1. Introduction

1.1 About This Document

This report presents a modernization analysis of Petra (OpenPetra), an open-source ERP platform serving non-profit organizations. The analysis was produced by Sage AI Technologies' modernization-planning workflow, which combines pre-computed Sage codebase intelligence with multi-agent reasoning to identify migration candidates, characterize the legacy system, and propose a target architecture on a modern .NET stack.

1.2 Candidate Selection Process

The workflow follows a multi-phase pipeline: (1) project intelligence (this section, plus Section 3), (2) candidate assembly driven by three independent subsystem-selection runs whose outputs are reconciled into a consensus pick (see Appendix A), (3) target architecture design, (4) behavioral rules extraction, and (5) technical examples for code, UI, and data mapping. For Petra, the candidate-selection problem space spans 27 documented business-function subsystems and 34 bounded contexts.

1.3 Report Contents

• Section 1 — Introduction (this section)
• Section 2 — Migration Scope (selected candidate subsystem)
• Section 3 — Legacy System Analysis
• Section 4 — Target Architecture (Azure App Service, .NET 8, Angular 18)
• Section 5 — Platform Affinity Analysis
• Section 6 — How Sage Helped This Migration Planning
• Section 7 — UI/UX Transformation Examples (jQuery → Angular 18)
• Section 8 — Code Translation Examples (.NET Framework 4.7 + .asmx → .NET 8 + minimal API)
• Section 9 — Data Mapping Strategy
• Section 10 — Business Rules Analysis
• Section 11 — Migration Execution & Legacy/Modern Coexistence
• Appendix A — Multi-Agent Subsystem Selection
• Appendix B — Service Architecture
• Appendix C — Deployment

1.4 What This Report Does NOT Include

• Cost estimates or budget figures.
• Effort estimates or delivery timelines.
• Specific cloud-account / tenancy / network-topology deployment plans.
• Vendor or product procurement recommendations.

1.5 About Petra (OpenPetra)

OpenPetra is a multi-tenant, multi-currency, multi-country ERP system for non-profit organizations. It manages contacts (donors, sponsors, volunteers, organizations, churches, banks, venues), donation processing with tax-deductible receipting, general-ledger accounting with year-end close, conference and event management (registration, accommodation, transportation), personnel and volunteer coordination, sponsorship programs (including sponsored-child management), and standardized + custom reporting. It is built as an n-tier client-server .NET application with a code-generation layer that transforms an XML master schema (petra.xml) into typed datasets, ORM classes, and RPC interfaces; the client is a JavaScript/jQuery web app that talks to an ASP.NET Web Services (.asmx, SOAP) layer hosted under Mono FastCGI on Linux, with a database-abstraction layer over PostgreSQL or MySQL.

2. Migration Scope

This report leverages Sage's deep insight into all 27 documented business-function subsystems in Petra (OpenPetra). A weighted scoring model was applied across each subsystem to find the right balance among migration risk, technical feasibility, and strategic value, with the goal of selecting a candidate slice for the first migration project — one that exercises the migration patterns the broader programme will rely on, demonstrates them on a meaningful business workflow, and stays within sensible blast-radius bounds for a pilot.

A single evaluation pass was conducted for this analysis; Sage’s three-pass consensus mode (which runs multiple independent scorings and reconciles them) is available for production engagements. The single-pass scoring is documented in Appendix A.

2.1 Why Finance — Gift Processing

Gift processing is OpenPetra's flagship donor workflow: a donor sends money, the back office reconciles a bank-statement import, posts a gift batch with motivations and tax-deductibility classification, and ultimately produces an annual tax receipt. Five distinct interactive web screens make up that flow:

• Gift Batches — entering and posting batches of donations with line-level allocation to motivations.
• Recurring Gift Batches — managing standing gifts and auto-generating periodic batches.
• Motivations Setup — the chart of motivation codes and motivation-detail-codes that drive how gifts are categorized and reported.
• Bank Import — importing bank statements (CAMT / MT940 / CSV) and matching transactions to expected gifts.
• Print Annual Receipts — generating tax-deductible receipts at year-end, per donor, with the right legal text per jurisdiction.

This is the right pilot for five reasons:

• End-to-end money-flow narrative. Bank import → gift batch → motivation classification → GL posting → annual receipt is a complete, recognizable donation processing workflow. It demos cleanly to non-profit prospects: a story about money and tax compliance, told screen-by-screen.
• Interactive UI surface that rewards modernization. Five distinct screens (versus one or two in most of the alternative slices) gives Section 7's UI/UX transformation analysis enough surface to demonstrate the AngularJS-to-Angular paradigm shift on real workflow forms — not on a single isolated maintenance dialog.
• Translation surface is large but tractable. Of the 279 files Sage associates with this subsystem, the hand-translated surface is roughly 23 server-side C# files (~15,000 lines), led by Gift.Transactions.cs (6,963 lines), Gift.Importing.cs (1,998), Gift.Receipting.cs (1,794), and Gift.Validation.cs (1,690). The remainder are XML report templates (45 files — template assets, ported through the template engine), SQL DDL / migration files (21 files — standard EF Core migration scope), and generated typed-dataset code that ports through the existing generation pipeline.
• Shared infrastructure across screens. All five screens use the same web connector (TGiftWebConnector), the same typed dataset (GiftBatchTDS), and the same RPC pattern (THttpConnector.CallWebConnector). Migrating five screens at once is roughly the cost of one connector port plus one typed-dataset port plus five Angular components — not five separate slices' worth of work.
• Compliance posture without live regulator dependency. Receipt content rules, gift-batch immutability after posting, multi-jurisdiction tax classification — these are real compliance requirements but they live in data and validation, not in real-time API calls to tax authorities. SEPA and DTAUS / MT940 are file-based imports/exports, not live integrations. The slice has compliance content (which the migration must preserve) but not live-regulator risk on the critical path.

2.2 What is in scope for the pilot

2.3 What is out of scope (kept on the legacy side via strangler-fig bridge)

• Partner aggregate — donor identity is consumed by the gift slice (read-only via the strangler bridge to the legacy partner store), not authored. Migrating Partner first would force every other slice to federate through the new identity store and is deferred to a later wave.
• General Ledger postings — the gift slice produces GL posting records via an internal interface. The GL itself remains on the legacy side until a dedicated finance migration wave.
• Bank-account master data — configuration; read-only consumer.
• Donations Processing tag — per the project-intel analysis, this Sage tag is sparse and the real surface lives under Finance — Gift Processing. There is no separate Donations Processing slice to consider.

2.4 Why this pilot is right-sized

• Bigger than the smallest possible pilot, smaller than the largest meaningful one. Sponsorship — Child Management (12 files, 1 screen) is the smallest defensible slice in Petra and was an excellent pure-engineering pilot — but it does not exercise enough UI surface to make Section 7's modernization narrative compelling, and the dominant user-facing surface (a child-photo-upload editor sitting atop a sponsored-child program with photos of minors) is not the right material for a prospect-facing demo. Gift Processing's five screens with end-to-end donor flow are the right size for a pilot that has to also serve as demonstration material.
• Smaller than Finance — Accounting (370 files) or Partner — Contacts Management (211 files) or System Management — Users (390 files). Those are the truly large subsystems whose risk profile rules them out as pilots. Gift Processing's hand-translation surface (~28 files of real translation work) is tractable.
• Pattern reusability across the rest of the programme. Patterns proven on this slice — typed-dataset port, .asmx-to-minimal-API port, jQuery+modal-to-Angular-component port, file-import flows, batch-state machines, multi-screen Angular routing — reapply directly to Finance — Banking, Finance — Accounting, Donations / extracts, and any other multi-screen workflow in the catalog.

See Appendix A for the complete scoring methodology, the 27-subsystem scoring matrix with interactive-UI-surface column, and detailed rationale for why the alternatives were ranked as they were.

3. Legacy System Analysis

The following legacy system analysis was generated by Sage AI.

3.1 High-Level System Architecture

OpenPetra is a layered, n-tier client-server .NET application with a code-generated data-access layer. The browser-based client (JavaScript + jQuery) makes HTTP RPC calls to an ASP.NET Web Services (.asmx, SOAP) layer; the server hosts module-specific Web Connectors (e.g., TSponsorshipWebConnector, TGiftTransactionWebConnector, TBankImportWebConnector) that delegate to typed-dataset ORM classes generated from a master XML schema (petra.xml). A database-abstraction layer fronts PostgreSQL or MySQL.

flowchart TB
  subgraph Client["Browser Client (jQuery + HTML)"]
    UI["Form Templates & Controllers"]
    Axios["HTTP RPC dispatcher"]
  end

  subgraph Server["ASP.NET Web Services (Mono FastCGI on Linux)"]
    SOAP[".asmx SOAP endpoints
(per-module: MFinance, MPartner, MPersonnel, MConference, MSysMan, MReporting)"]
    WC["Web Connectors
(T*WebConnector RPC classes)"]
    Sec["Security & Session
(TOpenPetraOrgSessionManager,
RequireModulePermission)"]
  end

  subgraph App["Application Layer"]
    Finance["Finance: GL, Gift, AP, Budget,
Currency, Tax (61.6K LOC)"]
    Partner["Partner Management
(32.6K LOC)"]
    Conference["Conference Management"]
    Personnel["Personnel / Volunteers"]
    Reporting["Reporting Engine
(XML templates + DTD)"]
  end

  subgraph Data["Data Layer"]
    DAL["Code-generated DAL
(typed datasets + ORM)"]
    DBAccess["DBAccess / TDBTransaction"]
    Schema["petra.xml master schema
+ generated DDL"]
  end

  subgraph DB["Database"]
    PG["PostgreSQL (primary)"]
    MY["MySQL"]
    SQ["SQLite"]
  end

  UI --> Axios
  Axios -- "HTTP RPC
JSON / SOAP" --> SOAP
  SOAP --> WC
  WC --> Sec
  WC --> Finance
  WC --> Partner
  WC --> Conference
  WC --> Personnel
  WC --> Reporting
  Finance --> DAL
  Partner --> DAL
  Conference --> DAL
  Personnel --> DAL
  Reporting --> DAL
  DAL --> DBAccess
  Schema -. "code-gen" .-> DAL
  DBAccess --> PG
  DBAccess --> MY
  DBAccess --> SQ
  

3.2 Architectural Layers

From Sage's architecture tree, OpenPetra distributes 400,437 cataloged lines across the following top-level layers:

Two structural notes worth carrying into target design: (1) a sizeable Code Generation branch (12.4K lines) drives the typed-dataset DAL from petra.xml — this is a build-time pipeline that any modernization must either reproduce, retire, or replace with EF Core scaffolding; (2) the Report Templates branch (43.5K lines of XML reports) is presentation-layer mass that significantly inflates the "UI" footprint relative to the actual interactive forms (the web client itself is ~9.4K lines).

3.3 Data Entities

Sage identifies 48 aggregate roots across 34 bounded contexts with 100% structural evidence. The top entities by relationship count and embedded business-rule density are:

The five highest-cohesion bounded contexts (microservice candidates per Sage):

graph LR
  PM["PersonnelManagement
(12 entities)"]
  UAM["UserAccessManagement
(10 entities)"]
  DA["DatabaseAbstraction
(9 entities)"]
  FM["FinancialManagement
(9 entities)"]
  CEM["ConferenceEventManagement
(8 entities)"]

  Partner((Partner
17 rels))
  Partner --- PM
  Partner --- FM
  Partner --- CEM
  Partner --- UAM

  GL((GeneralLedger))
  GL --- FM

  Conf((ConferenceAccommodation))
  Conf --- CEM

  Staff((PersonnelStaff))
  Staff --- PM

  UA((UserAccount))
  UA --- UAM
  

Note Partner's centrality: it is the connective tissue across PersonnelManagement (volunteers/staff are Partners), FinancialManagement (donors are Partners), ConferenceEventManagement (attendees are Partners), and UserAccessManagement (user accounts link to Partners). Any decomposition strategy must sequence Partner extraction first or accept a shared-data dependency across multiple new services.

3.4 Business Rules & Behavior

This section is populated in detail by the behavioral-rules phase (Section 9). Sage's domain-entity insight reports 265 business rules enforced across the 48 aggregate roots, with an average of 5.5 rules per entity. High-density rule clusters live around Partner (15 rules), Report (10), Translation (9), GeneralLedger (8), PersonnelStaff (8), UserAccount (8), and SponsoredChild (8). The behavioral-rules phase will extract, classify, and assign BR-XXX identifiers to each.

3.5 Technology Stack

3.6 Integration Patterns

Sage identifies 151 integration points across 216 files with an 89% structural-evidence rate. The dominant pattern is bidirectional Web Connector RPC over HTTP (jQuery client ↔ .asmx server); behind that sit file-based integrations (bank statement formats, XML report templates, code-gen) and database-protocol integrations to PostgreSQL/MySQL. Direction breakdown: 83 bidirectional, 46 inbound, 22 outbound.

flowchart LR
  Browser["jQuery Client
(Axios HTTP RPC)"]
  Browser -- "POST /api/<module>/<method>" --> SOAP

  subgraph SOAP["ASP.NET .asmx SOAP layer"]
    MF["serverMFinance.asmx"]
    MP["serverMPartner.asmx"]
    MPe["serverMPersonnel.asmx"]
    MC["serverMConference.asmx"]
    MR["serverMReporting.asmx"]
    MS["serverMSysMan.asmx"]
  end

  SOAP --> WCs["Web Connectors
(TGiftTransactionWebConnector,
TSponsorshipWebConnector,
TBankImportWebConnector,
TImportExportWebConnector,
TReportGeneratorWebConnector,
...)"]

  WCs --> DAL["Typed Datasets / DAL
(generated from petra.xml)"]
  DAL --> DB[("PostgreSQL / MySQL / SQLite")]

  Banks[/"Bank statement files
CAMT, MT940, CSV, ZIP"/] --> WCs
  XMLReports[/"XML report templates
+ reports.dtd"/] --> WCs
  WCs --> Out[/"Exports: PDF, Excel,
HTML, YML.GZ backup,
SEPA direct debit"/]

  Systemd[["systemd / fastcgi-mono-server4 / nginx"]] -.hosts.- SOAP
  

Key observations for migration planning:

• HTTP-routable surface. Every client/server interaction crosses an HTTP RPC boundary — classical strangler-fig is admissible. New Angular/.NET 8 endpoints can be slotted in behind a reverse proxy and swapped slice by slice.
• SOAP is the protocol, not the architecture. Despite the .asmx wrapping, the calls are JSON-over-HTTP RPC dispatched by THttpConnector.CallWebConnector with module/method routing. The SOAP envelope can be peeled off without changing the call semantics.
• High coupling to Partner. 83/151 integrations are bidirectional and the Partner aggregate touches 17 other entities. Service decomposition will cross the Partner boundary repeatedly; expect either a Partner-first extraction or a shared Partner reference data service.
• Code-gen is load-bearing. The DAL and a meaningful share of the RPC surface are generated from petra.xml. Modernization must decide whether to retain the schema-first generator (port it to T4 or source generators on .NET 8) or replace it with EF Core code-first conventions.
• File-format integrations are bank- and report-heavy. CAMT/MT940/SEPA processing and the 43.5K-line XML report library are domain-specific assets, not generic glue — their migration is closer to feature-port than refactor.

Sources: Sage MCP get_project_metadata, get_project_architecture_tree_and_line_count, get_insight (domain_entity, integration), get_project_business_function_subjects, get_project_technology_subjects. Project key petra.

4. Target Architecture

4.1 Introduction

This section specifies the target cloud architecture for the modernized Finance — Gift Processing subsystem. The slice is OpenPetra’s flagship donor money-flow: a donor sends money → a back-office user reconciles a bank-statement import → a gift batch is entered, validated, and posted → motivations classify each line for tax and reporting purposes → the General Ledger receives the posting → at year-end a tax-deductible annual receipt is rendered for every donor. Five interactive web screens (Gift Batches, Recurring Gift Batches, Motivations Setup, Bank Import, Print Annual Receipts) plus a back-office batch-rendering surface (annual-receipt PDFs, SEPA Direct Debit export, ICH international gift export) make up the in-scope footprint.

The target deploys to Azure App Service with Azure Database for PostgreSQL Flexible Server as the primary data store. PostgreSQL is preserved as the database engine — the legacy system is already on it — and the gift-domain schema (a_gift_batch, a_gift, a_gift_detail, a_motivation_group, a_motivation_detail, a_recurring_gift_batch, etc.) is preserved end-to-end. This is a deliberate contrast with a green-field domain like Sponsorship: the gift schema is the system-of-record for donations and posted batches, it’s mature and battle-tested, and it’s shared with downstream finance reporting. The modernization is server-side and client-side, not data-side.

4.1.1 Donor Money-Flow Diagram

Before any technical layering, this is the workflow the new architecture has to support — end-to-end, the same donation moves through these stages:

flowchart LR
  D["Donor"]
  BANK["Bank
(CAMT/MT940/CSV)"]
  BIMP["Bank Import
(reconciliation)"]
  BATCH["Gift Batch
(unposted → posted)"]
  MOT["Motivations
(tax + reporting
classification)"]
  GL["General Ledger
(posting)"]
  RCPT["Annual Receipt
(PDF, multi-lang)"]
  SEPA["SEPA Direct Debit
(recurring gifts)"]
  ICH["ICH Export
(cross-border gifts)"]

  D -- "donates" --> BANK
  BANK -- "statement file" --> BIMP
  BIMP -- "match & create" --> BATCH
  D -- "standing order" --> SEPA
  SEPA -- "creates" --> BATCH
  BATCH -- "uses" --> MOT
  BATCH -- "post" --> GL
  BATCH -- "year-end" --> RCPT
  BATCH -- "cross-border" --> ICH
  RCPT -. "to donor" .-> D
  

Five of these stages (Bank Import, Gift Batch, Motivations, Annual Receipt, recurring-gift batch entry that drives SEPA) are interactive web screens in the legacy. Two (the GL posting target and the bank itself) are integration boundaries to subsystems that remain on the legacy side during this migration wave. The new architecture preserves every box and every arrow; what changes is the implementation underneath each interactive box and the way the back-office batch boxes (Annual Receipt, SEPA, ICH) are operated.

4.1.2 Design Principles

1. Preserve the gift schema, replace the access layer. The gift-domain tables (a_gift_batch, a_gift, a_gift_detail, motivation tables, recurring-gift tables) are the system of record for donations and are shared with downstream finance reporting. They stay. The code-generated typed dataset GiftBatchTDS (derived from petra.xml + the gift typed-dataset XML) is replaced with EF Core 8 entities mapped to the same physical tables. Net-new tables in this slice are intentionally minimal — in contrast with a green-field domain where the schema is being designed for the first time.
2. Right-size to the workload shape. The slice has two genuinely different workload shapes — synchronous interactive batch-entry / validation / posting on one side, and asynchronous / batch-mode file-rendering and file-ingestion on the other (annual receipts, SEPA export, CAMT import, ICH export). The target reflects this with two services rather than collapsing both into one. Service granularity is finalized in Appendix B.
3. HTTP-routable strangler-fig coexistence. Per Sage’s project intelligence and the .NET / AngularJS source profile’s preferred coexistence pattern, every Petra client/server interaction crosses an HTTP RPC boundary. The Azure-fronted routing tier (Azure Front Door + API Management) directs /api/gift/* traffic to the new gift services and lets every other module continue to terminate at the legacy Mono FastCGI / .asmx endpoints. Coexistence specifics are owned by Section 11.
4. Decompose batch rendering off the request path. Annual-receipt PDF generation, SEPA file generation, and bank-statement-file ingestion (ZIP/CAMT) are batch-mode workloads — they should not run synchronously on a user-facing API request. The target places them behind a queued worker (Azure Service Bus + an App Service worker), with the interactive surface returning a job handle and polling for completion.
5. GL is consumed, not authored. The General Ledger remains on the legacy side. The new gift-processing service writes posting records to the GL via the existing internal interface (federated REST during coexistence; later, a dedicated GL service migration). The gift slice does not implement GL.
6. Donor identity is consumed, not authored. The Partner aggregate (the central entity in the project, 17 relationships, 0.91 confidence per Sage’s project intelligence) is read-only from the gift services for donor identity, addresses, partner-class-driven motivation defaults, and confidential-gift privacy joins. The Partner aggregate is migrated in a later wave; until then, federated reads against the legacy partner store.
7. Validation, observability, and error handling at every API boundary. All inbound and outbound calls are validated, traced, and structured-logged. Domain exceptions map to RFC 7807 problem responses. Posted-batch-immutability, sequential-batch-numbering, financial-period-validation, and tax-deductible-percentage bounds checking are implemented as typed domain rules — not return codes — and surface in span attributes when they fire.

4.1.3 Subsystem-specific Scope (committed)

4.2 Architecture Diagram

The target is a single Angular 18 SPA that calls two ASP.NET Core 8 services hosted on Azure App Service: a synchronous gift-processing-service for the interactive batch-entry / motivations / recurring-gift surface, and an asynchronous batch-mode gift-receipting-service for annual-receipt rendering, SEPA Direct Debit export, ICH export, and bank-statement-file ingestion. Both services share the gift-domain PostgreSQL schema; rendered files and bank-import staging are externalised to Azure Blob Storage; receipt generation, SEPA export, and CAMT import dispatch through Azure Service Bus to a worker.

flowchart TB
  subgraph Browser["Browser"]
    NGUI["Angular 18 SPA
(Gift Batches · Recurring ·
Motivations · Bank Import ·
Annual Receipts)"]
  end

  subgraph Edge["Azure Edge"]
    AFD["Azure Front Door
(WAF + TLS)"]
    APIM["API Management
(JWT, quota, route table)"]
  end

  subgraph AppPlan["Azure App Service Plan (Linux, P1v3)"]
    GPS["gift-processing-service
ASP.NET Core 8 (Minimal API)
batches · recurring · motivations ·
donor extracts"]
    GRS["gift-receipting-service
ASP.NET Core 8 worker
annual receipts · SEPA export ·
ICH export · bank import"]
  end

  subgraph LegacyZone["Legacy Co-existence Surface (Section 11)"]
    LEG["Petra .asmx / Mono FastCGI
(MPartner, MFinance/GL,
System Mgmt, etc.)"]
  end

  subgraph Data["Data & Storage (Azure)"]
    PG[("Azure Database for
PostgreSQL Flexible Server
(gift schema preserved)")]
    BLOB[("Azure Blob Storage
(receipts · SEPA files ·
bank-statement uploads)")]
    KV["Azure Key Vault"]
    REDIS["Azure Cache for Redis
(motivation lookups,
session, idempotency)"]
    SB[/"Azure Service Bus
(receipt-batch · sepa-export
· bank-import queues)"/]
  end

  subgraph Obs["Observability"]
    AI["Application Insights"]
    LAW["Log Analytics Workspace"]
  end

  NGUI -- "HTTPS" --> AFD
  AFD --> APIM
  APIM -- "/api/gift/*" --> GPS
  APIM -- "/api/gift/receipts/*
/api/gift/sepa/*
/api/gift/bank-import/*" --> GRS
  APIM -- "everything else" --> LEG

  GPS -- "EF Core 8 / Npgsql" --> PG
  GPS -- "queue jobs" --> SB
  SB -- "consume jobs" --> GRS
  GRS -- "EF Core 8 / Npgsql" --> PG
  GRS -- "rendered PDFs / SEPA XML / staged uploads" --> BLOB
  GPS -- "session + ref data" --> REDIS
  GPS -- "GL post (REST)" --> LEG
  GPS -- "Partner identity (REST)" --> LEG
  GPS -- "secrets" --> KV
  GRS -- "secrets" --> KV
  GPS -- "OTLP / ILogger" --> AI
  GRS -- "OTLP / ILogger" --> AI
  AI --> LAW
  LEG -. "shared DB during
strangler phase" .-> PG
  

Service granularity (count and boundary) is finalized by the service-architecture phase. This diagram reflects the Section 4 working assumption of two modernized services — a synchronous interactive service and an asynchronous batch worker — based on the genuinely different workload shapes inside the slice. See Appendix B for the resolved decomposition.

4.3 Technology Stack

4.3.1 Code-Level Architecture Decisions

The resolved target patterns below combine: (a) defaults from Sage’s target-architecture pattern library (which assume a Python target by default and so were translated to their .NET 8 / Angular 18 equivalents pragmatically), (b) Azure App Service-specific overrides inferred from analogous container-platform templates, and (c) the engagement’s explicit target-architecture commitments (no plan-level pattern overrides applied).

4.4 Data Model

This slice has a fundamentally different data-model story from a green-field domain like Sponsorship. The gift-domain schema is preserved, not redesigned. The existing tables (a_gift_batch, a_gift, a_gift_detail, a_motivation_group, a_motivation_detail, a_recurring_gift_batch, a_recurring_gift, a_recurring_gift_detail) are the system of record for OpenPetra donations: they hold posted financial transactions, they’re shared with downstream finance reporting, and they have years of operational history. The migration replaces the access layer (typed datasets → EF Core) and the API surface (.asmx Web Connector → ASP.NET Core endpoints) without disturbing the physical schema.

Net-new tables in this slice are deliberately minimal. We add only what’s needed to support the queued-worker pattern (a job-tracking table) and to capture metadata that the legacy stored only in filesystem paths or session state (rendered-receipt and uploaded-statement provenance).

4.4.1 Gift-domain ER (preserved physical schema)

erDiagram
  PARTNER ||--o{ GIFT_BATCH : "gl_effective"
  PARTNER ||--o{ GIFT : "donor_partner_key"
  PARTNER ||--o{ GIFT_DETAIL : "recipient_partner_key"
  GIFT_BATCH ||--o{ GIFT : "contains"
  GIFT ||--o{ GIFT_DETAIL : "has lines"
  MOTIVATION_GROUP ||--o{ MOTIVATION_DETAIL : "categorises"
  MOTIVATION_DETAIL ||--o{ GIFT_DETAIL : "classifies"
  RECURRING_GIFT_BATCH ||--o{ RECURRING_GIFT : "contains"
  RECURRING_GIFT ||--o{ RECURRING_GIFT_DETAIL : "has lines"
  PARTNER ||--o{ RECURRING_GIFT : "donor_partner_key"

  PARTNER {
    bigint partner_key PK "legacy p_partner.p_partner_key_n"
    string partner_class "FAMILY|PERSON|ORG"
    string partner_short_name
    string status_code
  }

  GIFT_BATCH {
    int ledger_number PK "FK to a_ledger"
    int batch_number PK "sequential per ledger"
    date batch_effective_date
    string batch_status "Unposted|Posted|Cancelled"
    string currency_code "ISO 4217"
    decimal exchange_rate_to_base
    string method_of_payment
    string created_by
    datetime created_at
    datetime posted_at "nullable"
  }

  GIFT {
    int ledger_number PK
    int batch_number PK
    int gift_transaction_number PK
    bigint donor_partner_key FK
    string method_of_giving
    date date_entered
    boolean confidential
    string receipt_letter_code
    boolean receipt_print_flag
  }

  GIFT_DETAIL {
    int ledger_number PK
    int batch_number PK
    int gift_transaction_number PK
    int detail_number PK
    bigint recipient_partner_key FK
    int recipient_ledger_number
    string motivation_group_code FK
    string motivation_detail_code FK
    decimal gift_transaction_amount "transaction currency"
    decimal gift_amount "base currency"
    decimal gift_amount_intl "intl currency (ICH)"
    decimal tax_deductible_pct "0..100"
    boolean modified_detail "for adjustment-filtering"
  }

  MOTIVATION_GROUP {
    string motivation_group_code PK
    string motivation_group_description
    boolean group_status
  }

  MOTIVATION_DETAIL {
    string motivation_group_code PK
    string motivation_detail_code PK
    string motivation_detail_description
    boolean tax_deductible
    string default_account_code "GL account"
    string default_cost_centre_code
  }

  RECURRING_GIFT_BATCH {
    int ledger_number PK
    int recurring_batch_number PK
    string description
    string frequency "Monthly|Quarterly|Annual|..."
  }

  RECURRING_GIFT {
    int ledger_number PK
    int recurring_batch_number PK
    int recurring_gift_number PK
    bigint donor_partner_key FK
    date start_date
    date end_date "nullable"
    boolean active
    string sepa_mandate_reference "varchar(35)"
    date sepa_mandate_given "nullable"
  }

  RECURRING_GIFT_DETAIL {
    int ledger_number PK
    int recurring_batch_number PK
    int recurring_gift_number PK
    int detail_number PK
    bigint recipient_partner_key FK
    string motivation_group_code FK
    string motivation_detail_code FK
    decimal gift_amount
    string currency_code
  }
  

4.4.2 Net-new tables (gift-services-owned)

These are the only schema additions in this wave. They support the queued-worker pattern and capture provenance the legacy stored ad-hoc.

erDiagram
  RENDER_JOB ||--o| RENDERED_RECEIPT : "produces"
  RENDER_JOB ||--o| SEPA_EXPORT_FILE : "produces"
  BANK_IMPORT_UPLOAD ||--o{ BANK_IMPORT_LINE : "extracts"
  BANK_IMPORT_LINE ||--o| GIFT_DETAIL : "matches (optional)"

  RENDER_JOB {
    uuid job_id PK
    string job_kind "ANNUAL_RECEIPT|SEPA_EXPORT|ICH_EXPORT"
    int ledger_number
    int year "for annual receipts"
    string status "Queued|Running|Succeeded|Failed"
    string requested_by_user_id
    datetime requested_at
    datetime completed_at "nullable"
    text failure_reason "nullable"
  }

  RENDERED_RECEIPT {
    uuid receipt_id PK
    uuid job_id FK
    int ledger_number
    int year
    bigint donor_partner_key FK
    string locale_code "en|de|nb|da|..."
    string blob_uri "Azure Blob URI"
    bigint size_bytes
    string sha256
    datetime rendered_at
    datetime immutable_until "tax-audit retention"
  }

  SEPA_EXPORT_FILE {
    uuid sepa_file_id PK
    uuid job_id FK
    int ledger_number
    int recurring_batch_number
    date collection_date
    string blob_uri
    int mandate_count
    decimal total_amount
    string currency_code
    datetime exported_at
  }

  BANK_IMPORT_UPLOAD {
    uuid upload_id PK
    string original_filename
    string format "CAMT|MT940|CSV|ZIP"
    string blob_uri "raw file in Blob"
    bigint size_bytes
    string uploaded_by_user_id
    datetime uploaded_at
    string status "Parsed|MatchingComplete|Discarded"
  }

  BANK_IMPORT_LINE {
    uuid line_id PK
    uuid upload_id FK
    int line_number
    date transaction_date
    decimal amount
    string currency_code
    string remitter_name
    string remitter_iban
    text reference_text
    int matched_ledger_number "nullable"
    int matched_batch_number "nullable"
    int matched_gift_transaction_number "nullable"
    string match_status "Unmatched|AutoMatched|UserMatched|Rejected"
  }
  

4.4.3 Table-by-table sketch

4.4.4 Indexing strategy

• a_gift_batch (ledger_number, batch_status, batch_effective_date) — supports the “unposted batches in this period” landing query and the field-adjustment filter on batch_status = 'Posted'.
• a_gift_detail (recipient_partner_key, modified_detail) — supports adjustment-processing’s recipient-side queries (per UnmodifiedDetailFilterConstraint, conf 0.89).
• a_gift (donor_partner_key, date_entered DESC) — supports donor-history queries used by the receipt printer (per Gift.ReceiptPrinting.GetDonationsOfDonor.sql evidence).
• a_motivation_detail (motivation_group_code, motivation_detail_code) — primary-key access pattern, plus a covering index on (default_account_code, default_cost_centre_code) for the cross-reference report queries.
• render_job (status, requested_at) — supports the worker’s “next queued job” poll and the admin “recent failed jobs” list.
• bank_import_line (upload_id, match_status) — supports the user-facing “unmatched transactions” queue.
• Trigram or pg_trgm index on partner-name fields used by donor-extract LIKE-pattern searches (per the legacy TypeAheadSearchPattern, conf 0.85). The legacy implementation does multi-field LIKE without index support; PostgreSQL pg_trgm brings these queries into sub-second territory at production volumes.

For detailed schema mappings from legacy petra.xml-generated typed datasets and the existing PostgreSQL a_gift_* / a_motivation_* DDL to this target data model (and the six net-new operational tables), see Section 10: Data Mapping Strategy.

4.5 Service Architecture

5. Platform Affinity Analysis

Platform affinity analysis classifies each constraint discovered in the legacy codebase as either platform-driven (an artifact of the .NET Framework 4.7 / Mono FastCGI / jQuery / NAnt environment that serves no business purpose) or business-driven (a genuine requirement that must be preserved). Getting this distinction wrong leads to one of two failure modes: replicating unnecessary limitations in the modern system, or accidentally breaking business rules that were disguised as platform constraints.

Petra is a semi-modern .NET codebase — not terminally legacy, but decaying along identifiable axes (deprecated frameworks, security-relevant version drift, runtime-imposed dependency ceilings). Section 6 surfaced 7 architectural concerns and audited 37 dependencies; this section curates the subset where the target architecture (.NET 8 + Angular 18 on Azure App Service, with Microsoft Entra ID, PostgreSQL Flexible Server, and Azure Service Bus) breaks a constraint that the legacy stack imposes. The dominant patterns that recur across most entries are two strategic ceilings working in tandem: the .NET Framework 4.7 runtime ceiling (collapses a long tail of NuGet pins and polyfills the moment the slice moves to .NET 8) and the synchronous in-process request pipeline (collapses the annual-receipt-run and bank-import flows from request-monopolising operations into queued, independently-scaled workloads).

5.1 Capacity Constraints

5.1.1 .NET Framework 4.7 NuGet Ecosystem Ceiling

<!-- we cannot update to 5.x because that only supports .net 5 -->
<package id="Npgsql" version="4.1.10" />

<!-- don't go to 3.16.x because that requires dotnet -->
<package id="NUnit" version="3.13.3" />

<!-- do not update to 1.4.x, because that requires .net 6.0 -->
<package id="SharpZipLib" version="1.3.3" />

5.1.2 SharpZipLib 1.3.3 + PDFsharp 1.50 — In-Slice Library Ceilings

5.2 Processing Model Constraints

5.2.1 Synchronous In-Process Request Pipeline for Batch Workloads

5.2.2 Mono FastCGI Hosting on Linux

5.2.3 Server-Side Session-Bound Authentication

5.2.4 NAnt Build Pipeline + In-Repo Development Tooling

5.3 User Interface Constraints

5.3.1 jQuery + ES5 Web Client Ceiling

5.3.2 Bootstrap 4 EOL + Browserify / popper.js Build Chain

5.3.3 axios 0.21.x with Documented CVEs

5.4 Data Type Constraints

5.4.1 XML-Driven Code-Generated Typed Datasets (Preserve-Schema Variant)

5.4.2 Newtonsoft.Json 13.x as Default Serializer

5.4.3 Multi-Currency Three-Amount Numeric Precision

← Back to Table of Contents

6. Technical Debt Analysis

The architectural concerns and strengths in 6.2–6.6 are sourced from Sage AI’s project-level architectural assessment (LLM confidence 0.85). The catalog itself is project-wide and cycle-stable; what changes between analyses is the classification of each concern against the committed target architecture. 6.5 is sourced from Sage’s anti-pattern check library for the .NET / AngularJS source profile. 6.7 is sourced from manifest-file scanning of Petra’s repository. Classifications against the target architecture trace to the target-architecture analysis (Section 4) — committed Azure App Service / .NET 8 / Angular 18 stack for the Finance — Gift Processing slice (two-service split: gift-processing-service + gift-receipting-service worker).

6.1 Methodology

This section distills Petra’s technical debt into a stakeholder-readable view across two distinct categories:

• Architectural debt (6.2–6.6) — patterns and design choices that create cost, risk, or constraint at the system level. The data source is Sage’s project-level architectural assessment, which surfaces severity-ranked Areas of Concern grounded to specific architectural elements, balanced by an explicit list of Architectural Strengths.
• Library/version debt (6.7) — specific outdated dependencies discovered by scanning Petra’s manifest files (*.csproj, packages.config, package.json). This is the bill-of-materials view: which packages have known migration paths, which are EOL, which carry CVE history.

These are different stakeholder framings. Architectural debt informs strategy (do we replace the layer? rewrite the slice? wrap and isolate?). Library debt informs execution (what version-bumps and replacements does the migration ship?). Both classifications below are scoped against the same proposed target architecture.

Each architectural concern is classified using a four-bucket framework:

• Retired by target — the target architecture removes the cause; the debt is gone post-migration.
• Mitigated by target — the target reduces the impact (e.g., adds observability, isolates new code from a persistent legacy pattern, replaces a chunk of the affected surface) but the underlying complexity remains in legacy zones.
• Inherited — the target keeps the pattern; the debt persists. Stakeholders deserve the honest read.
• Out of scope — the concern is real but is not addressed by this engagement’s migration scope; tracked as future-investment.

Each library/version entry is classified on two axes (lifecycle status × target action) — see 6.7 for details.

What this section is not: it is not a code-quality lint report, not a comprehensive security audit, not a defect list. It is a debt assessment scoped to architectural-level patterns and dependency-level lifecycle status. The Petra source profile (dotnet-angularjs) is framed as semi-modern — the codebase is not terminally legacy, but it is decaying in identifiable, defensible ways.

Scope note for classification. The committed migration scope (Section 4) is the Finance — Gift Processing slice, decomposed into two services: gift-processing-service (synchronous interactive surface — five web screens for gift batch entry, recurring gifts, motivations, donor extracts, and federation reads) and gift-receipting-service (asynchronous queued worker handling annual-receipt rendering, SEPA Direct Debit XML export, ICH multi-currency export, and bank-statement import). Concerns and dependencies whose architectural element falls outside that slice are classified Out of scope / Outside slice: real debts that the modernized slice does not touch. This is the honest read — the slice retires what it retires, and the rest is future investment.

6.2 Severity-ranked concerns (architectural)

Seven architectural concerns surfaced, distributed as one high-severity, four medium-severity, and two low-severity. Highest severity first.

Classification totals: Retired by target: 2 · Mitigated by target: 4 · Inherited: 0 · Out of scope: 1.

Why the distribution shifts compared to a Sponsorship-style slice. The Gift Processing slice sits squarely on the Finance Management surface (D-02) and on the chunk of the report-template estate that drives annual receipts (D-03). A slice that did not touch Finance Management or annual-receipt rendering would honestly classify both concerns as Out of scope. This slice does touch them — partially — so the honest read is Mitigated by target: the cause is not eliminated, but a real share of it is rebuilt with modern observability, structured exceptions, and a queued-worker pattern. D-04 (Partner Management transaction-coordination) remains Out of scope because Partner identity authoring is explicitly preserved on the legacy side.

6.3 Detailed concern narratives

D-01 (high): Web Client built on jQuery + ES5 (Presentation Layer.Web Client) — Retired by target

The browser-side client is built on jQuery and vanilla ES5 JavaScript — no module system, no component framework, no type system, no first-class testability surface. This is not a lint complaint; it is an architectural ceiling. Petra’s interactive UI lives in roughly 6,682 lines of hand-written DOM-manipulation code that lacks the structural primitives (components, props, reactive state, dependency injection) which any modern frontend assumes. The practical consequences are visible in three places: developer onboarding is slow because new contributors cannot rely on framework conventions; UI consistency drifts because each screen re-implements its own state management; and ecosystem reach narrows because libraries built for the modern era either don’t fit or require adapter shims.

This is the only high-severity concern Sage surfaced and it is the one with the cleanest exit ramp in the target architecture. Section 4 commits the client stack to Angular 18 with TypeScript 5.4, standalone components, signals-based reactivity, and the new @if/@for control flow. The Gift Processing slice rebuilds five distinct interactive screens — Gift Batches, Recurring Gift Batches, Motivations Setup, Bank Import, and Print Annual Receipts — as Angular 18 standalone components with lazy-loaded feature modules. The target-architecture handoff explicitly lists the legacy jQuery + Bootstrap-modal forms for these five screens under What’s retired. For the modernized gift-processing-service the jQuery + ES5 surface is gone, not merely upgraded.

Honest qualifier: this classification scopes to the slice the migration actually delivers. Legacy zones (Partner authoring, GL accounting, Conference, Personnel, Reporting subsystem outside the gift-receipt subset) continue to use jQuery during the strangler-fig coexistence phase per Section 4 and Section 11. The route table at the Azure API Management edge sends /api/gift/* traffic to the new Angular SPA and everything else to the legacy client — both surfaces coexist behind the same edge until subsequent slices are migrated. The high-severity debt is retired for what was migrated; whole-codebase elimination is a function of how many subsequent slices ship.

D-02 (medium): Finance Operations Engine performance under high transaction volumes (Application Layer.Finance Management) — Mitigated by target

Petra’s Finance Operations Engine (~49,362 lines, 17.2% of the cataloged codebase) carries multi-currency revaluation, gift-batch posting, ICH processing, year-end closing, and budget-period workflows. Sage flags it as a potential performance bottleneck under high transaction volumes — complex calculations are computed inline in service-facade methods rather than queued or sharded, and the multi-currency path crosses the Database Abstraction Layer for every conversion lookup.

The Gift Processing slice changes this concern’s classification compared to a slice that did not touch Finance Management. Gift batch posting, the multi-currency three-amount pattern (transaction / base / international), recurring-gift posting, motivation-detail GL defaulting, and the SEPA Direct Debit / ICH export pipelines all sit inside this engine — and they are inside the slice. The target architecture preserves the calculations themselves (Section 4’s preserve-schema decision is a deliberate choice: gift-domain math is regulator-aware and golden-master tested), but it puts modern infrastructure around them. Multi-currency calculations move into an EF Core 8 / .NET 8 service with structured logging, OpenTelemetry tracing across HTTP and Service Bus, an explicit domain-exception hierarchy mapped to RFC 7807 problem responses, and golden-master tests for batch posting and tax-deductible calculation. The performance bottleneck risk is contained by moving the worst offenders — annual-receipt rendering, SEPA export, bank-statement import — off the request thread and into the gift-receipting-service worker behind three Service Bus queues with independent App Service plan scaling.

Critical honesty note: the calculations are not rewritten. The complexity Sage flagged is not eliminated — it is observed, scaffolded, and isolated from interactive latency budgets. GL posting still flows back to legacy MFinance via federated REST (the only write to legacy from the new services), so a portion of the engine’s computational surface continues to live on the legacy stack. This is the canonical case of mitigated rather than retired: the slice ships measurable improvements in observability, scalability, and failure isolation; the underlying calculation complexity persists where the legacy boundaries persist.

D-03 (medium): XML Report Template Definitions sprawl (Presentation Layer.Report Templates) — Mitigated by target

~39,992 lines (14.0% of cataloged) live in XML report templates. Sage flags this as maintenance overhead and potential consistency risk: each template re-declares its queryDetail hierarchy, formatters, and parameter bindings, and there is no schema-level enforcement that two reports with the same fact format it identically.

The Gift Processing slice does not retire the XML Report Template estate wholesale — donor extracts, gift summary reports, and the broader Reporting subsystem remain on the legacy template engine. But annual-receipt generation is a meaningful portion of the template estate, and the slice replaces it. The target architecture moves annual-receipt rendering out of the inline XML / HTML template engine and into gift-receipting-service as a queued PDF-rendering job (QuestPDF or PuppeteerSharp, with library selection deferred to Section 8), backed by a render_job table for status, a rendered_receipt provenance table with SHA-256 hash and immutable-until timestamps, and Azure Blob Storage with an immutability policy for tax-audit retention. Per-locale receipt templates (German / English / Norwegian) move from PO-file-driven in-template substitution to .NET IStringLocalizer resources plus per-locale template files in Blob.

The slice therefore retires the annual-receipt subset of the XML template sprawl — perhaps 5–10% of the ~40K-line estate, with concrete operational benefits (provenance, immutability, batch retry via dead-letter queue). The remaining ~90%+ of XML report templates — donor extracts, gift summary reports, financial statements, conference reports, partner reports — stay on the legacy engine. Honest classification: mitigated, not retired. A subsequent reporting-modernization initiative would address the rest.

D-04 (medium): Partner Management transaction-management complexity (Application Layer.Partner Management) — Out of scope

Partner Management (~28,298 lines, 9.9%) is the central coordination point for the Petra domain — Partner is the most-related aggregate (17 relationships per the project-intel handoff). Sage flags TPartnerEditWebConnector’s extensive CRUD coordination as a transaction-management complexity risk. The pattern is service-facade orchestration over a generated DAL: each web-connector method opens a transaction, performs N data-set operations, and commits, with method-scoped (not workflow-scoped) transaction boundaries that have accumulated special-case branches over time.

Section 4 explicitly excludes Partner identity authoring from this migration: gift services read donor identity (p_partner, p_family, p_person) via federated REST against legacy MPartner, but they do not refactor TPartnerEditWebConnector. The transaction-coordination complexity Sage flagged remains untouched on the legacy side. Section 4’s caveat 9 explicitly notes that this “increases the importance of the eventual MPartner migration” — this concern is the architectural footprint of that deferred work, and is honestly logged as Out of scope rather than dressed up as something the slice handles.

D-05 (medium): Security framework lacks modern auth patterns (Infrastructure.Security Framework) — Mitigated by target

Authentication routes through TPetraPrincipal and the session-based TOpenPetraOrgSessionManager — server-side session state, no native OAuth 2.0 / OIDC / JWT support, no first-class API-token model. For a single-tenant on-premise deployment this is acceptable; for cloud deployment, modern identity is table stakes.

Section 4 commits to Microsoft Entra ID (OIDC) for the new endpoints, with managed identities for service-to-Azure-resource auth and JWT validation enforced at Azure API Management. Both gift-processing-service and gift-receipting-service use the modern pattern, with a role-claim requirement enforced for batch-posting endpoints. Critically, however, Section 4 also commits to retaining TOpenPetraOrgSessionManager for legacy endpoints during the strangler-fig coexistence phase: legacy clients continue to authenticate as they always have, with APIM bridging the two regimes. This is the canonical case of mitigated rather than retired: modern auth lives where new traffic lives, but the dated session-based framework persists wherever legacy traffic still terminates. Full retirement is gated on every slice migrating off legacy — a multi-slice horizon that Section 11 owns.

D-06 (low): Common Utilities Framework coupling (Cross-Cutting Concerns.Common Utilities) — Mitigated by target

• ~8,083 lines of shared utilities (ArrayList wrappers, string helpers, generic Utilities classes) referenced widely across legacy modules. Section 4’s gift-processing-service and gift-receipting-service use .NET 8 BCL primitives directly (List<T>, LINQ, System.Text.Json, HttpClientFactory + Polly) rather than the legacy utility wrappers. New code does not inherit the coupling. The legacy utility framework, however, persists in the unmigrated zones during coexistence — so the cross-module coupling that Sage flagged is contained, not eliminated. Whole-codebase retirement happens only as subsequent slices migrate.

D-07 (low): Development Tools Suite redundancy (Build & Deployment.Development Tools) — Retired by target

• ~6,575 lines of in-repo development tooling (notably TinyWebServer, custom build scripts) duplicate functionality available out-of-box in the modern stack. Section 4 commits to dotnet build + dotnet publish + npm run build on GitHub Actions, with Kestrel as the embedded web server — standard .NET 8 tooling. The target-architecture handoff explicitly lists NAnt under What’s retired. For the modernized slice, the bespoke development-tools surface is replaced by industry-standard tooling and is genuinely retired.

6.4 Architectural strengths to preserve

Sage’s assessment surfaced five architectural strengths. The target architecture should explicitly preserve the property each strength provides, even if the implementation changes.

• Single-source-of-truth schema (petra.xml) — the master XML schema drives database DDL, generated typed-dataset ORM classes, and report-template field bindings from one canonical specification. Section 4 retires the typed-dataset generator for the gift slice in favour of EF Core 8 code-first against the preserved gift-domain schema, but explicitly defers the broader question (per Section 4 caveat 5: whether petra.xml generation survives for the rest of OpenPetra during coexistence is a Section 11 concern). The property being preserved is “schema changes propagate to code automatically” — EF Core Migrations supplies that property within the new services’ boundary; legacy zones retain the petra.xml pipeline.
• Code Generation Pipeline (TDataDefinitionParser, TDataDefinitionStore) — the schema-to-code transformation is a real architectural asset. Section 4 chose “replace with EF Core code-first for the slice, defer the legacy-zones decision to Section 11.” The asset is preserved in the legacy zones during coexistence; the slice substitutes a different implementation of the same property. Note that for Gift Processing the schema itself is preserved end-to-end — only the code-generation step is retired, not the tables it generates against.
• Multi-Database Abstraction (PostgreSQL / MySQL / SQLite via unified connection factory) — Section 4 standardizes on Azure Database for PostgreSQL Flexible Server, but the EF Core 8 + Npgsql layer preserves the abstraction property: the same DbContext can target SQLite for unit tests (via Testcontainers or in-memory), and a future migration to a different engine touches only the provider configuration. Test-environment flexibility is retained.
• Cross-Layer Validation Framework (TVerificationResult + specialized validators) — consistent business-rule validation across modules is a non-trivial architectural property. Section 4 commits to FluentValidation as the single field-level validation surface for the new services, layered with custom domain-rule classes for the gift-domain financial rules (period validation, posted-batch immutability, sequential gift-batch numbering, tax-deductible 0..100 bounds, SEPA mandate-reference format, Code-128 barcode character set). The implementation changes; the property (one validation surface, consistent rule enforcement) is preserved — and the gift-domain rules become first-class typed exceptions rather than verification-result strings.
• Integration Test Infrastructure (NUnit-based, including TestPartnerEdit and per-module financial coverage) — a real, exercised integration-test suite is rare and valuable. Section 4 commits to xUnit + FluentAssertions + Testcontainers (with an 80% coverage target, plus golden-master tests required for batch posting and tax-deductible calculation) for the new services, and the legacy NUnit suite continues to run against the legacy code during coexistence. The safety net that makes a strangler-fig migration credible is preserved on both sides of the boundary.

6.5 Source-language anti-patterns observed

The active source profile (dotnet-angularjs, v1.1) declares seven anti-patterns to check on every .NET Framework + AngularJS migration. Each is evaluated below against Petra’s actual setup. The point of this subsection is not to issue agent-internal warnings — it is to make explicit which framing traps a stakeholder reading this report should know the analysis successfully avoided.

• “.asmx is hard SOAP” misframing. Petra’s .asmx services (the TGiftTransactionWebConnector-style web connectors) appear at the wire level as SOAP envelopes, but the project-intel handoff confirms the wire format is JSON-over-HTTP RPC dispatched via THttpConnector.CallWebConnector. The migration story is therefore RPC-method-dispatch → REST-over-HTTP, not SOAP → REST. Section 4’s “ASP.NET Core 8 Minimal APIs” commitment matches this correctly. Trap avoided.
• EF Core migration without first retiring the code-generation pipeline. Petra has the petra.xml → TDataDefinitionParser → GiftBatchTDS typed-dataset pipeline as the source of truth for the legacy DAL. If EF Core replaced the legacy DAL while the generator continued to run, the next code-gen pass would overwrite EF-managed entities. Section 4’s Caveat 5 — “petra.xml retirement is scoped to this slice only” — correctly retires the pipeline within the gift-services’ boundary while explicitly deferring the legacy-zone question to Section 11. Importantly, the gift-domain schema is preserved end-to-end (a_gift_batch, a_gift, a_gift_detail, etc.) — only the typed-dataset generator is retired for the slice. Trap avoided.
• Counting XML report templates / inline HTML templates as “UI files”. Petra has ~39,992 lines of XML report templates (D-03 above) and a substantial HTML-template surface for the legacy jQuery client. Treating these as interactive UI surface would have inflated UI-migration scope by an order of magnitude and skewed candidate-selection scoring — particularly for this slice, which carries 45 XML report templates as part of the broader reporting estate. The candidate-selection phase correctly excluded reporting templates from interactive-UI counting (the slice has five interactive screens, not 50); the receipt-template subset of the report estate is rebuilt by gift-receipting-service as part of D-03’s mitigation. Trap avoided.
• “No observability today” framing. The source-profile anti-pattern warns that mature .NET projects often have ELMAH / log4net / NLog / Serilog already in place, so observability is rarely net-new on this stack. Petra in particular has a TLogging framework in Common.Logging (per Sage’s technology subjects) and a structured logging pattern across web connectors. Section 6 (How Sage Helped) and Section 4’s observability commitments correctly emphasize consistency (one logger across services) and correlation (trace IDs propagated automatically across HTTP and Service Bus, so a queued receipt-batch trace spans both services) rather than “observability is new” — matching the profile’s recommended framing for .NET sources. Trap avoided.
• Promising “rip out .NET Framework” without checking NuGet compatibility. Petra’s csharp/ThirdParty/packages.config contains in-line comments documenting that several deps (Npgsql 4.1.10, SharpZipLib 1.3.3, NUnit 3.15.2) are pinned at old versions specifically because newer versions require .NET 5/6+. The .NET Framework 4.7 ceiling is therefore not just a runtime question but a transitive-dependency cascade. Section 4 right-sizes by carving two services that ship on .NET 8 alongside the legacy 4.7 stack rather than promising whole-codebase upgrade. The package-compatibility audit in 6.7 below makes this explicit. Trap avoided.
• Assuming SQL Server. Petra is multi-database (PostgreSQL primary, MySQL, SQLite) per project-intel. Section 4 standardizes the modernized slice on Azure Database for PostgreSQL Flexible Server (engine preserved from primary legacy DB) rather than defaulting to Azure SQL. The preserve-schema decision is deeper than driver choice — the entire gift-domain schema (a_gift_batch, a_gift, a_gift_detail, a_motivation_*, a_recurring_gift_*) is preserved end-to-end. Trap avoided.
• “Just upgrade AngularJS to Angular” misframing. AngularJS 1.x → Angular 17+ is a complete framework rebuild, not a version bump — the digest cycle, scope inheritance, and directive compilation model do not have direct Angular peers. Petra is actually jQuery-based (not AngularJS at all per the source-profile cautionNotes), which makes this trap inapplicable in the literal sense, but the broader anti-pattern still applies: the legacy front-end is being replaced, not upgraded. Section 4’s “Angular 18 SPA standalone components” commitment frames this as a rewrite under the strangler-fig coexistence pattern, with five Angular 18 components (one per gift screen) replacing five jQuery + Bootstrap-modal forms. Trap avoided.

6.6 Debt outside migration scope

One concern from 6.2 is classified Out of scope. It is real architectural debt that the modernization slice does not address. Stakeholders should treat it as a future-investment line item rather than a risk the current engagement retires:

• D-04 — Partner Management transaction-coordination complexity. TPartnerEditWebConnector remains on the legacy stack because Partner identity authoring is explicitly out of this slice (Section 4: Partner is consumed via federated read, not authored). The transaction-management complexity persists; a future MPartner migration would address it. This is the single biggest deferred-investment item the slice leaves on the table, and it’s the architectural footprint of the “Partner is the central aggregate” reality that runs through every Sage-derived insight on the project.

Total debt-by-classification distribution: 2 retired, 4 mitigated, 0 inherited, 1 out-of-scope. The absence of an “Inherited” row is meaningful: there is no concern in the catalog that the target architecture would explicitly carry forward unchanged into the new services. Concerns either get retired by the slice, mitigated by the slice’s containment of legacy patterns and partial rebuild of the affected surface, or are honestly excluded from this engagement’s scope.

6.7 Outdated dependencies (library/version debt)

This subsection is the bill-of-materials view of Petra’s dependency surface, distinct from the architectural concerns in 6.2–6.6. Manifest-file scanning surfaced the following manifests in the cataloged Petra repository:

Manifests not found (scanned, returned no matches): bower.json, *.nuspec, paket.dependencies. Petra does not use Bower, does not publish itself as a NuGet package, and does not use Paket. Two further .csproj files were found but neither contributes to the dependency catalog (one is NAnt-tooling-only with HintPath references; one is a template file).

The dependency table below is the union of packages.config (24 server entries) + package.json (12 client entries) + the NAnt cross-reference (1 entry) = 37 dependencies. Each entry classifies on two axes: Lifecycle status (current / outdated / eol-major-version / eol-project / known-cve) and Target action (removed / replaced / upgraded / kept-with-risk / outside-slice). Lifecycle status is project-wide and stable across runs; target action is the column that shifts with the chosen slice.

Server-side dependencies (csharp/ThirdParty/packages.config)

Client-side dependencies (js-client/package.json)

Build-system (NAnt) cross-reference

Risk narratives for EOL-project and known-CVE entries

NAnt (eol-project, build system). NAnt’s last release was 2012; the project is community-abandoned. Petra’s build orchestration leans on it for code-generation invocation, NUnit test driving, and assembly linking. The migration path is well-trodden: dotnet build, dotnet test, and a CI pipeline (GitHub Actions per Section 4). The slice retires NAnt for both gift services. Legacy zones continue to invoke NAnt during coexistence; full retirement is gated on every slice migrating off the legacy build.

Npgsql 4.1.10 (eol-major-version, primary database driver). This is the most stakeholder-impactful single dep in the catalog. It is the database driver for the entire system, the manifest comment explicitly documents the inability to upgrade (“we cannot update to 5.x because that only supports .net 5”), and Npgsql 4.x is no longer maintained — meaning the project is one critical CVE away from a forced cross-major-version migration with no easy rollback. The target runs Npgsql 8.x via Npgsql.EntityFrameworkCore.PostgreSQL; for the gift services this concern is retired. For the unmigrated legacy zones, this is the single highest-priority library debt the engagement leaves on the table — a follow-up engagement should expedite either a full .NET 8 migration or, at minimum, a Npgsql security audit.

SharpZipLib 1.3.3 (eol-major-version, archive I/O). Slice shift vs a non-import slice: the bank-import worker in gift-receipting-service ingests ZIP-wrapped CAMT bank-statement archives, so this dep falls inside the slice. Manifest comment documents the .NET 6.0 ceiling on 1.4.x. The target replaces SharpZipLib 1.3.3 with System.IO.Compression built-in on .NET 8 for the bank-import path. Legacy zones may keep SharpZipLib 1.3.3 for any other archive-handling that is not in this slice.

PDFsharp 1.50.5147 (outdated, PDF rendering). Slice shift vs a non-receipt slice: annual-receipt PDF rendering is rebuilt by gift-receipting-service as a queued worker, so PDFsharp moves from “outside slice” into “Replaced by target.” Final replacement library is deferred to Section 8 (QuestPDF or PuppeteerSharp). PDFsharp’s 1.50 line is from 2018; the 6.x line is current. This is a meaningful upgrade in PDF compliance and a meaningful reduction in legacy-PDF-rendering CVE exposure for the receipt path.

libsodium-net 0.10.0 (eol-project, crypto). Last release 2017. Crypto code on an abandoned package is a bigger risk class than other abandoned packages — CVE patches don’t arrive even in theory. Outside this slice (the gift services do not invoke the legacy crypto path), so no migration action this engagement; flagged for a future slice.

Portable.BouncyCastle 1.9.0 (eol-project, crypto). The package ID was renamed to BouncyCastle.Cryptography; the Portable.BouncyCastle ID is no longer the maintained version. Outside slice; flagged.

i18next-xhr-backend ^1.5.1 (eol-project, i18n). Deprecated in favour of i18next-http-backend. Replaced wholesale by Angular i18n; not flagged as a migration risk.

browserify / browserify-css / popper.js (eol-project, front-end). All three are deprecated in favour of modern peers (webpack/Vite/esbuild; @popperjs/core). All three are removed by the Angular 18 build pipeline; no migration risk in the slice.

axios ^0.21.4 (known-cve, HTTP client). 0.21.x carries published CVEs (CVE-2021-3749 regex DoS; CVE-2023-45857 XSRF token leakage) that are addressed in axios 1.x. Replaced by Angular HttpClient in the new SPA — the slice does not ship with axios at any version.

Summary

Of 37 dependencies surveyed across two real manifests (24 server, 12 client; 1 NAnt cross-reference) plus two non-contributing .csproj files:

• Server-side (24 deps): 4 current, 16 outdated, 2 eol-major-version, 2 eol-project, 0 known-cve. By target action: 7 removed, 7 replaced, 3 upgraded, 0 kept-with-risk, 7 outside-slice.
• Client-side (12 deps): 1 current, 3 outdated, 3 eol-major-version, 4 eol-project, 1 known-cve. By target action: 6 removed, 5 replaced, 1 upgraded.
• NAnt cross-reference (1): eol-project; replaced.
• Total lifecycle: 5 current, 19 outdated, 5 eol-major-version, 7 eol-project, 1 known-cve.
• Total target action (37 entries): 13 removed, 13 replaced, 4 upgraded, 0 kept-with-risk, 7 outside-slice.

Slice-driven shifts in target action vs a non-receipt, non-import slice. Two server-side deps shift from “Outside slice” into the active migration column for this slice: SharpZipLib moves to “Replaced by target” because the bank-import worker is in scope, and PDFsharp moves to “Replaced by target” because annual-receipt rendering is in scope. The lifecycle column is identical to a project-wide audit (those are project-level facts) — what changes is which legacy deps the slice has the standing to retire. The other seven outside-slice server deps (MySqlConnector, MimeKit, MailKit, Portable.BouncyCastle, HtmlAgilityPack, libsodium-net, NPOI) all sit in legacy paths the gift services never invoke.

Cross-cutting observation: the .NET Framework 4.7 ceiling is a transitive cascade. Three of the server-side outdated entries (Npgsql, NUnit, SharpZipLib) carry inline manifest comments documenting that they cannot be upgraded because newer versions require .NET 5/6+. Six BCL polyfill packages (System.Buffers, System.Memory, System.ValueTuple, System.Runtime.CompilerServices.Unsafe, System.Threading.Tasks.Extensions, System.Runtime) are present only because the runtime is .NET Framework 4.7. The library-debt picture is therefore not 37 independent decisions but one strategic decision: migrate off .NET Framework 4.7 first, and many of these entries collapse automatically. Section 4’s commitment to .NET 8 for both gift services is the ceiling-break; the slice retires or absorbs the polyfill subset (the “Removed by target” column above) wholesale because .NET 8’s BCL contains every type those polyfills exist to backport.

Provenance. Manifests scanned: 4 (2 contributing + 2 non-contributing as documented above). Patterns scanned with no matches: bower.json, *.nuspec, paket.dependencies. EOL claims cross-reference the source profile’s knownEolDependencies array (NAnt, Newtonsoft.Json) plus published CVE history (axios) and project-status verification (Bootstrap 4, Browserify, Popper.js v1, i18next-xhr-backend, libsodium-net, Portable.BouncyCastle). Test-only deps (NUnit + console runners) are included because they are EOL-pinned by the runtime ceiling, not filtered out.

Architectural source: Sage’s project-level architectural assessment for Petra, LLM confidence 0.85. Dependency source: manifest scan of the Petra repository. Concerns: 7 (1 high, 4 medium, 2 low). Strengths: 5. Anti-pattern checks: 7 of 7 traps avoided. Dependencies surveyed: 37. Lifecycle distribution: 5 current, 19 outdated, 5 eol-major-version, 7 eol-project, 1 known-cve. Classification distribution (architectural): 2 retired, 4 mitigated, 0 inherited, 1 out-of-scope. Target-action distribution (libraries): 13 removed, 13 replaced, 4 upgraded, 0 kept-with-risk, 7 outside-slice.

7. UI/UX Transformation Examples

This section demonstrates the user-interface transformation from Petra's legacy jQuery + Bootstrap-modal Gift Processing surface to a modern Angular 18 SPA backed by ASP.NET Core 8 Minimal APIs on Azure App Service. The legacy is already a web application — the user already opens a browser, types into HTML inputs, and clicks save buttons — but the workload is fragmented behaviorally across stacked Bootstrap modals, every save round-trips through a separate .asmx endpoint on TGiftTransactionWebConnector, every long-running render holds the request thread, and the operator's mental model ("statement file in → posted batch → tax receipt out") is never represented as one continuous surface. The transformation lies in composition and workload shape: three modal stacks collapse to a single Gift Batch Lifecycle sheet, and a single synchronous render form expands into Form + Job Status Panel + Manual Review + Audit Trail thanks to the new queued-worker pattern.

7.1 UI Affinity Analysis

Before examining individual screens, the table below maps the legacy UI's recurring frictions to modernization opportunities. Every row traces to actual source content discovered via Sage MCP — the five jQuery templates (GiftBatches.html, RecurringGiftBatches.html, Motivations.html, BankImport.html, PrintAnnualReceipts.html), their controller JavaScript, and TGiftTransactionWebConnector on the server.

7.2 Gift Batches — Modal-stack Editing → Inline Editable Grid

Gift Batches is the highest-traffic gift screen and the cleanest paradigm-shift example in the slice. The legacy renders a list of batches; opening one expands a transaction list; opening a transaction opens .tpl_edit_trans over the parent; opening a detail opens .tpl_edit_trans_detail over that. Three modal levels deep. The modern equivalent is a single inline-editable grid (cell-level edit, keyboard navigation, bulk paste). Example data obeys BR-GFT-001 (sequential batch numbers), BR-GFT-002 (period-validated effective date), BR-GFT-009 (three-amount multi-currency), BR-GFT-013 (active-only motivation pickers), and BR-GFT-005 (posted batches locked).

7.3 Recurring Gift Batches — SEPA Mandate Capture

Recurring Gift Batches drives the upstream side of the donation cycle: the recurring-gift batch generates the SEPA Direct Debit XML that the bank collects against, which is what later produces incoming bank-statement lines (the inbound side handled by Bank Import in section 7.5). The legacy form embeds SEPA mandate capture in the Edit Transaction modal (mandate reference + given-date columns added by DB upgrade Upgrade202206_202207.cs:66). The modern equivalent is a dedicated SEPA-aware recurring-gift sheet with mandate validation feedback inline. BR-GFT-015 governs the mandate-tracking semantics.

7.4 Motivations Setup — Catalog Editor with Active-Status Awareness

Motivations Setup is the lightest screen in the slice but a load-bearing one: every gift detail line picks a motivation, and every motivation carries a default GL account, default cost centre, and active flag (a_motivation_status_l). The legacy renders motivation groups as a collapsible list with an Edit Detail modal whose body has six checkboxes for the boolean facets (sponsorship, membership, tax-deductible, active, etc.) and two autocomplete fields for GL defaults. The modern equivalent exposes the same data in a single editable side panel that cross-references where each motivation is currently being used. BR-GFT-013 (active-status default) governs the activation flag.

7.5 Bank Import — Synchronous Parse → Live Job-Status Banner

Bank Import is the most workload-distinct screen in the slice. The legacy uploads a CAMT/MT940/CSV file via multipart POST and synchronously parses it on the request thread — for a 142-line file, the page locks for 20–30 seconds before the matched-status grid renders. The modern equivalent returns 202 Accepted on upload, enqueues a Service Bus message to the bank-import queue, runs the parse in gift-receipting-service's BankImportModule worker, and shows a live progress banner in the SPA (BR-GFT-007 banking-code classification fires inside the worker). This is the visible face of the queued-worker pattern and the canonical demo for "the new architecture lets the operator keep working while the file processes."

7.6 Print Annual Receipts — Submit Form (1:1 view)

The Print Annual Receipts form itself is the closest 1:1 translation in the slice: same fields (start date, end date, optional single-donor filter, HTML template upload, logo, signature, email subject/body, only-test checkbox), three submit modes (Download archive, Print, Email). The legacy pre-fills the date range to last calendar year via PrintAnnualReceipts.js:11 (BR-GFT-008). The modern equivalent has the same fields rendered as Angular reactive form controls, with the date-range default surfaced as an explicit hint rather than hidden in JS. The interesting divergence is what happens after Submit — covered by section 7.8 below.

7.7 "Beyond 1:1" — Use Case 1: The Gift Batch Lifecycle Sheet (Consolidation)

While five-screen-by-five-screen translation is useful, the highest-leverage transformation in this slice is collapsing the three-page Bank Import → Gift Batches → GL Verification flow into a single Gift Batch Lifecycle sheet. The legacy fragments the operator's continuous task ("statement file in → posted batch → GL recorded") across three independently-rendered pages with their own filter states, their own grids, and their own RPC round-trip cycles. The end-to-end traceability ("the 142-line CAMT file produced the 137-line gift batch which posted to GL transaction 8943") exists in the database (composite-key joins across bank_import_line → a_gift_detail → a_journal) but the legacy UI is too modal-fragmented to render it.

The lifecycle sheet shows on a single render: the source bank-import upload at the top (provenance), the draft → posted gift batch in the middle with inline detail editing, and the federated-GL-posting result at the bottom — all bound to a status timeline running down the right edge. This view is auto-generated from the storyboard in inputs/ui-storyboards/gift-processing-end-to-end-002-draft.md via the ui-storyboard-transformation skill: each scene in the storyboard becomes a state of the unified view showing which panels are active.

## Use Case 1: Process a Gift Batch End-to-End

### Scene 1 — Bank Import upload
- Drop CAMT/MT940/CSV onto upload zone
- Live status banner: "Parsing... 142 of 142 transactions"
- BR-GFT-007 banking-code chips per matched line

### Scene 2 — Unmatched queue
- 55 unmatched rows; fuzzy-match suggestions per row
- Operator resolves 5 edge cases (Match / Split / Reject)
- 50 auto-promote into draft batch + 87 auto-matched = 137 details

### Scene 3 — Draft batch landing
- Top of unposted-batches list with BatchNumber = LastGiftBatchNumber + 1 (BR-GFT-001)
- Period chip "2026-04 open" (BR-GFT-002)
- 137 detail rows; 12 flagged "needs motivation"

### Scene 4 — Inline detail editing
- Cell-edit motivation, tax %, recipient
- BR-GFT-014 partner-class auto-resolve fires server-side
- BR-GFT-003 recalculation cascade on % change
- BR-GFT-010 out-of-range reject (deliberate tightening)

### Scene 5 — Post Batch
- Validate (period, motivations active, no zero-amount)
- BR-GFT-002 re-fires; BR-GFT-005 immutability armed; BR-GFT-013 active check
- Federated POST to legacy MFinance for GL transaction
- Toast: "Batch GBP-2026-047 posted, GL Txn 8943"

### Scene 6 — GL receipt and lifecycle close
- Batch row greys out; no edit affordance (BR-GFT-005)
- Side panel: GL Txn 8943 with 8 journal lines across 3 cost centres
- Receipts now eligible for next annual run (BR-GFT-004 prep)
            

Gift Batch Lifecycle Sheet — Unified View (Scene 5 active: Post Batch)

The unified view shows every panel that the legacy splits across three pages: source upload provenance, batch + inline editable details, and federated GL posting result. Below, Scene 5 (Post Batch) is the active state — the validation panel is highlighted, the post button is armed, and the timeline shows progress through "drafted → reviewed" with "posted" pending.

What becomes possible only post-migration

• End-to-end traceability in one render. The 142-line CAMT → 137-line batch → 8-line GL journal across 3 cost centres. The legacy database supports the join, but the legacy UI never assembles it.
• No request-thread hostage. Bank-statement parse and GL post are queued workers. A 5-minute parse no longer locks the page; a slow GL write no longer leaves a half-posted batch.
• Saga-protected cross-boundary write. The federated GL post is a saga step with outbox and retry. Failure rolls back the batch-status flip. Legacy: GL write was inline and best-effort; failure required DB-admin recovery.
• Live status timeline. Operator sees lifecycle progression (uploaded → parsed → classified → drafted → reviewed → posted → GL recorded) without leaving the sheet.
• Inline detail editing replaces 137 modal opens. The single biggest usability improvement in the slice.

7.8 "Beyond 1:1" — Use Case 2: The Annual Receipt Run (Expansion, Not Consolidation)

Use Case 2 is the inverse of the standard Beyond-1:1 pattern. The legacy is a single form that synchronously produces a multipart-PDF download. There are no fragments to consolidate. What changes is that the queued-worker pattern unlocks UX surfaces the synchronous-render legacy cannot afford: a Job Status Panel (live progress per donor), a Manual Review side panel (cross-jurisdiction edge cases), and an Audit Trail screen (per-receipt provenance with SHA-256 + immutable Blob path). The form stays roughly the same; what's new is everything that happens after Submit.

The point worth flagging for the report's narrative: "Beyond 1:1" is not always consolidation. The slice's two use cases happen to demonstrate both directions — Use Case 1 collapses three pages into one (consolidation), Use Case 2 expands a single form into Form + Status + Review + Audit (expansion). The architectural shape that drives the difference is whether the legacy fragmented the workflow across pages (consolidate) or hid the workload behind a synchronous render (expand). Queued workers are the canonical case where modernization adds UI rather than removing it.

Job Status Panel — the visible face of the queued worker

Below: the post-Submit experience for the 1,431-donor annual run. The form has been replaced by a live status panel; the worker is mid-run, rendering per-donor PDFs in parallel and writing each to immutable Blob storage with SHA-256 provenance. The legacy screen at this point in the workflow was a frozen browser tab with a spinner.

What becomes possible only post-migration (UX surfaces unlocked by queued worker)

• Live progress per donor. Operator sees the run advance — not just a spinner. Switch tabs and come back; the panel resumes from where the worker is.
• Manual review queue. Cross-jurisdiction edge cases (country-specific preambles, unsigned-off templates, dubious addresses) surface as a side panel rather than being silently dropped or rendered with default templates. Each gets a "Render anyway / Skip / Send to PO" decision — recorded in render_job.review_actions.
• Per-receipt audit trail. SHA-256 + immutable Blob path + rendered-at + rendered-by per receipt — legacy had transient temp-file PDFs and no provenance row. Re-prints serve the same immutable PDF rather than re-rendering.
• Resumable runs. A failed render goes to the dead-letter queue; admin retries the specific donor without restarting the entire batch.
• Per-donor re-issue from audit trail. "Re-issue James Wilson's 2024 receipt" is a single audit-row drill-in → click. Legacy required running the entire annual flow filtered to one donor.
• Hash-based deduplication. Same donor + same date range + no underlying gift changes → SHA-256 match → integrity check is free. Legacy had no notion of receipt identity beyond "the file the operator downloaded."
• Cross-year audit query. "Show me every receipt this donor has received since 2022" is a single query against rendered_receipt. Legacy: search filesystem temp directories.

7.9 Anti-Patterns Avoided in This Section

• No green-screen mockups. Petra is a web SPA — the legacy column renders the actual jQuery + Bootstrap modal stack as it appears in source, with the parent page visible-but-dimmed behind the modal backdrop. There are no fictional 80x24 terminals or function-key bars.
• No fictional fields. Every form field in the legacy column maps to a real name="..." attribute in the source HTML — a_batch_number_i, a_batch_status_c, a_motivation_detail_code_c, a_sepa_mandate_reference_c, AStartDate, AEndDate, etc. Modal classes (.tpl_edit_batch, .tpl_edit_trans, .tpl_edit_trans_detail, .tpl_edit_motivation) match the source div structure.
• No fictional BR-XXXX codes inside legacy code. BR-GFT-001..016 references appear only in analysis prose, "active rules" footers, and modernization-notes columns — never inside legacy modal markup. The behavioral-rules catalog in Section 9 is the source of truth.
• Modern column matches legacy data density. Where the legacy shows multiple rows (137 detail lines, 1,431 donors, 142 transactions), the modern column shows the same row volume in modern form — not a single summary card. The Bank Import streaming table renders 6 rows + "49 more"; the Gift Batch grid renders 6 rows + "131 more"; the audit-trail preview renders 3 rows.
• No COBOL or green-screen comparative framing. The legacy stack is .NET / Mono / FastCGI / jQuery / Bootstrap; the modernization is .NET 8 / Angular 18. The report stands on its own without comparison to other migration types.
• Mockup data obeys the cited rules. Every example value was derived to be consistent with the BR catalog — tax % stays in [0, 100] (BR-GFT-010), batch numbers are sequential (BR-GFT-001), period chip says "open" (BR-GFT-002), motivations resolved by partner unit type (BR-GFT-014), receipt amount totals match the per-donor gift history aggregation (BR-GFT-009).
• Modern column is Angular 18, not React. Per the engagement’s committed target stack and the .NET / AngularJS source profile; React would be the wrong stack for this slice.
• "Beyond 1:1" is not always consolidation. Use Case 1 collapses three pages; Use Case 2 expands one form into four surfaces. The architectural driver (queued worker + immutable artefact) determines direction.

Continue to Section 8: Code Translation Examples for the .NET 8 / Angular 18 framework-pattern translations (the inline-grid + queued-worker + saga shapes shown here as UI map to HttpClient, Azure.Messaging.ServiceBus, FluentValidation, Angular reactive forms, and OpenTelemetry on the code side).

8. Code Translation Examples

This section demonstrates the translation of Petra's framework-level idioms in the Gift Processing slice from .NET Framework 4.7 / ASP.NET Web Services (.asmx) / jQuery to ASP.NET Core 8 Minimal APIs / EF Core 8 / Azure Service Bus / Angular 18. The examples focus on cross-cutting patterns — how RPC endpoints, transactions, long-running render jobs, and verification-result error handling are reshaped — rather than business logic translations, which appear in Section 9 (Business Rules Analysis) alongside their formal Given-When-Then specifications and behavioral-fidelity classifications. BR-GFT-XXX references in this section are cross-references; the rules themselves are documented in Section 9.

8.1 ASMX Web Method → ASP.NET Core 8 Minimal API Endpoint

Petra exposes server-side gift operations via static methods on TGiftTransactionWebConnector, hosted on a .asmx endpoint with [RequireModulePermission] attributes that drive a custom session-based authorisation layer (TOpenPetraOrgSessionManager). The wire format is JSON-RPC over a SOAP envelope shape (per the source profile's anti-pattern note: do NOT describe .asmx as 'hard SOAP' if the wire format is actually JSON RPC). The modern equivalent is an ASP.NET Core 8 Minimal API endpoint with FluentValidation on the request DTO, OIDC bearer-token authorisation, OpenAPI metadata, and a structured Serilog event.

// csharp/ICT/Petra/Server/lib/MFinance/Gift/
// Gift.Transactions.cs lines 71-115 (CreateAGiftBatch)

namespace Ict.Petra.Server.MFinance.Gift.WebConnectors
{
    public partial class TGiftTransactionWebConnector
    {
        [RequireModulePermission("FINANCE-1")]
        public static GiftBatchTDS CreateAGiftBatch(
            Int32 ALedgerNumber,
            DateTime ADateEffective,
            string ABatchDescription,
            TDataBase ADataBase = null)
        {
            if (ALedgerNumber <= 0)
            {
                throw new
                  EFinanceSystemInvalidLedgerNumberException(
                    "Ledger number must be > 0",
                    ALedgerNumber);
            }

            GiftBatchTDS MainDS = new GiftBatchTDS();
            TDBTransaction Transaction =
                new TDBTransaction();
            TDataBase db = DBAccess.Connect(
                "CreateAGiftBatch", ADataBase);
            bool SubmissionOK = false;

            db.WriteTransaction(
                ref Transaction,
                ref SubmissionOK,
                delegate
                {
                    ALedgerTable ledgerTable =
                      ALedgerAccess.LoadByPrimaryKey(
                        ALedgerNumber, Transaction);
                    // ... assign batch number,
                    // validate period, populate
                    // MainDS, submit changes
                    SubmissionOK = true;
                });

            return MainDS;
        }
    }
}

// Endpoints/GiftBatchEndpoints.cs

public static class GiftBatchEndpoints
{
    public static RouteGroupBuilder
    MapGiftBatches(this RouteGroupBuilder g)
    {
        g.MapPost("/api/gift/batches", async (
                CreateGiftBatchRequest req,
                IValidator<CreateGiftBatchRequest> validator,
                IGiftBatchService svc,
                CancellationToken ct) =>
            {
                var result = await
                    validator.ValidateAsync(req, ct);
                if (!result.IsValid)
                    return Results.ValidationProblem(
                        result.ToDictionary());

                var batch = await
                    svc.CreateAsync(req, ct);
                return Results.Created(
                    $"/api/gift/batches/{batch.LedgerNumber}/{batch.BatchNumber}",
                    batch);
            })
            .RequireAuthorization("GiftEntry")
            .WithName("CreateGiftBatch")
            .Produces<GiftBatchResponse>(201)
            .ProducesValidationProblem()
            .WithOpenApi();

        return g;
    }
}

// Validation/CreateGiftBatchValidator.cs

public sealed class CreateGiftBatchValidator
    : AbstractValidator<CreateGiftBatchRequest>
{
    public CreateGiftBatchValidator()
    {
        RuleFor(x => x.LedgerNumber)
            .GreaterThan(0)
            .WithMessage("Ledger number must be > 0");
        RuleFor(x => x.DateEffective).NotEmpty();
        RuleFor(x => x.BatchDescription)
            .NotEmpty().MaximumLength(80);
    }
}

8.2 TDBTransaction Delegate → DbContext + IDbContextTransaction

Petra wraps every gift-batch read or write in a TDBTransaction passed by reference into a delegate, with a separate SubmissionOK ref-bool that the delegate sets to signal commit. This is the canonical Mono-era .NET 4.7 transactional idiom (and the source profile's legacyIdiomInventory singles it out by name: DBAccess.GDBAccessObj.GetNewOrExistingDelegate). The modern equivalent is EF Core 8 with a request-scoped DbContext and an explicit IDbContextTransaction only when an operation crosses aggregate boundaries (the gift-batch + ledger-counter increment in BR-GFT-001 is exactly such a case).

// Gift.Transactions.cs lines 100-115 (excerpt)
// (the inner WriteTransaction body for
//  CreateAGiftBatch — sequential
//  numbering + period fit)

TDBTransaction Transaction =
    new TDBTransaction();
TDataBase db = DBAccess.Connect(
    "CreateAGiftBatch", ADataBase);
bool SubmissionOK = false;

db.WriteTransaction(
    ref Transaction,
    ref SubmissionOK,
    delegate
    {
        ALedgerTable ledgerTable =
          ALedgerAccess.LoadByPrimaryKey(
            ALedgerNumber, Transaction);

        // BR-GFT-001 sequential numbering:
        // allocate next batch number from
        // the ledger row counter
        AGiftBatchRow NewRow =
          MainDS.AGiftBatch.NewRowTyped();
        NewRow.LedgerNumber = ALedgerNumber;
        NewRow.BatchNumber =
          ++ledgerTable[0].LastGiftBatchNumber;
        NewRow.BatchDescription =
          ABatchDescription;
        NewRow.BatchStatus =
          MFinanceConstants.BATCH_UNPOSTED;

        // BR-GFT-002 period validation
        TFinancialYear
          .GetLedgerDatePostingPeriod(
            ALedgerNumber, ref ADateEffective,
            out int BatchYear,
            out int BatchPeriod,
            Transaction, true);

        NewRow.BatchYear = BatchYear;
        NewRow.BatchPeriod = BatchPeriod;
        MainDS.AGiftBatch.Rows.Add(NewRow);

        AGiftBatchAccess.SubmitChanges(
          MainDS.AGiftBatch, Transaction);
        ALedgerAccess.SubmitChanges(
          ledgerTable, Transaction);
        SubmissionOK = true;
    });

// Services/GiftBatchService.cs (excerpt)

public sealed class GiftBatchService(
    GiftDbContext db,
    IFinancialPeriodValidator periodValidator,
    ILogger<GiftBatchService> log)
    : IGiftBatchService
{
    public async Task<GiftBatchResponse>
    CreateAsync(
        CreateGiftBatchRequest req,
        CancellationToken ct)
    {
        await using var tx = await
            db.Database.BeginTransactionAsync(
                IsolationLevel.Serializable, ct);

        // BR-GFT-001 sequential numbering
        var ledger = await db.Ledgers
            .SingleAsync(l =>
              l.LedgerNumber == req.LedgerNumber, ct);

        var nextNumber =
            ++ledger.LastGiftBatchNumber;

        // BR-GFT-002 period validation
        var period = await
            periodValidator.ResolveAsync(
                req.LedgerNumber,
                req.DateEffective,
                forceFit: true, ct);

        var batch = new GiftBatch
        {
            LedgerNumber = req.LedgerNumber,
            BatchNumber = nextNumber,
            BatchDescription = req.BatchDescription,
            BatchStatus = BatchStatus.Unposted,
            DateEffective = period.EffectiveDate,
            BatchYear = period.Year,
            BatchPeriod = period.Period
        };

        db.GiftBatches.Add(batch);
        await db.SaveChangesAsync(ct);
        await tx.CommitAsync(ct);

        log.LogInformation(
            "gift.batch_created " +
            "ledger={Ledger} batch={Batch}",
            batch.LedgerNumber, batch.BatchNumber);

        return
            GiftBatchResponse.FromEntity(batch);
    }
}

8.3 Synchronous Render → Azure Service Bus Queued Worker ARCHITECTURAL HEADLINE

Petra's CreateAnnualGiftReceipts entry point on TReceiptingWebConnector renders every donor's annual receipt PDF synchronously inside the request handler — load donor list, fetch each donor's gift detail, run the HTML template, embed the logo and signature images, generate the PDF binary, and only then return. For a year-end run with thousands of donors this can take many minutes; the legacy UI shows a page-locked spinner and is at the mercy of any HTTP/IIS/Mono FastCGI timeout. The modern equivalent splits the boundary in two: the API endpoint persists a render_job row and publishes a RenderAnnualReceiptJob message to Azure Service Bus; the gift-receipting-service background worker (an IHostedService consuming the receipt-batch queue with sessions enabled for per-ledger ordering) does the actual rendering, writes the PDF to Azure Blob Storage, and updates the render_job status. This is the load-bearing architectural shift that justifies the two-service split documented in Section 4.

// csharp/ICT/Petra/Server/lib/MFinance/Gift/
// Gift.Receipting.cs lines 75-141 (entry)

public class TReceiptingWebConnector
{
  [RequireModulePermission("FINANCE-1")]
  public static bool
  CreateAnnualGiftReceipts(
    Int32 ALedgerNumber,
    string AFrequency,
    DateTime AStartDate,
    DateTime AEndDate,
    string AHTMLTemplate,
    byte[] ALogoImage,
    string ALogoFilename,
    byte[] ASignatureImage,
    string ASignatureFilename,
    string ALanguage,
    string AEmailSubject,
    string AEmailBody,
    string AEmailFrom,
    string AEmailFromName,
    string AEmailFilename,
    out string APDFReceipt,
    out string AHTMLReceipt,
    out TVerificationResultCollection AVerification,
    bool ADeceasedFirst = false,
    string AExtract = null,
    Int64 ADonorKey = 0,
    string AAction = "all",
    bool AOnlyTest = true)
  {
    APDFReceipt = string.Empty;
    AHTMLReceipt = string.Empty;
    AVerification =
      new TVerificationResultCollection();

    Catalog.Init(ALanguage, ALanguage);

    TDBTransaction Transaction =
      new TDBTransaction();
    TDataBase db = DBAccess.Connect(
      "AnnualGiftReceipts");

    db.ReadTransaction(
      ref Transaction,
      delegate
      {
        // 1. Load donor key set (extract
        //    or full ledger sweep)
        // 2. For EACH donor: query gifts,
        //    apply BR-GFT-004 4-condition
        //    receipt eligibility filter
        // 3. Render HTML → PDF inside
        //    the request thread
        // 4. (Optional) email per donor
        // All synchronous — can take
        // many minutes for year-end runs
      });

    return true;
  }
}

// gift-processing-service:
// Endpoints/AnnualReceiptEndpoints.cs

g.MapPost("/api/gift/receipts/annual", async (
    AnnualReceiptRunRequest req,
    GiftDbContext db,
    ServiceBusClient sb,
    ILogger<Program> log,
    CancellationToken ct) =>
{
  var job = new RenderJob
  {
    JobId = Guid.NewGuid(),
    Kind = RenderJobKind.AnnualReceipt,
    LedgerNumber = req.LedgerNumber,
    Status = RenderJobStatus.Queued,
    RequestedAt = DateTimeOffset.UtcNow,
    RequestedBy = req.UserId
  };
  db.RenderJobs.Add(job);
  await db.SaveChangesAsync(ct);

  var sender =
    sb.CreateSender("receipt-batch");
  var message = new ServiceBusMessage(
    BinaryData.FromObjectAsJson(
      new RenderAnnualReceiptJob(
        job.JobId, req)))
  {
    SessionId =
      $"ledger-{req.LedgerNumber}",
    ContentType = "application/json",
    MessageId = job.JobId.ToString()
  };
  await sender.SendMessageAsync(message, ct);

  log.LogInformation(
    "gift.receipt.job_queued " +
    "job_id={JobId} ledger={Ledger}",
    job.JobId, req.LedgerNumber);

  return Results.Accepted(
    $"/api/gift/receipts/jobs/{job.JobId}",
    new { jobId = job.JobId });
})
.RequireAuthorization("GiftReceipts")
.Produces(202);

// gift-receipting-service:
// Workers/AnnualReceiptWorker.cs

public sealed class AnnualReceiptWorker(
    ServiceBusClient sb,
    IServiceProvider sp,
    ILogger<AnnualReceiptWorker> log)
    : BackgroundService
{
  protected override async Task
  ExecuteAsync(CancellationToken ct)
  {
    await using var processor =
      sb.CreateSessionProcessor(
        "receipt-batch",
        new ServiceBusSessionProcessorOptions
        {
          MaxConcurrentSessions = 4,
          AutoCompleteMessages = false
        });

    processor.ProcessMessageAsync += async args =>
    {
      var msg = args.Message
        .Body.ToObjectFromJson<RenderAnnualReceiptJob>();

      await using var scope =
        sp.CreateAsyncScope();
      var renderer = scope.ServiceProvider
        .GetRequiredService<IAnnualReceiptRenderer>();

      try
      {
        await renderer.RenderAsync(
          msg, args.CancellationToken);
        await args.CompleteMessageAsync(
          args.Message);
      }
      catch (Exception ex)
      {
        log.LogError(ex,
          "gift.receipt.job_failed " +
          "job_id={JobId}", msg.JobId);
        await args.AbandonMessageAsync(
          args.Message);  // retry / DLQ
      }
    };

    await processor.StartProcessingAsync(ct);
    await Task.Delay(Timeout.Infinite, ct);
  }
}

8.4 TVerificationResultCollection → ASP.NET Core Middleware + RFC 7807 ProblemDetails

Petra's gift-validation surface (TFinanceValidation_Gift.ValidateGiftBatchManual and its peers) signals errors by populating a TVerificationResultCollection reference parameter in-place; callers inspect HasCriticalErrors and unwind. This couples error reporting to the call-site rather than the protocol boundary, and it loses HTTP semantics entirely — every failure is HTTP 200 with a JSON-encoded verification collection. The modern equivalent is a typed exception hierarchy (GiftServiceError base with subclasses BatchAlreadyPostedException, FinancialPeriodClosedException, etc.) thrown from the domain service and caught by an app.UseExceptionHandler middleware that emits application/problem+json per RFC 7807, with the original verification context surfaced in extensions.

// csharp/ICT/Petra/Server/lib/MFinance/
// validation/Gift.Validation.cs lines 65-130

namespace Ict.Petra.Server.MFinance.Validation
{
  public static partial class
    TFinanceValidation_Gift
  {
    public static bool
    ValidateGiftBatchManual(
      object AContext,
      AGiftBatchRow ARow,
      ref TVerificationResultCollection
        AVerificationResultCollection,
      AAccountTable AAccountTableRef = null,
      /* ...8 more optional refs... */
      bool AValidateAccountCostCentre = false)
    {
      DataColumn ValidationColumn;
      TScreenVerificationResult VerificationResult;
      int VerifResultCollAddedCount = 0;

      // Don't validate posted rows
      if ((ARow.RowState ==
            DataRowState.Deleted) ||
          (ARow.BatchStatus ==
            MFinanceConstants.BATCH_POSTED))
      {
        return true;
      }

      ValidationColumn = ARow.Table.Columns[
        AGiftBatchTable.ColumnBankAccountCodeId];

      // Bank Account Code must be active
      if (!ARow.IsBankAccountCodeNull() &&
          (AAccountTableRef != null))
      {
        AAccountRow foundRow = (AAccountRow)
          AAccountTableRef.Rows.Find(
            new object[] {
              ARow.LedgerNumber,
              ARow.BankAccountCode });

        VerificationResult = (foundRow == null) ?
          new TScreenVerificationResult(
            new TVerificationResult(AContext,
              String.Format(Catalog.GetString(
                "Unknown bank account code '{0}'."),
                ARow.BankAccountCode),
              TResultSeverity.Resv_Critical),
            ValidationColumn) : null;

        if (AVerificationResultCollection
            .Auto_Add_Or_AddOrRemove(
              AContext, VerificationResult))
        {
          VerifResultCollAddedCount++;
        }

        /* ... 6 more bank-account checks,
           each populating the ref
           collection in-place ... */
      }

      return VerifResultCollAddedCount == 0;
    }
  }
}

// Errors/GiftServiceError.cs (hierarchy)

public abstract class GiftServiceError(
    string code,
    int status,
    string detail,
    IDictionary<string, object?>? extensions = null)
    : Exception(detail)
{
  public string Code => code;
  public int StatusCode => status;
  public IDictionary<string, object?> Extensions
    => extensions
       ?? new Dictionary<string, object?>();
}

public sealed class
  UnknownBankAccountException(
    int ledger, string code)
  : GiftServiceError(
      "gift.batch.unknown_bank_account",
      422,
      $"Unknown bank account code '{code}'.",
      new Dictionary<string, object?>
      {
        ["ledgerNumber"] = ledger,
        ["bankAccountCode"] = code
      });

// Validation/GiftBatchValidator.cs
// (the rule that previously populated
//  TVerificationResultCollection)

public sealed class GiftBatchValidator(
    GiftDbContext db) : IGiftBatchValidator
{
  public async Task EnsureValidAsync(
    GiftBatch batch, CancellationToken ct)
  {
    if (batch.BatchStatus == BatchStatus.Posted)
      throw new
        BatchAlreadyPostedException(
          batch.LedgerNumber,
          batch.BatchNumber);

    var account = await db.Accounts
      .Where(a =>
        a.LedgerNumber == batch.LedgerNumber
          && a.AccountCode ==
              batch.BankAccountCode)
      .SingleOrDefaultAsync(ct);

    if (account is null)
      throw new UnknownBankAccountException(
        batch.LedgerNumber,
        batch.BankAccountCode);

    if (!account.PostingStatus)
      throw new
        NonPostingAccountException(
          batch.LedgerNumber,
          batch.BankAccountCode);

    /* further checks throw their own
       typed exception subclasses */
  }
}

// Program.cs (middleware wiring)

app.UseExceptionHandler(opts =>
{
  opts.Run(async ctx =>
  {
    var ex = ctx.Features
      .Get<IExceptionHandlerFeature>()?.Error;

    if (ex is GiftServiceError g)
    {
      ctx.Response.StatusCode = g.StatusCode;
      ctx.Response.ContentType =
        "application/problem+json";

      var problem = new ProblemDetails
      {
        Type = $"urn:gift:{g.Code}",
        Title = g.Code,
        Status = g.StatusCode,
        Detail = g.Message
      };
      foreach (var kv in g.Extensions)
        problem.Extensions[kv.Key] = kv.Value;

      await ctx.Response
        .WriteAsJsonAsync(problem);
    }
  });
});

8.5 Section Boundary — What Belongs Here vs Section 9

The Gift Processing slice has two C# stacks — legacy .NET Framework 4.7 with .asmx + TDBTransaction + TVerificationResultCollection, and modern .NET 8 with Minimal APIs + EF Core 8 + RFC 7807 ProblemDetails. Section 8 is deliberately scoped to the framework-pattern translations between those two stacks: how an .asmx RPC endpoint becomes a Minimal API, how a TDBTransaction delegate becomes IDbContextTransaction, how a synchronous render becomes a Service Bus queued worker, and how a TVerificationResultCollection becomes a typed exception caught by middleware.

These framework-pattern translations are interesting precisely because both source and target are C#: the syntactic shift is what makes each translation worth showing — an idiomatic shift, not a language-family translation. The four examples above each cite a BR-GFT-XXX identifier in their notes column (BR-GFT-001, 002, 004, 005, 006), but only for the "the framework wiring above is what enforces this rule's invariant" framing. The rule's Given-When-Then specification, behavioral-fidelity classification (preserved-exactly vs deliberately-tightened vs flagged-for-PO-review), source citation, and target validator code all live in Section 9 (Business Rules Analysis) to avoid duplication. This split is most natural when source and target share a language family — the framework-vs-business-rule boundary is what keeps each section's job distinct.

One Gift-Processing-specific addition to the boundary contract: Translation #3 (Service Bus queued worker) crosses the service boundary, not just the framework boundary. The other three translations are within-process idiom shifts; the queued-worker pattern is the load-bearing seam between gift-processing-service and gift-receipting-service. Section 4 owns the service-architecture rationale; Section 8 shows the translation idiom; Section 9 (BR-GFT-004 receipt eligibility, BR-GFT-005 posted-batch immutability) carries the invariants the queued message must respect. The three sections are complementary readings of the same architectural decision.

Continue to Section 10: Data Mapping Strategy for the schema-preserved gift-domain tables and the six net-new operational tables that support the queued-worker pattern (render_job, rendered_receipt, sepa_export_file, bank_import_upload, bank_import_line, idempotency_keys).

9. Business Rules Analysis

This section documents the behavioral rules extracted from the Finance — Gift Processing slice of OpenPetra, showing C# / SQL / JavaScript source implementation alongside .NET 8 / Angular 18 translations with formal Given-When-Then specifications. Sixteen distinct rules were retrieved through Sage's entity analysis and verified against actual source files in csharp/ICT/Petra/Server/lib/MFinance/Gift/, csharp/ICT/Petra/Server/lib/MFinance/BankImport/, csharp/ICT/Petra/Server/sql/, csharp/ICT/Petra/Shared/lib/MFinance/, and js-client/src/forms/Finance/Gift/GiftReceipting/.

9.1 Business Rules Overview

Sage's entity analysis surfaced 24 candidate business-rule entities across the Finance — Gift Processing and Donations Processing subjects, plus targeted sweeps on tax / receipt / SEPA / posted / motivation / batch / gift name fragments. After deduplicating rules that appeared in two or more clusters with identical source-file evidence (8 same-rule overlaps), and excluding rules that fell outside the slice scope or below the confidence threshold (8 entries — see Catalog § "Excluded Sage Entities"), 16 distinct rules govern the gift-processing slice. Thirteen of the sixteen rules clear the agent's high-confidence threshold (≥ 0.75); the remaining three sit in the 0.70 band and are presented with their evidence intact.

The rules were extracted from 13 distinct source files spanning three architectural surfaces:

• Server-side gift-processing C# — Gift.Batch.cs, Gift.TaxDeductiblePct.cs, Gift.Adjustment.cs, Gift.gui.tools.cs (the 4 source files that hold the bulk of batch-state, tax-deductible, and motivation-defaulting policy)
• Bank-import C# — ImportFromMT940.cs, ImportFromCAMT.cs (German banking-code classification)
• Shared finance utilities C# — TaxDeductibility.cs (the percentage-bounds clamp and amount-derivation utility used by Gift.TaxDeductiblePct.cs)
• SQL queries — Gift.ReceiptPrinting.GetDonationsOfDonor.sql, ICH.HOSAReportGiftSummary.sql, Gift.Queries.ExtractDonorByAmount.sql (receipt eligibility, multi-currency aggregation, composite-key joins)
• Database upgrade scripts — Upgrade201911_201912.cs, Upgrade202206_202207.cs (the motivation-status correction and the SEPA-mandate column additions)
• Import / export plumbing — ImportExport.cs (the YML.GZ import default-values block)
• Report templates — methodofgiving.xml (the report-side posted-batch filter)
• Web client — PrintAnnualReceipts.js (the previous-calendar-year default for annual-receipt date range)

Rule Distribution by Category

Rule Discovery Methodology

Business rules were retrieved through Sage's entity catalog using get_entities_by_subject filtered to entity_type="business_rule" for both Finance — Gift Processing (7 rules) and Donations Processing (5 rules). To ensure breadth, eight additional search_entities sweeps were executed on the most likely rule-bearing name fragments (gift, tax, receipt, sepa, posted, motivation, batch) raising the candidate pool from 7 to 24. Pairwise comparison of rule descriptions and cited line references identified eight same-rule overlaps; the higher-confidence variant was retained and the cross-cluster convergence noted as additional evidence. The remaining catalog was filtered against the slice scope (excluding cross-cutting Partner-aggregate rules, GDPdU export rules that live in a separate finance-accounting tool, and Sponsorship-specific recurring-gift rules outside this slice) and a 0.50 confidence floor. BR-GFT-NNN identifiers were assigned by this analysis for traceability; they do not exist in the legacy source.

Each rule's Given-When-Then specification was derived by this workflow from Sage's plain-language description and verified against actual code retrieved via get_file_content_in_range. Of 8 file:line spot-checks performed, 7 were exact and 1 had a single-digit line drift (PrintAnnualReceipts.js — Sage cited line 25, actual is line 11; the file's 10-line GPL header offsets every cited line). Sage's basename match was correct in all cases.

Confidence-band finding for the financial code surface. Of 16 distinct rules, 13 clear the high-confidence threshold (≥ 0.75) and the remaining 3 sit at exactly 0.70. The mean confidence is 0.818. Two factors explain the strong lift: (a) gift-processing rules tend to be encoded in dedicated server-side methods with grep-able names (UpdateTaxDeductibiltyAmounts, GetLedgerDatePostingPeriod, BatchStatus = 'Posted') rather than buried inside form save handlers; (b) the 13 rule-bearing files cluster under MFinance/Gift/ and provide strong structural evidence for Sage's entity classifier. This means the catalog can be treated as authoritative without per-rule manual verification — the source code remains available for inspection, and any rule's concrete code has been spot-verified above.

9.2 Validation Rules

BR-GFT-002: Gift Batch Effective Date Period Validation

NewRow = AMainDS.AGiftBatch
    .NewRowTyped(true);

NewRow.LedgerNumber =
    ALedgerNumber;
NewRow.BatchNumber =
    ++ALedgerTbl[0]
        .LastGiftBatchNumber;

Int32 BatchYear, BatchPeriod;

// if DateEffective is outside the
// range of open periods, use the
// most fitting date
TFinancialYear
    .GetLedgerDatePostingPeriod(
        ALedgerNumber,
        ref ADateEffective,
        out BatchYear,
        out BatchPeriod,
        ATransaction,
        AForceEffectiveDateToFit);

NewRow.BatchYear = BatchYear;
NewRow.BatchPeriod = BatchPeriod;
NewRow.GlEffectiveDate =
    ADateEffective;
NewRow.ExchangeRateToBase = 1.0M;
NewRow.BatchDescription =
    "PLEASE ENTER A DESCRIPTION";
NewRow.BankAccountCode =
    info.GetDefaultBankAccount();
NewRow.BankCostCentre =
    info.GetStandardCostCentre();
NewRow.CurrencyCode =
    ALedgerTbl[0].BaseCurrency;
AMainDS.AGiftBatch.Rows.Add(NewRow);

public sealed class
    FinancialPeriodValidator
{
    private readonly
        IAccountingPeriodRepository _periods;

    public PeriodResolution Validate(
        int ledgerNumber,
        DateOnly proposed,
        bool silentSnap)
    {
        var open = _periods
            .GetOpenPeriods(ledgerNumber);

        var match = open.FirstOrDefault(p =>
            proposed >= p.StartDate
            && proposed <= p.EndDate);

        if (match is not null)
        {
            return new PeriodResolution(
                proposed,
                match.Year,
                match.Period);
        }

        if (!silentSnap)
        {
            throw new
                FinancialPeriodClosedException(
                    ledgerNumber, proposed);
        }

        // Force-fit: snap to nearest
        // open period boundary
        var snapped =
            open.SnapToNearest(proposed);

        return new PeriodResolution(
            snapped.Date,
            snapped.Year,
            snapped.Period);
    }
}

BR-GFT-010: Tax-Deductible Percentage Bounds 0..100%

if (AGiftDetail == null)
{
    return;
}
else if (AGiftDetail
    .IsTaxDeductiblePctNull())
{
    AGiftDetail.TaxDeductiblePct = 0.0m;
}

AGiftDetail.TaxDeductiblePct =
    Math.Max(
        AGiftDetail.TaxDeductiblePct, 0);
AGiftDetail.TaxDeductiblePct =
    Math.Min(
        AGiftDetail.TaxDeductiblePct, 100);

/* Update transaction amounts */
CalculateTaxDeductibilityAmounts(
    out TaxDeductAmount,
    out NonDeductAmount,
    AGiftDetail
        .GiftTransactionAmount,
    AGiftDetail.TaxDeductiblePct);

if (AGiftDetail
        .IsTaxDeductibleAmountNull()
    || AGiftDetail
        .IsNonDeductibleAmountNull()
    || (AGiftDetail.TaxDeductibleAmount
        != TaxDeductAmount)
    || (AGiftDetail.NonDeductibleAmount
        != NonDeductAmount))
{
    AGiftDetail.TaxDeductibleAmount =
        TaxDeductAmount;
    AGiftDetail.NonDeductibleAmount =
        NonDeductAmount;
}

public readonly record struct
    TaxDeductiblePercentage
{
    public decimal Value { get; }

    public TaxDeductiblePercentage(
        decimal value)
    {
        if (value < 0m || value > 100m)
        {
            throw new
                TaxDeductibleOutOfBoundsException(
                    value);
        }
        Value = value;
    }

    public static
        TaxDeductiblePercentage Default =>
            new(0m);
}

// FluentValidation rule
public sealed class
    GiftDetailDtoValidator
    : AbstractValidator<GiftDetailDto>
{
    public GiftDetailDtoValidator()
    {
        RuleFor(x => x.TaxDeductiblePct)
            .InclusiveBetween(0m, 100m)
            .WithMessage(
                "Tax-deductible percentage " +
                "must be between 0 and 100.");
    }
}

BR-GFT-004: Tax-Deductible Receipt Dual-Flag Eligibility

SELECT a_gift.a_date_entered_d,
       a_gift.a_first_time_gift_l,
       a_gift_detail.a_detail_number_i,
       a_gift_detail
           .a_gift_transaction_amount_n,
       a_gift_detail.a_gift_amount_n,
       a_gift_detail
           .a_tax_deductible_amount_n,
       ...
       Recipient.p_partner_short_name_c,
       a_motivation_detail
           .a_motivation_detail_desc_c
FROM a_gift_batch, a_gift,
     a_gift_detail, a_motivation_detail,
     a_account, a_cost_centre,
     p_partner AS GiftDestination,
     p_partner AS Recipient
WHERE a_gift_batch
        .a_ledger_number_i = ?
   AND a_gift_batch
        .a_batch_status_c = 'Posted'
   AND a_gift.a_ledger_number_i =
        a_gift_batch.a_ledger_number_i
   AND a_gift.a_batch_number_i =
        a_gift_batch.a_batch_number_i
   AND a_gift_detail.a_ledger_number_i =
        a_gift_batch.a_ledger_number_i
   AND a_gift_detail.a_batch_number_i =
        a_gift_batch.a_batch_number_i
   AND a_gift_detail
        .a_gift_transaction_number_i =
        a_gift.a_gift_transaction_number_i
   AND a_gift_batch.a_gl_effective_date_d
        BETWEEN ? AND ?
   AND a_gift.p_donor_key_n = ?
   AND a_gift.a_print_receipt_l = 1
   AND a_motivation_detail.a_receipt_l = 1
   AND a_gift_detail
        .a_modified_detail_l = 0

public sealed class
    ReceiptEligibilityFilter
{
    public IQueryable<GiftDetail> Apply(
        IQueryable<GiftDetail> q)
    {
        return q.Where(d =>
            d.Gift.Batch.Status ==
                BatchStatus.Posted
            && d.Gift.PrintReceipt
            && d.MotivationDetail
                .ReceiptEligible
            && !d.ModifiedDetail);
    }
}

public async Task<
    IReadOnlyList<ReceiptLine>>
    BuildAnnualReceiptAsync(
        long donorKey,
        int ledgerNumber,
        DateOnly start,
        DateOnly end,
        CancellationToken ct)
{
    var query = _db.GiftDetails
        .Include(d => d.Gift)
            .ThenInclude(g => g.Batch)
        .Include(d =>
            d.MotivationDetail)
        .Include(d => d.RecipientPartner)
        .Where(d =>
            d.Gift.DonorKey == donorKey
            && d.Gift.Batch.LedgerNumber
                == ledgerNumber
            && d.Gift.Batch
                .GlEffectiveDate >= start
            && d.Gift.Batch
                .GlEffectiveDate <= end);

    query = _eligibility.Apply(query);

    return await query
        .Select(d => ToReceiptLine(d))
        .ToListAsync(ct);
}

BR-GFT-011: Gift Import Default Values

if (ATableName == "a_gift")
{
    if (!RowDetails.ContainsKey(
            "LinkToPreviousGift")
        || RowDetails["LinkToPreviousGift"]
            == string.Empty)
    {
        RowDetails["LinkToPreviousGift"] =
            "false";
    }
    if (!RowDetails.ContainsKey(
            "PrintReceipt")
        || RowDetails["PrintReceipt"]
            == string.Empty)
    {
        RowDetails["PrintReceipt"] =
            "true";
    }
}

public sealed record GiftImportRecord
{
    public required long DonorKey
        { get; init; }

    public required decimal Amount
        { get; init; }

    [DefaultValue(false)]
    public bool LinkToPreviousGift
        { get; init; } = false;

    [DefaultValue(true)]
    public bool PrintReceipt
        { get; init; } = true;

    public string? Comment
        { get; init; }

    public string MotivationGroup
        { get; init; } = string.Empty;

    public string MotivationDetail
        { get; init; } = string.Empty;
}

// On JSON deserialization, missing
// fields use the property defaults.
// Same defaults apply to direct API
// calls, so the two ingest paths share
// behavior.

Additional validation rules are documented in the catalog: BR-GFT-012 (Gift Composite-Key Hierarchy Integrity, 0.77 — preserved as EF Core composite primary keys, no schema change).

9.3 Calculation Rules

BR-GFT-001: Sequential Gift Batch Numbering

AGiftBatchRow NewRow = null;

try
{
    NewRow = AMainDS.AGiftBatch
        .NewRowTyped(true);

    NewRow.LedgerNumber =
        ALedgerNumber;

    // Atomic pre-increment of the
    // ledger's LastGiftBatchNumber:
    // serializes batch creation per
    // ledger via the ledger-row lock
    // taken by the enclosing
    // TDBTransaction.
    NewRow.BatchNumber =
        ++ALedgerTbl[0]
            .LastGiftBatchNumber;

    Int32 BatchYear, BatchPeriod;
    TFinancialYear
        .GetLedgerDatePostingPeriod(
            ALedgerNumber,
            ref ADateEffective,
            out BatchYear,
            out BatchPeriod,
            ATransaction,
            AForceEffectiveDateToFit);

    // ... batch defaults ...

    AMainDS.AGiftBatch.Rows.Add(NewRow);
}
catch (Exception ex)
{
    TLogging.LogException(ex,
        Utilities.GetMethodSignature());
    throw;
}

return NewRow;

public async Task<GiftBatch>
    CreateBatchAsync(
        int ledgerNumber,
        DateOnly effectiveDate,
        bool silentSnap,
        CancellationToken ct)
{
    await using var tx = await _db
        .Database
        .BeginTransactionAsync(
            IsolationLevel.Serializable,
            ct);

    var ledger = await _db.Ledgers
        .Where(l =>
            l.LedgerNumber == ledgerNumber)
        .FirstAsync(ct);

    // Period validation (BR-GFT-002)
    var resolution = _periods.Validate(
        ledgerNumber,
        effectiveDate,
        silentSnap);

    // Sequential numbering (BR-GFT-001)
    ledger.LastGiftBatchNumber += 1;
    var batchNumber =
        ledger.LastGiftBatchNumber;

    var batch = new GiftBatch
    {
        LedgerNumber = ledgerNumber,
        BatchNumber = batchNumber,
        Status = BatchStatus.Unposted,
        BatchYear = resolution.Year,
        BatchPeriod = resolution.Period,
        GlEffectiveDate =
            resolution.Date,
        ExchangeRateToBase = 1.0m,
        BatchDescription =
            "PLEASE ENTER A DESCRIPTION",
        CurrencyCode =
            ledger.BaseCurrency
    };

    _db.GiftBatches.Add(batch);
    await _db.SaveChangesAsync(ct);
    await tx.CommitAsync(ct);

    return batch;
}

BR-GFT-003: Tax-Deductible Recalculation on Percentage Change

db.SelectDT(Table, Query, Transaction);

// update fields for each row
for (int i = 0;
     i < Table.Rows.Count;
     i++)
{
    AGiftDetailRow Row = Table[i];

    Row.TaxDeductiblePct = ANewPct;
    TaxDeductibility
        .UpdateTaxDeductibiltyAmounts(
            ref Row);
}

AGiftDetailAccess.SubmitChanges(
    Table, Transaction);

SubmissionOK = true;

public sealed class
    TaxDeductibilityCalculator
{
    public void Apply(
        GiftDetail row,
        TaxDeductiblePercentage newPct)
    {
        row.TaxDeductiblePct =
            newPct.Value;

        // Transaction-currency split
        row.TaxDeductibleAmount =
            row.GiftTransactionAmount
                * (newPct.Value / 100m);
        row.NonDeductibleAmount =
            row.GiftTransactionAmount
                - row.TaxDeductibleAmount;

        // Base-currency split
        row.TaxDeductibleAmountBase =
            row.GiftAmount
                * (newPct.Value / 100m);
        row.NonDeductibleAmountBase =
            row.GiftAmount
                - row.TaxDeductibleAmountBase;
    }
}

public async Task<int>
    AdjustTaxDeductiblePctAsync(
        long recipientKey,
        DateOnly fromDate,
        TaxDeductiblePercentage newPct,
        CancellationToken ct)
{
    var rows = await _db.GiftDetails
        .Where(/* recipient + date */)
        .ToListAsync(ct);

    foreach (var row in rows)
    {
        _calculator.Apply(row, newPct);
    }

    await _db.SaveChangesAsync(ct);
    return rows.Count;
}

BR-GFT-008: Annual Receipt Default Date Range = Previous Calendar Year

$(function() {
    var year =
        (new Date()).getYear()
        + 1900 - 1;

    $("#StartDate").val(
        year + "-01-01");
    $("#EndDate").val(
        year + "-12-31");

    LoadDefaultTemplateFiles();
});

@Component({
    selector:
        'app-print-annual-receipts',
    standalone: true,
    imports: [ReactiveFormsModule],
    templateUrl:
        './print-annual-receipts.html'
})
export class
    PrintAnnualReceiptsComponent
    implements OnInit
{
    form = this.fb.group({
        startDate:
            ['', Validators.required],
        endDate:
            ['', Validators.required],
        templateFiles: [[]]
    });

    constructor(
        private fb: FormBuilder,
        private receipts:
            ReceiptingClient
    ) {}

    ngOnInit(): void {
        const lastYear =
            new Date().getFullYear() - 1;

        this.form.patchValue({
            startDate:
                `${lastYear}-01-01`,
            endDate:
                `${lastYear}-12-31`
        });

        this.receipts
            .loadDefaultTemplates()
            .subscribe(/* ... */);
    }
}

Additional calculation rule: BR-GFT-009 (Multi-Currency Three-Amount Tracking, 0.83) — preserved at the schema level as a six-column shape on a_gift_detail (transaction-currency: a_gift_transaction_amount_n, a_tax_deductible_amount_n, a_non_deductible_amount_n; base-currency: a_gift_amount_n, a_tax_deductible_amount_base_n, a_non_deductible_amount_base_n). EF Core entities expose them as typed Money value objects. ICH HOSA reports continue to aggregate by base currency only.

9.4 State Transition Rules

BR-GFT-005: Posted-Batch-Only Financial Reporting (Posted-Batch Immutability)

<detailreports>
  <detailreport
    id="Get all the gifts with selected
        Method of Giving"
    action="GiftTransactions/
        GiftTransactionsDefaultDetail
        .xml">
    <parameter name="title2"
      value="Gift Totals of Method of
        Giving {{param_Method}}"/>
    <parameter name="period1"
      value="From {{param_start_date}}
        to {{param_end_date}}"/>
    <detailreportquery>
      batch.a_gl_effective_date_d
        BETWEEN
          {#param_start_date#} AND
          {#param_end_date#}
      AND batch.a_batch_status_c
        = "Posted"
      AND motivation.a_receipt_l = TRUE
      AND (gift.a_method_of_giving_code_c
            = {param_Method}
        OR ({param_Method} = ''
            AND gift
              .a_method_of_giving_code_c
              IS NULL))
      AND batch.a_currency_code_c
        = {param_Currency}
    </detailreportquery>
  </detailreport>
</detailreports>

public enum BatchStatus
{
    Unposted,
    Posted,
    Cancelled
}

// Write guard: any service method
// that mutates a batch must call
// EnforceMutable first.
internal static class
    GiftBatchInvariants
{
    public static void EnforceMutable(
        GiftBatch batch)
    {
        if (batch.Status ==
                BatchStatus.Posted)
        {
            throw new
                BatchAlreadyPostedException(
                    batch.LedgerNumber,
                    batch.BatchNumber);
        }
    }
}

// Posted-batch report filter: typed
// LINQ predicate composable across
// every gift report query.
public static class
    GiftBatchQueryExtensions
{
    public static
        IQueryable<GiftBatch>
        OnlyPosted(
            this IQueryable<GiftBatch> q)
        => q.Where(b =>
            b.Status ==
                BatchStatus.Posted);
}

BR-GFT-006: Modified-Detail Flag Blocks Duplicate Reversals

foreach (DataRowView RowView in
    AGiftDS.AGiftDetail.DefaultView)
{
    AGiftDetailRow GiftDetailRow =
        (AGiftDetailRow)RowView.Row;

    if (GiftDetailRow.ModifiedDetail)
    {
        Message += "\n" + String.Format(
            Catalog.GetString(
                "Gift {0} with Detail {1} " +
                "in Batch {2}"),
            GiftDetailRow
                .GiftTransactionNumber,
            GiftDetailRow.DetailNumber,
            GiftDetailRow.BatchNumber);

        GiftCount++;
    }
}

if (GiftCount != 0)
{
    if (GiftCount > 1)
    {
        Message = String.Format(
            Catalog.GetString(
                "Cannot reverse or adjust " +
                "the following gifts:"))
            + "\n" + Message
            + "\n\n"
            + Catalog.GetString(
                "They have already been " +
                "adjusted or reversed.");
    }
    else if (GiftCount == 1)
    {
        Message = String.Format(
            Catalog.GetString(
                "Cannot reverse or adjust " +
                "the following gift:"))
            + "\n" + Message
            + "\n\n"
            + Catalog.GetString(
                "It has already been " +
                "adjusted or reversed.");
    }

    AMessages.Add(
        new TVerificationResult(null,
            Message,
            TResultSeverity.Resv_Critical));
}

public sealed class
    GiftAlreadyAdjustedException
    : DomainException
{
    public IReadOnlyList<
        GiftDetailReference>
        AlreadyAdjusted { get; }

    public GiftAlreadyAdjustedException(
        IReadOnlyList<
            GiftDetailReference> refs)
        : base(
            "Cannot reverse or adjust " +
            "gifts that have already " +
            "been adjusted or reversed.")
    {
        AlreadyAdjusted = refs;
    }
}

public async Task PrepareReversalAsync(
    IReadOnlyList<
        GiftDetailReference> targets,
    CancellationToken ct)
{
    var rows = await _db.GiftDetails
        .Where(d =>
            targets.Select(t =>
                t.CompositeKey)
                .Contains(d.CompositeKey))
        .ToListAsync(ct);

    var alreadyAdjusted = rows
        .Where(r => r.ModifiedDetail)
        .Select(r => r.ToReference())
        .ToList();

    if (alreadyAdjusted.Count > 0)
    {
        // All-or-nothing: even one
        // already-adjusted detail
        // aborts the entire reversal.
        throw new
            GiftAlreadyAdjustedException(
                alreadyAdjusted);
    }

    // ... write the paired reversal/
    //     correction rows ...
}

Additional state-transition rule: BR-GFT-013 (Motivation Detail Active-Status Default, 0.77) — preserved as MotivationDetail.IsActive with default true; the historical activation-state correction in Upgrade201911_201912.cs:48 remains in the migration history but the bug it fixed does not regress because the new entity defaults to active.

9.5 Workflow Rules

BR-GFT-007: German Banking Code Gift Detection

row.DateEffective = tr.valueDate;
row.TransactionAmount = tr.amount;
row.Description = tr.description;
row.TransactionTypeCode = tr.typecode;

// see the codes:
// http://www.hettwer-beratung.de/
//   sepa-spezialwissen/...
if ((row.TransactionTypeCode == "052")
    || (row.TransactionTypeCode == "051")
    || (row.TransactionTypeCode == "053")
    || (row.TransactionTypeCode == "067")
    || (row.TransactionTypeCode == "068")
    || (row.TransactionTypeCode == "069")
    || (row.TransactionTypeCode == "119")
    || (row.TransactionTypeCode == "152")
    || (row.TransactionTypeCode == "166")
    || (row.TransactionTypeCode == "169"))
{
    row.TransactionTypeCode +=
        MFinanceConstants
            .BANK_STMT_POTENTIAL_GIFT;
}

MainDS.AEpTransaction.Rows.Add(row);

// appsettings.json
// {
//   "GiftDetection": {
//     "GermanBankingCodes": [
//       "052", "051", "053",
//       "067", "068", "069",
//       "119", "152", "166", "169"
//     ]
//   }
// }

public sealed class GiftDetectionRule
{
    private readonly HashSet<string>
        _giftCodes;

    public GiftDetectionRule(
        IOptions<
            GiftDetectionOptions> opt)
    {
        _giftCodes = new(
            opt.Value.GermanBankingCodes,
            StringComparer.Ordinal);
    }

    public TransactionClassification
        Classify(
            BankImportLine line)
    {
        if (_giftCodes.Contains(
                line.TransactionTypeCode)
            && line.TransactionAmount > 0m)
        {
            return TransactionClassification
                .PotentialGift;
        }
        return TransactionClassification
            .Other;
    }
}

BR-GFT-014: Partner-Class-Driven Motivation Defaulting

// 1. Look up partner-specific
//    motivation override
bool KeyMinFound = false;

AMotivationDetailTable
    MotivationDetailTable
    = AMotivationDetailAccess
        .LoadViaPPartner(
            APartnerKey, readTransaction);

if (MotivationDetailTable != null
    && MotivationDetailTable.Rows.Count
        > 0)
{
    foreach (AMotivationDetailRow Row
        in MotivationDetailTable.Rows)
    {
        if (Row.MotivationStatus)
        {
            motivationGroup =
                MotivationDetailTable[0]
                    .MotivationGroupCode;
            motivationDetail =
                MotivationDetailTable[0]
                    .MotivationDetailCode;
            KeyMinFound = true;
            break;
        }
    }
}

// 2. Fallback: unit-type switch
if (!KeyMinFound)
{
    PUnitTable pUnitTable =
        PUnitAccess.LoadByPrimaryKey(
            APartnerKey, readTransaction);

    if (pUnitTable.Rows.Count == 1)
    {
        PUnitRow unitRow = pUnitTable[0];

        switch (unitRow.UnitTypeCode)
        {
            case MPartnerConstants
                .UNIT_TYPE_AREA:
            case MPartnerConstants
                .UNIT_TYPE_FUND:
            case MPartnerConstants
                .UNIT_TYPE_FIELD:
                motivationDetail =
                    MFinanceConstants
                        .GROUP_DETAIL_FIELD;
                break;

            case MPartnerConstants
                .UNIT_TYPE_KEYMIN:
                motivationDetail =
                    MFinanceConstants
                      .GROUP_DETAIL_KEY_MIN;
                break;

            // others: no default
        }
    }
}

public sealed class MotivationResolver
{
    private readonly GiftDbContext _db;

    public MotivationResolver(
        GiftDbContext db) => _db = db;

    public async Task<
        ResolvedMotivation?>
        ResolveDefaultAsync(
            long partnerKey,
            CancellationToken ct)
    {
        // 1. Partner-specific override
        var partnerOverride =
            await _db.MotivationDetails
                .Where(m =>
                    m.RecipientPartnerKey
                        == partnerKey
                    && m.IsActive)
                .FirstOrDefaultAsync(ct);

        if (partnerOverride is not null)
        {
            return new ResolvedMotivation(
                partnerOverride
                    .MotivationGroupCode,
                partnerOverride
                    .MotivationDetailCode);
        }

        // 2. Unit-type fallback
        var unit = await _db.Units
            .Where(u =>
                u.PartnerKey == partnerKey)
            .FirstOrDefaultAsync(ct);

        if (unit is null)
            return null;

        return unit.UnitType switch
        {
            UnitType.Area
                or UnitType.Fund
                or UnitType.Field
                => new ResolvedMotivation(
                    "GIFT",
                    "FIELD"),

            UnitType.KeyMin
                => new ResolvedMotivation(
                    "GIFT",
                    "KEYMIN"),

            _ => null
        };
    }
}

Additional workflow rule: BR-GFT-015 (Recurring-Gift SEPA Mandate Tracking, 0.70) — the a_recurring_gift table carries a_sepa_mandate_reference_c (varchar(35)) and a_sepa_mandate_given_d (date) per the 2022.07 DB upgrade; the SEPA export worker generates ISO 20022 pain.008 XML with these fields populated. Recommended for product-owner review: the donor-key + YYYYMMDD format convention referenced in the target-architecture handoff is not enforced by the schema (only varchar(35) length); confirm whether to codify in a typed value object.

9.6 Authorization & Privacy Rules

BR-GFT-016: Confidential Gift Privacy via Partner Double-Join

SELECT ...
       GiftDestination
           .p_partner_short_name_c
           AS FieldName,
       Recipient
           .p_partner_short_name_c
           AS RecipientName,
       Recipient
           .p_partner_short_name_loc_c
           AS RecipientLocalName,
       Recipient.p_partner_key_n
           AS RecipientKey,
       ...
FROM a_gift_batch, a_gift,
     a_gift_detail,
     a_motivation_detail,
     a_account, a_cost_centre,
     p_partner AS GiftDestination,
     p_partner AS Recipient
WHERE ...
   AND GiftDestination.p_partner_key_n
        = a_gift_detail
            .a_recipient_ledger_number_n
   AND Recipient.p_partner_key_n
        = a_gift_detail
            .p_recipient_key_n
   ...

public class GiftDetail
{
    public long RecipientLedgerNumber
        { get; set; }
    public long RecipientPartnerKey
        { get; set; }

    public Partner
        RecipientLedgerPartner
        { get; set; } = null!;

    public Partner RecipientPartner
        { get; set; } = null!;
}

public sealed record ReceiptLine(
    DateOnly DateEntered,
    decimal TransactionAmount,
    string Currency,
    decimal TaxDeductibleAmount,
    decimal NonDeductibleAmount,
    string FieldName,
    string? RecipientName,
    string MotivationDescription);

public ReceiptLine ToReceiptLine(
    GiftDetail d,
    bool donorMayKnowRecipient)
{
    return new ReceiptLine(
        d.Gift.DateEntered,
        d.GiftTransactionAmount,
        d.Gift.Batch.CurrencyCode,
        d.TaxDeductibleAmount,
        d.NonDeductibleAmount,
        d.RecipientLedgerPartner
            .ShortName,           // Field
        donorMayKnowRecipient
            ? d.RecipientPartner
                .ShortName
            : null,               // Recipient
        d.MotivationDetail
            .Description);
}

9.7 Business Rule Traceability

File paths in this section refer to repository-relative paths under the OpenPetra source tree. Sage's Line References field stores qualified paths for most references; basename-only references were resolved via search_files before citation. The single line-anchor drift (PrintAnnualReceipts.js — Sage cited line 25, actual is line 11) is documented above; the file's GPL header offsets the citation by 14 lines. All other 14 cited file:line references were verified exactly via get_file_content_in_range.

9.8 Rule Validation Strategy

Unit Testing Approach

Each business rule maps to an xUnit test fixture in either GiftProcessingService.Tests or GiftReceiptingService.Tests. Validation rules (BR-GFT-002, BR-GFT-010, BR-GFT-011, BR-GFT-012, plus filter rules BR-GFT-004) are tested by exercising the corresponding domain validator / value object / LINQ predicate with both compliant and non-compliant inputs and asserting expected exception types and HTTP problem codes. Calculation rules (BR-GFT-001, BR-GFT-003, BR-GFT-008, BR-GFT-009) are tested with parametric inputs covering precision-edge cases (multi-currency rounding, percentage = 0/100/null, year boundaries). State-transition rules (BR-GFT-005, BR-GFT-006, BR-GFT-013) are tested with in-memory-database fixtures asserting that posted-batch mutations throw, modified-detail reversals abort, and motivation creation defaults to active. Workflow rules (BR-GFT-007, BR-GFT-014, BR-GFT-015) are tested via service-level fixtures with seeded reference data.

Integration Testing Approach

Integration tests verify rule interactions across the gift lifecycle: bank-statement import (BR-GFT-007 detection) → gift batch creation (BR-GFT-001 numbering, BR-GFT-002 period) → gift detail entry (BR-GFT-014 motivation defaulting, BR-GFT-010 percentage bounds) → tax-deductible adjustment (BR-GFT-003 recalculation, BR-GFT-006 idempotence) → batch posting → annual-receipt generation (BR-GFT-004 eligibility, BR-GFT-008 date range, BR-GFT-016 confidentiality). The test suite uses Testcontainers-hosted PostgreSQL with the existing gift-domain schema seeded from a known-good donation fixture and Service Bus emulator for the receipt-batch / SEPA-export queue interactions.

Behavioral Equivalence Approach (Golden Master)

For the duration of coexistence, the modernized gift services run in a side-by-side configuration with the legacy TGiftTransactionWebConnector. A scheduled equivalence harness submits a synthetic request set (create batch, enter gifts, adjust tax-deductible-pct, post batch, generate receipts, import bank statement, match transactions) to both stacks and compares: (1) success/failure outcomes, (2) HTTP-equivalent status codes (legacy verification-result severity mapped to RFC 7807 problem types), (3) every amount column on every gift detail row to four decimal places, and (4) the rendered annual-receipt PDFs by SHA-256 of canonicalised text content. The two highest-impact rules (BR-GFT-004 receipt eligibility, BR-GFT-005 posted-batch immutability) have golden-master tests required per the target-architecture handoff's testing decision — behavioral divergence on either is a release blocker.

10. Data Mapping Strategy

This section documents the data-tier transformation for the Finance — Gift Processing slice. The headline is unusual for a modernization plan: the gift-domain schema is preserved end-to-end. Petra's eight gift-domain tables (a_gift_batch, a_gift, a_gift_detail, a_motivation_group, a_motivation_detail, a_recurring_gift_batch, a_recurring_gift, a_recurring_gift_detail) carry years of posted financial transactions and are the system of record for downstream finance reporting. The migration does not touch them. Six small operational tables are introduced — render_job, rendered_receipt, sepa_export_file, bank_import_upload, bank_import_line, idempotency_keys — not to remodel the financial domain but to give the queued-worker pattern (introduced in Section 4 and shown in Section 8.3) and the strangler-fig coexistence pattern the job-tracking, provenance, and idempotency rows they require. The PostgreSQL engine itself is preserved.

10.1 Legacy Data Architecture

The Gift Processing subsystem reads from and writes to eight gift-domain tables, all defined in db/petra.xml (the project-wide canonical schema, 24,821 lines) and projected into a typed dataset called GiftBatchTDS. The dataset is defined declaratively in csharp/ICT/Petra/Shared/lib/MFinance/data/Finance.Gift.TypedDataSets.xml (80 lines) and code-generated at build time into a strongly-typed C# class hierarchy by TDataDefinitionParser. The generated class participates in transactional reads (db.ReadTransaction) and writes (SubmitChanges per-table cascading calls) at every TGiftTransactionWebConnector entry point. All data lives in the same PostgreSQL instance; there is no fixed-length-file storage anywhere in the path.

erDiagram
  A_LEDGER ||--o{ A_GIFT_BATCH : "owns numbered batches"
  A_GIFT_BATCH ||--o{ A_GIFT : "contains gifts"
  A_GIFT ||--o{ A_GIFT_DETAIL : "splits into detail lines"
  A_GIFT_DETAIL }o--|| A_MOTIVATION_DETAIL : "categorised by (composite FK ledger+group+detail)"
  A_MOTIVATION_DETAIL }o--|| A_MOTIVATION_GROUP : "in group (composite FK ledger+group)"
  A_GIFT }o--|| P_PARTNER : "donor (p_donor_key_n)"
  A_GIFT_DETAIL }o--|| P_PARTNER : "recipient (p_recipient_key_n)"

  A_RECURRING_GIFT_BATCH ||--o{ A_RECURRING_GIFT : "contains recurring gifts"
  A_RECURRING_GIFT ||--o{ A_RECURRING_GIFT_DETAIL : "splits into detail lines"
  A_RECURRING_GIFT_DETAIL }o--|| A_MOTIVATION_DETAIL : "categorised by (composite FK)"
  A_RECURRING_GIFT }o--|| P_PARTNER : "donor (p_donor_key_n)"

  A_GIFT_BATCH {
    int a_ledger_number_i PK
    int a_batch_number_i PK
    varchar a_batch_description_c "X(40)"
    varchar a_batch_status_c "Unposted|Posted|Cancelled — see deviation in 10.4"
    int a_batch_period_i "1..20"
    int a_batch_year_i
    date a_gl_effective_date_d
    varchar a_currency_code_c "X(8)"
    decimal a_batch_total_n "NUMERIC(24,10)"
    decimal a_hash_total_n "NUMERIC(24,10)"
    decimal a_exchange_rate_to_base_n "NUMERIC(24,10)"
    varchar a_bank_cost_centre_c "X(12)"
    varchar a_bank_account_code_c "X(9)"
    varchar a_gift_type_c "X(8) default Gift"
    varchar a_method_of_payment_code_c "X(8)"
    int a_last_gift_number_i
    date s_modification_date_d
  }

  A_GIFT {
    int a_ledger_number_i PK
    int a_batch_number_i PK
    int a_gift_transaction_number_i PK
    bigint p_donor_key_n FK
    varchar a_method_of_giving_code_c
    varchar a_method_of_payment_code_c
    varchar a_receipt_letter_code_c
    boolean a_print_receipt_l
    boolean a_first_time_gift_l
    boolean a_link_to_previous_gift_l
    boolean a_admin_charge_l
    boolean a_restricted_l
    date a_date_entered_d
    varchar a_reference_c "X(10)"
  }

  A_GIFT_DETAIL {
    int a_ledger_number_i PK
    int a_batch_number_i PK
    int a_gift_transaction_number_i PK
    int a_detail_number_i PK
    bigint p_recipient_key_n FK
    bigint a_recipient_ledger_number_n
    varchar a_motivation_group_code_c FK
    varchar a_motivation_detail_code_c FK
    decimal a_gift_transaction_amount_n "NUMERIC(24,10)"
    decimal a_gift_amount_n "base ledger currency"
    decimal a_gift_amount_intl_n "international currency"
    decimal a_tax_deductible_pct_n "NUMERIC(5,2)"
    boolean a_confidential_gift_flag_l "lives here, not on a_gift"
    boolean a_modified_detail_l
    boolean a_tax_deductible_l
  }

  A_MOTIVATION_DETAIL {
    int a_ledger_number_i PK
    varchar a_motivation_group_code_c PK
    varchar a_motivation_detail_code_c PK "X(8) — width is the source of the seed-data 'MED-EQUIPT' overflow noted in 10.7"
    varchar a_account_code_c "default GL account"
    varchar a_cost_centre_code_c "default cost centre"
    boolean a_tax_deductible_l
    boolean a_membership_l
    boolean a_sponsorship_l
    boolean a_worker_support_l
  }

  A_RECURRING_GIFT_BATCH {
    int a_ledger_number_i PK
    int a_batch_number_i PK
    varchar a_currency_code_c "X(8)"
    varchar a_batch_description_c "X(40) nullable — unlike a_gift_batch which is notnull"
    decimal a_batch_total_n "NUMERIC(24,10)"
  }

  A_RECURRING_GIFT {
    int a_ledger_number_i PK
    int a_batch_number_i PK
    int a_gift_transaction_number_i PK
    bigint p_donor_key_n FK
    varchar a_reference_c "X(8) — narrower than a_gift.a_reference_c X(10)"
    varchar a_sepa_mandate_reference_c "X(35) — donor-key + YYYYMMDD; lives HERE not on the batch row"
    date a_sepa_mandate_given_d
    varchar a_charge_status_c "X(10)"
    date a_last_debit_d
    int a_debit_day_i
    boolean a_active_l
  }

  A_RECURRING_GIFT_DETAIL {
    int a_ledger_number_i PK
    int a_batch_number_i PK
    int a_gift_transaction_number_i PK
    int a_detail_number_i PK
    bigint p_recipient_key_n FK
    decimal a_gift_amount_n
    boolean a_confidential_gift_flag_l
    date a_start_donations_d
    date a_end_donations_d
  }
    

Legacy ER diagram — the eight gift-domain tables consumed by GiftBatchTDS, sourced from db/petra.xml and reproduced from the schema-decisions handoff. All eight tables are preserved unchanged in the target. Three relationships worth highlighting: (1) the SEPA mandate columns (a_sepa_mandate_reference_c, a_sepa_mandate_given_d) live on a_recurring_gift — the per-donor row — not on a_recurring_gift_batch; (2) a_confidential_gift_flag_l lives on the per-line a_gift_detail table, not on the donor-side a_gift header; (3) the FK from a_gift_detail to a_motivation_detail is a composite three-column key (a_ledger_number_i, a_motivation_group_code_c, a_motivation_detail_code_c), not the single-column reference a flat reading might suggest.

10.2 Target Data Architecture

The target preserves the PostgreSQL engine, the partner-key identity space (p_partner.p_partner_key_n), the four legacy reference-data tables that gift services consume read-only (a_ledger, a_currency, a_account, p_partner), and every column of every gift-domain table. The data-tier delta is therefore narrow: six operational tables that exist only because the queued-worker pattern and the strangler-fig coexistence pattern need them.

Note — the FK fragment from bank_import_line to a_gift_detail is the only point where a new operational table references a legacy gift-domain row. It is recorded as a four-column nullable reference (matched_ledger_number, matched_batch_number, matched_gift_transaction_number, matched_detail_number); the V1 handoff records single-column FKs only, so the composite-key constraint is materialised at deploy time. The reverse direction does not exist: posted gift-detail rows are immutable (BR-GFT-005) and never deleted, so the SET-NULL semantics on rollback are defensive belt-and-braces, not a routinely-exercised path.

For the complete target data model ER diagram showing all entity relationships, see Section 4.4: Data Model.

10.3 The Preservation Decision

Why does the gift-domain schema stay? Three reasons compound:

1. It is the system of record for years of posted batches. a_gift_batch, a_gift, and a_gift_detail hold every donation Petra has processed since deployment, including batches whose a_batch_status_c='Posted' rows are immutable per BR-GFT-005. Migrating the data shape would mean migrating the data, and migrating the data of a financial system of record is an order-of-magnitude harder problem than migrating the code that reads it — reconciliation, dual-write windows, posted-batch-checksum validation, and tax-authority audit consistency would all be in scope. The slice does not require any of that to deliver the user-visible improvements documented in Sections 7 and 8.
2. Downstream finance reporting reads the same tables. Out of the eight gift-domain tables, six are also consumed by GL posting (a_transaction / a_journal writes derive from a_gift_detail's motivation defaults), by donor-history reports, by tax-receipt aggregations, and by the cross-reference report queries listed in Section 4.4's indexing additions. Renaming a column or splitting a table would force rewrites in code paths the slice does not own. Preserving the schema means the slice changes nothing for those readers.
3. The case for redesign is weak. The schema is well-normalised, FK-constrained, partner-key-aligned, and supports the multi-currency three-amount-per-line pattern (a_gift_transaction_amount_n in donor currency, a_gift_amount_n in ledger base currency, a_gift_amount_intl_n in the ledger's international rollup currency, all NUMERIC(24,10)) that the domain genuinely requires. There is no obvious schema-design improvement that would justify the migration cost. The legacy code that reads the schema (typed datasets, code-gen pipeline, RPC web-connectors) has well-known modernisation wins (Sections 7, 8); the legacy schema does not.

The preservation decision means that for the eight gift-domain tables there is no DDL change, no data migration, no shadow-write phase, and no read-from-old / write-to-new dual-path window. The only thing that changes about how those tables are touched is the code that touches them — that is the subject of section 10.4 and the entire body of Section 8.

10.4 The Code-Generation Pipeline Retirement

Petra's legacy data-access path is a code-generation pipeline:

flowchart LR
  A["db/petra.xml
(canonical schema, 24,821 lines)"] -->|TDataDefinitionParser
NAnt build target| B["Generated DAL classes
(per-table CRUD + access layer)"]
  C["Finance.Gift.TypedDataSets.xml
(80 lines)"] -->|TDataDefinitionParser
+ TTypedDataSetGenerator| D["GiftBatchTDS.Generated.cs
+ GiftBatchTDSAccess.cs
(strongly-typed dataset)"]
  A -.references.-> C
  B --> E["TGiftTransactionWebConnector
+ TGiftBatchFunctions
(business logic reads/writes via TDS)"]
  D --> E
    

Legacy data-access pipeline. petra.xml defines the schema once; the typed-dataset XML names which tables a given subsystem cares about plus a few subsystem-specific custom fields; the parser plus typed-dataset generator together emit C# classes at build time; web-connectors compose business logic on top of the typed dataset.

For the gift slice, every leg of this pipeline is retired in favour of EF Core 8 code-first — but the schema itself is preserved. EF Core does not rewrite the tables; it provides a different way for the new C# code to read and write the same rows.

The schema is preserved; the way the C# code accesses it changes. Below, side-by-side: the legacy generated typed-dataset schema declaration (column 1), the existing physical PostgreSQL DDL that both the legacy code and the new code target (column 2, byte-faithful to db/petra.xml via the schema-decisions handoff), and the EF Core 8 entity that maps the new code to those existing physical tables (column 3).

<!-- Finance.Gift.TypedDataSets.xml -->
<DataSet name="GiftBatchTDS">
  <Table sqltable="a_ledger"/>
  <Table sqltable="a_gift_batch">
    <CustomField name="GiftBatchTotal"
                 type="Decimal"/>
  </Table>
  <Table sqltable="a_gift">
    <CustomField name="DonorName"
                 type="String"/>
    <CustomField name="GiftTotal"
                 type="Decimal"/>
  </Table>
  <Table sqltable="a_gift_detail">
    <CustomField name="DonorKey"
                 type="Int64"/>
    <CustomField name="DonorName"
                 type="String"/>
    <CustomField name="DonorClass"
                 type="String"/>
    <CustomField name="DateEntered"
                 type="DateTime"/>
    <CustomField name="RecipientDescription"
                 type="String"/>
    // ...11 more custom fields
  </Table>
  <Table sqltable="a_recurring_gift_batch"/>
  <Table sqltable="a_recurring_gift">
    // ...same custom-field treatment
  </Table>
  <Table sqltable="a_recurring_gift_detail">
    // ...17 custom fields
  </Table>
  <Table sqltable="a_motivation_group"/>
  <Table sqltable="a_motivation_detail"/>
  <Table sqltable="p_partner"
         name="DonorPartners"/>
  <Table sqltable="p_partner"
         name="RecipientPartners"/>
  // ...support tables
</DataSet>

// Generated at build time by
// TTypedDataSetGenerator into:
// GiftBatchTDS.Generated.cs (~thousands of LOC)
// GiftBatchTDSAccess.cs       (~hundreds of LOC)
// + per-table strongly-typed
//   row classes, DataTable
//   subclasses, and
//   SubmitChanges helpers

-- Existing physical schema, sourced
-- byte-faithful from db/petra.xml via
-- schema-decisions-002.json (cycle 23).
-- All 19 columns; column order matches
-- Petra source order. NO DDL CHANGES.

CREATE TABLE a_gift_batch (
    a_ledger_number_i          INTEGER      NOT NULL DEFAULT 0,
    a_batch_number_i           INTEGER      NOT NULL DEFAULT 0,
    a_batch_description_c      VARCHAR(40)  NOT NULL,
    s_modification_date_d      DATE         DEFAULT CURRENT_DATE,
    a_hash_total_n             NUMERIC(24,10) DEFAULT 0,
    a_batch_total_n            NUMERIC(24,10) DEFAULT 0,
    a_bank_account_code_c      VARCHAR(9)   NOT NULL,
    a_last_gift_number_i       INTEGER      DEFAULT 0,
    a_batch_status_c           VARCHAR(16)  DEFAULT 'Unposted',
        -- DEVIATION: source X(8) -> handoff 16;
        -- petra-self-contradiction (see callout
        -- above): 'Cancelled' is 9 chars but the
        -- <field> declares X(8). Widened so the
        -- constraint matches the documented enum.
    a_batch_period_i           INTEGER      NOT NULL DEFAULT 0,
    a_batch_year_i             INTEGER      NOT NULL,
    a_gl_effective_date_d      DATE         NOT NULL DEFAULT CURRENT_DATE,
    a_currency_code_c          VARCHAR(8)   NOT NULL,
    a_exchange_rate_to_base_n  NUMERIC(24,10) NOT NULL DEFAULT 0,
    a_bank_cost_centre_c       VARCHAR(12)  NOT NULL,
    a_gift_type_c              VARCHAR(8)   NOT NULL DEFAULT 'Gift',
    a_method_of_payment_code_c VARCHAR(8),
    PRIMARY KEY(a_ledger_number_i,
                a_batch_number_i),
    FOREIGN KEY(a_ledger_number_i)
        REFERENCES a_ledger(a_ledger_number_i),
    FOREIGN KEY(a_currency_code_c)
        REFERENCES a_currency(a_currency_code_c)
);

-- Existing indexes preserved as-is.
-- date_effective, period_effective.
-- One additive index from § 4.4:
CREATE INDEX ix_gift_batch_landing
    ON a_gift_batch(
        a_ledger_number_i,
        a_batch_status_c,
        a_gl_effective_date_d);
-- (supports unposted-batches landing
--  query and field-adjustment Posted-
--  only filter; pure additive change)

// Entities/AGiftBatch.cs

public sealed class AGiftBatch
{
    public int LedgerNumber { get; set; }
    public int BatchNumber { get; set; }
    public string BatchDescription { get; set; }
        = string.Empty;
    public BatchStatus BatchStatus { get; set; }
    public int BatchPeriod { get; set; }
    public int BatchYear { get; set; }
    public DateOnly GlEffectiveDate { get; set; }
    public string CurrencyCode { get; set; }
        = string.Empty;
    public decimal ExchangeRateToBase { get; set; }
    public decimal? BatchTotal { get; set; }
    public decimal? HashTotal { get; set; }
    public string BankAccountCode { get; set; }
        = string.Empty;
    public string BankCostCentre { get; set; }
        = string.Empty;
    public string GiftType { get; set; }
        = "Gift";
    public string? MethodOfPaymentCode { get; set; }
    public DateOnly? ModificationDate { get; set; }
    // (Petra audit on a_gift_batch is the
    //  single column s_modification_date_d;
    //  no s_created_by_c / s_modified_by_c on
    //  this table per Petra source.)

    // Navigation
    public ALedger Ledger { get; set; } = null!;
    public ICollection<AGift> Gifts
        { get; } = new List<AGift>();
}

// Fluent-API mapping
public sealed class AGiftBatchConfig
    : IEntityTypeConfiguration<AGiftBatch>
{
    public void Configure(
        EntityTypeBuilder<AGiftBatch> b)
    {
        // Map to the EXISTING physical table.
        // Hungarian column suffixes preserved.
        b.ToTable("a_gift_batch");
        b.HasKey(x => new
            { x.LedgerNumber, x.BatchNumber });
        b.Property(x => x.LedgerNumber)
            .HasColumnName("a_ledger_number_i");
        b.Property(x => x.BatchNumber)
            .HasColumnName("a_batch_number_i");
        b.Property(x => x.BatchDescription)
            .HasColumnName("a_batch_description_c")
            .HasMaxLength(40);
        b.Property(x => x.BatchStatus)
            .HasColumnName("a_batch_status_c")
            .HasConversion<string>()
            .HasMaxLength(16); // declared deviation
        b.Property(x => x.CurrencyCode)
            .HasColumnName("a_currency_code_c")
            .HasMaxLength(8);
        b.Property(x => x.BatchTotal)
            .HasColumnName("a_batch_total_n")
            .HasPrecision(24, 10);
        b.Property(x => x.ExchangeRateToBase)
            .HasColumnName("a_exchange_rate_to_base_n")
            .HasPrecision(24, 10);
        b.Property(x => x.BankAccountCode)
            .HasColumnName("a_bank_account_code_c")
            .HasMaxLength(9);
        b.Property(x => x.BankCostCentre)
            .HasColumnName("a_bank_cost_centre_c")
            .HasMaxLength(12);
        // ...remaining columns (period/year/etc.)
    }
}

10.5 Operational Tables (NEW)

The six operational tables exist to give the queued-worker pattern persistence outside the request thread, plus durable idempotency for the strangler-fig coexistence boundary. Five are owned by gift-receipting-service; the sixth, idempotency_keys, is owned by gift-processing-service. The interactive surfaces never write to the receipting tables and read them only for status display. They share an audit-column convention (created_at, updated_at, created_by, updated_by) per § 10.9.1.

erDiagram
  RENDER_JOB ||--o{ RENDERED_RECEIPT : "produces (annual-receipt jobs)"
  RENDER_JOB ||--o{ SEPA_EXPORT_FILE : "produces (sepa jobs)"
  BANK_IMPORT_UPLOAD ||--o{ BANK_IMPORT_LINE : "parses into"
  BANK_IMPORT_LINE }o..o| A_GIFT_DETAIL : "matches (composite-key FK fragment to legacy gift-domain row)"

  RENDER_JOB {
    uuid render_job_id PK
    varchar job_type "AnnualReceipt|Sepa|Ich"
    int ledger_number FK "to a_ledger"
    varchar status "Queued|Running|Completed|Failed|DeadLettered"
    int retry_count
    timestamptz requested_at
    timestamptz started_at
    timestamptz completed_at
    text failure_reason
    jsonb job_payload "type-specific parameters"
    varchar requested_by
  }

  RENDERED_RECEIPT {
    uuid receipt_id PK
    uuid render_job_id FK
    int ledger_number FK
    bigint donor_partner_key "logical FK to legacy p_partner"
    int tax_year
    date period_start
    date period_end
    varchar blob_uri "azure blob path"
    varchar sha256_hash
    bigint size_bytes
    timestamptz rendered_at
    timestamptz immutable_until
  }

  SEPA_EXPORT_FILE {
    uuid sepa_file_id PK
    uuid render_job_id FK
    int ledger_number FK
    date collection_date
    int mandate_count
    decimal total_amount "ledger currency"
    varchar currency_code FK "to a_currency"
    varchar blob_uri
    varchar sha256_hash
    timestamptz generated_at
  }

  BANK_IMPORT_UPLOAD {
    uuid upload_id PK
    int ledger_number FK
    varchar file_format "CAMT|MT940|CSV|ZIP"
    varchar status "Uploaded|Parsing|Parsed|MatchingComplete|Failed"
    varchar blob_uri "raw upload retained"
    varchar sha256_hash
    bigint size_bytes
    timestamptz uploaded_at
    varchar uploaded_by
    int line_count
    int matched_count
  }

  BANK_IMPORT_LINE {
    uuid line_id PK
    uuid upload_id FK
    int line_number
    date value_date
    varchar transaction_code "BR-GFT-007"
    decimal amount
    varchar currency_code FK
    varchar payer_iban
    varchar payer_name
    text statement_text
    varchar match_status "Unmatched|AutoMatched|UserMatched|Rejected"
    int matched_ledger_number "nullable; FK fragment 1/4"
    int matched_batch_number "nullable; 2/4"
    int matched_gift_transaction_number "nullable; 3/4"
    int matched_detail_number "nullable; 4/4"
    timestamptz matched_at
    varchar matched_by
  }

  IDEMPOTENCY_KEYS {
    varchar idempotency_key PK
    varchar request_method
    varchar request_path
    varchar request_body_hash
    int response_status_code
    jsonb response_body
    timestamptz first_seen_at
    timestamptz completed_at
    timestamptz expires_at
  }
    

Operational tables ER diagram (six tables). render_job is the queued-worker job-tracking table; rendered_receipt and sepa_export_file are the per-output provenance rows; bank_import_upload → bank_import_line form a parent-child pair for the bank-statement matching flow; idempotency_keys stands alone as the strangler-fig at-most-once token store. The dashed FK from bank_import_line to a_gift_detail is the only edge that crosses into the preserved gift-domain schema, and it is a four-column composite reference materialised at deploy time.

Below: the DDL and EF Core entity for render_job as the worked example. The other five operational tables follow the same shape (UUID PK, audit columns, NUMERIC for monetary, JSONB where the per-job-type payload genuinely is heterogeneous). Their full DDL is generated by Sage’s artifact-generation pipeline and ships in the migration artefacts bundle.

// In the legacy synchronous world,
// CreateAnnualGiftReceipts is a single
// 26-parameter [WebMethod] call that
// returns three out-parameters and
// writes the PDFs to a temporary
// filesystem path before streaming
// them back to the caller. There is
// NO database row representing the
// job's existence, NO retry record,
// NO dead-letter trace, NO durable
// audit. If the request times out,
// the partial work is lost and the
// caller has to start over.
//
// (See Section 8.3 for the legacy
// method signature.)
//
// The render_job table exists
// because the queued-worker pattern
// requires durable persistence of
// every job's lifecycle. There
// is nothing to migrate from
// legacy — this is a net-new
// operational entity.

-- Migration: 20260501_AddRenderJob.sql
CREATE TABLE render_job (
    render_job_id    UUID
        PRIMARY KEY
        DEFAULT gen_random_uuid(),
    job_type         VARCHAR(32)  NOT NULL
        CHECK(job_type IN
            ('AnnualReceipt',
             'Sepa',
             'Ich')),
    ledger_number    INTEGER      NOT NULL
        REFERENCES a_ledger(a_ledger_number_i),
    status           VARCHAR(20)  NOT NULL
        CHECK(status IN
            ('Queued', 'Running',
             'Completed', 'Failed',
             'DeadLettered')),
    retry_count      INTEGER      NOT NULL
        DEFAULT 0,
    requested_at     TIMESTAMPTZ  NOT NULL
        DEFAULT CURRENT_TIMESTAMP,
    started_at       TIMESTAMPTZ,
    completed_at     TIMESTAMPTZ,
    failure_reason   TEXT,
    job_payload      JSONB        NOT NULL,
    requested_by     VARCHAR(64)  NOT NULL,
    created_at       TIMESTAMPTZ  NOT NULL
        DEFAULT CURRENT_TIMESTAMP,
    created_by       VARCHAR(64)  NOT NULL,
    updated_at       TIMESTAMPTZ  NOT NULL
        DEFAULT CURRENT_TIMESTAMP,
    updated_by       VARCHAR(64)  NOT NULL
);

CREATE INDEX ix_render_job_pickup
    ON render_job(status, requested_at)
    WHERE status IN
        ('Queued', 'Running');

CREATE INDEX ix_render_job_history
    ON render_job(ledger_number,
                   requested_at DESC);

// Entities/RenderJob.cs

public sealed class RenderJob
{
    public Guid RenderJobId { get; set; }
        = Guid.NewGuid();
    public JobType JobType { get; set; }
    public int LedgerNumber { get; set; }
    public JobStatus Status { get; set; }
        = JobStatus.Queued;
    public int RetryCount { get; set; }
    public DateTimeOffset RequestedAt { get; set; }
    public DateTimeOffset? StartedAt { get; set; }
    public DateTimeOffset? CompletedAt { get; set; }
    public string? FailureReason { get; set; }
    public JsonDocument JobPayload { get; set; }
        = null!;
    public string RequestedBy { get; set; }
        = string.Empty;

    // Audit (universal rule, § 10.9.1)
    public DateTimeOffset CreatedAt { get; set; }
    public string CreatedBy { get; set; }
        = string.Empty;
    public DateTimeOffset UpdatedAt { get; set; }
    public string UpdatedBy { get; set; }
        = string.Empty;

    // Navigation
    public ICollection<RenderedReceipt> Receipts
        { get; } = new List<RenderedReceipt>();
    public ICollection<SepaExportFile> SepaFiles
        { get; } = new List<SepaExportFile>();
}

public sealed class RenderJobConfig
    : IEntityTypeConfiguration<RenderJob>
{
    public void Configure(
        EntityTypeBuilder<RenderJob> b)
    {
        b.ToTable("render_job");
        b.HasKey(j => j.RenderJobId);
        b.Property(j => j.JobType)
            .HasConversion<string>()
            .HasMaxLength(32);
        b.Property(j => j.Status)
            .HasConversion<string>()
            .HasMaxLength(20);
        b.Property(j => j.JobPayload)
            .HasColumnType("jsonb");
        b.HasIndex(j => new
            { j.Status, j.RequestedAt })
            .HasFilter("status IN ('Queued','Running')");
    }
}

10.6 ER Diagrams — Together

The two diagrams in § 10.1 (preserved gift-domain schema, eight tables plus four read-only-reference targets) and § 10.5 (operational tables, six entities) compose into a single picture of the data tier the slice produces. The seam between them is narrow: three FK families from operational tables into the preserved gift-domain / partner / ledger schema, and zero references in the reverse direction. The preserved schema has no awareness of the operational tables' existence.

Because the preserved schema is reproduced verbatim in § 10.1 and the operational tables in § 10.5, no third combined diagram is rendered — a single 18-table ER diagram would obscure the architectural point that the two halves are deliberately separate. Section 4.4's data-model figure carries the unified target view at the architecture level, with FK arrows summarised rather than enumerated; this Section 9 layout intentionally complements it by showing the per-half detail that Section 4 abstracts away.

10.7 Migration Mechanics

The slice's data-tier migration is the smallest of any modernisation pattern in the project: modify zero existing tables; add six operational tables.

Section 11 owns the full coexistence and cutover plan including the per-endpoint strangler-fig schedule, dual-traffic monitoring, and the GL-write reliability story (the one place where new services write to legacy — via federated REST to legacy MFinance, not directly to the database).

10.8 Petra-XML Code Generation Pipeline — Retired for the Slice

Section 10.4 covered the artefact-level retirement; this subsection covers what happens to the rest of the pipeline machinery for the gift slice's surface and what stays alive elsewhere.

The orchestrator must therefore know which tables are owned by EF Core (the six operational tables) and which are mapped-but-not-owned (the eight gift-domain tables, plus the four legacy-shared read-only-reference tables a_ledger, a_currency, a_account, p_partner). The distinction matters for migration-script generation: EF Core migrations should be authored only for the owned set; the mapped-but-not-owned set is configured as existing in the DbContext via Fluent API, and the generated migration should never propose DDL changes against them. A unit test in the build verifies dotnet ef migrations add CheckGiftDomainStable produces an empty migration — if it ever does not, the configuration has drifted and the build fails. Section 11 owns the multi-slice cutover plan.

10.9 Schema Migration Design Rules

These design rules govern every data-tier decision the artifact-generation workflow makes. They are split into universal rules (apply regardless of target database engine) and engine-specific rules (implementation details for PostgreSQL, the chosen and preserved engine for Petra). PostgreSQL is fixed for this engagement; the engine-specific table is included so this contract travels to a future Cosmos / DynamoDB target without re-deriving the universal rules.

10.9.1 Universal Rules (engine-agnostic)

10.9.2 Engine-Specific Rules — PostgreSQL (preserved)

Petra preserves PostgreSQL as the engine. The PostgreSQL column applies; the DynamoDB and Cosmos / MongoDB columns are reference-only, included so this Section 9 contract is portable to a hypothetical future engagement on a different engine without re-deriving the universal rules.

For the overall migration execution plan including phased cutover, the GL-write reliability story, and rollback procedures, see Section 11: Migration Strategy.

11. Migration Execution & Legacy/Modern Coexistence

Sections 4 and 9 define what the target architecture looks like and how the gift-domain schema is preserved end-to-end. This section defines how the transition happens — the operational mechanics of running OpenPetra's legacy .asmx server alongside the new ASP.NET Core 8 / Angular 18 services, progressively shifting traffic, and executing a low-risk cutover for the Finance — Gift Processing slice.

The section is organised in six layers: first, why classical strangler fig fits this system (and why SAROC and dual-write do not); second, the queued-worker EIP component view that anchors the receipting subsystem; third, the routing-rules-first cutover choreography; fourth, a worked example showing why ordering and idempotency matter for sequential gift batch numbering; fifth, the proof-of-concept plan (deferred to Phase A of execution); and sixth, operational considerations — DLQ behaviour, queue-depth alerts, consumer-lag SLOs, and rollback.

11.1 Why Classical Strangler Fig Fits Petra Gift Processing

Sage’s coexistence pattern library applies a three-question decision tree to pick the coexistence pattern:

Does the source have a request-routing surface (LB, API gateway, reverse proxy)?
├── No  →  SAROC
└── Yes →  Are writes idempotent and is divergence acceptable for short windows?
           ├── No  →  Classical strangler fig (route reads first, then writes)
           └── Yes →  Symmetric dual-write
    

Question 1 — routing surface? Yes. Petra's Finance — Gift Processing slice presents an HTTP boundary on every interaction: the JavaScript / jQuery thin client calls server-side WebMethods on ASP.NET .asmx SOAP endpoints over HTTP. The Mono FastCGI process serves these endpoints behind a reverse proxy. Every legacy interaction crosses an HTTP boundary — there is no direct database thick-client surface, no green-screen TUI, no batch-only file drop. This is the exact opposite of ACAS: where ACAS users sit at ACCEPT / DISPLAY COBOL screens with no routable surface, Petra users sit in a browser making JSON-over-SOAP RPCs. SAROC is therefore inapplicable — we have a routing surface, so passive CDC observation is not the right primitive.

Question 2 — writes idempotent? No. The load-bearing write in this slice is gift batch posting. Per BR-GFT-001 (Sequential Gift Batch Numbering), every batch creation runs NewRow.BatchNumber = ++ALedgerTbl[0].LastGiftBatchNumber — an atomic increment of the ledger's batch counter inside a serialisable transaction. Posting the batch then writes journal rows to a_transaction / a_journal with auto-generated journal numbers, and updates motivation YTD / LTD running totals. None of these writes are naturally idempotent. Replaying a posted-batch event without an idempotency token would: (a) consume another batch number from the ledger counter (gap in the sequential invariant), (b) double-post journal rows (corrupting the GL), and (c) double-add to motivation YTD totals (inflating treasurer dashboards and Gift Aid claim totals). Symmetric dual-write is therefore inapplicable — we do not have the idempotency property the pattern requires.

Decision: Classical strangler fig — route reads first, then writes. This is the only branch of the decision tree consistent with both characteristics of the system. Reads (GET /api/Finance/Gift/…) are naturally idempotent and can be forked at the gateway with parity verification. Writes (POST /Finance/Gift/PostBatch) get the gateway-issued idempotency-token treatment so a single client retry cannot double-post.

11.2 EIP Component View — The Receipting Queued Worker

Classical strangler fig itself is a routing pattern (Content-Based Router at the gateway) and does not have a Hohpe & Woolf EIP message-queue diagram of record. However, the modern target architecture does include a queued-worker subsystem inside the gift slice: gift-processing-service submits annual-receipt render jobs to an Azure Service Bus queue (receipt-batch), and gift-receipting-service consumes them, renders PDFs to Blob Storage, and updates the rendered_receipt provenance table.

Figure 11.1 renders that subsystem in the canonical EIP notation. The "legacy" side is the legacy .asmx annual-receipt endpoint that today renders synchronously on the request thread; the "modern" side is the new two-service shape with Service Bus between them. The Channel Adapter here is not CDC-style passive observation (we are not on the SAROC branch); it is the gift-processing-service's outbound queue-publishing client, which serialises the render request and hands it to the durable channel.

11.3 Cutover Choreography

The cutover is a four-phase sequence of routing-rule changes at Azure API Management. The legacy .asmx endpoints stay live throughout Phases A, B, and C; only Phase D decommissions them. Routing changes are policy-file edits, deployable as code, reversible in seconds. This is the key affordance of classical strangler fig — the cutover is configuration, not a database migration.

Sizing context: the Finance — Gift Processing slice is approximately 12,000 LOC of server-side .asmx code (per the candidate-selection handoff — Gift.Adjustment.cs 742, Gift.Batch.cs 200, Gift.Exporting.SEPA.cs 369, Gift.Exporting.cs 870, Gift.Importing.cs 1,998, plus matching JS / SQL) plus the matching jQuery client. A small team (2–3 engineers + 1 QA + part-time PO) should plan 6–8 weeks per phase, with Phase A possibly running longer if parity-diff investigations surface unexpected legacy quirks.

Total elapsed wall time: 20–28 weeks (5–7 months). The Finance — Gift Processing slice is the second-largest module in OpenPetra; smaller modules following the same playbook should compress proportionally.

Federation traffic during coexistence. Both during and after Phase C, the modern gift-processing-service calls back to legacy MFinance via federated REST for two reasons: (a) read-only access to a_ledger, a_account, a_cost_centre, a_accounting_period; and (b) GL posting writes to a_transaction / a_journal. The GL-write boundary is the one place where the new service writes into the legacy zone; per the target-architecture handoff caveat, this is a saga-pattern candidate but the saga boundary is owned by service-architecture (Appendix B), not by this section.

11.4 Why Ordering and Idempotency Matter for Gift Posting

The load-bearing rule for this discussion is BR-GFT-001 — Sequential Gift Batch Numbering (confidence 0.95). The legacy code is one line at csharp/ICT/Petra/Server/lib/MFinance/Gift/Gift.Batch.cs:111:

NewRow.BatchNumber = ++ALedgerTbl[0].LastGiftBatchNumber;
    

It runs inside a serialisable transaction. Concurrent batch creations on the same ledger serialise via the row lock on a_ledger. The result is a strictly monotonic batch counter per ledger — no gaps, no duplicates — which downstream auditors, treasurers, and tax authorities rely on.

Worked example. Suppose treasurer Sarah submits a gift batch at 14:32 on a Monday in ledger 43 (the UK ledger). The batch contains a single £500 gift from donor partner key 10001234, allocated 60/40 across two motivation details:

• Motivation MED-EQUIPT — £300 (general medical-equipment fund)
• Motivation BEDS-2026 — £200 (specific 2026 hospital-beds appeal)

The batch is created with BatchNumber = 5,847 (the next value after the ledger counter's prior 5,846). When Sarah hits "Post", three things happen atomically:

1. Counter increment: a_ledger.LastGiftBatchNumber goes 5,846 → 5,847.
2. Journal write: two rows in a_journal — debit cash £500, credit MED-EQUIPT £300, credit BEDS-2026 £200 (aggregated from the gift-detail rows per the legacy posting rules).
3. Motivation totals update: MED-EQUIPT.YTD += 300 (now £14,300 say); BEDS-2026.YTD += 200 (now £47,200); the LTD running totals on each motivation also tick up by the same amounts.

What breaks if a write replays without idempotency. The Phase-C cutover sits behind APIM. Suppose Sarah's browser hits a transient network blip, retries the POST /Finance/Gift/PostBatch, and APIM forwards both requests to gift-processing-service — the second one arriving 800ms after the first.

The mechanism in this design. APIM is configured to issue a UUID X-Idempotency-Key header on every POST /Finance/Gift/PostBatch that it forwards to gift-processing-service. The service's first action on every write request is to SELECT from a small idempotency_keys table (key, response body, response status, created-at). On hit, it returns the cached response without touching the gift-domain tables. On miss, it begins the EF Core serialisable transaction; only after the transaction commits is the row written to idempotency_keys. A nightly job purges keys older than 24 hours.

Why we picked idempotency tokens over natural keys. Operator-keyed gift batches do not have a stable composite natural key — the legacy system generates the batch number on submission, and the operator-supplied fields (description, effective date, currency) are not collectively unique. This rules out the natural-key approach used in some patterns (e.g., bank reference + amount + value-date for a payment instruction). Idempotency tokens are the safer choice for write-with-side-effects.

11.5 Proof-of-Concept Plan

No PoC has been built yet. Per the agent definition's "no fabricated PoC numbers" rule, this section identifies what the PoC will validate and where in the cutover it lives.

The PoC is Phase A of the execution plan — shadow-mode reads at a 5% gateway split. The PoC has its own validation criteria, distinct from the production-cutover go/no-go gates:

Quantitative numbers will be filled in after Phase A runs. This section will be re-issued via the standard refinement protocol (Section 11 refinement is in scope; the section's structure stays; the PoC subsection swaps "to be validated" for measured numbers).

11.6 Operational Considerations

Once cutover is underway, four operational concerns dominate: dead-letter-queue handling, queue-depth alerting, consumer-lag SLOs, and rollback. The numbers below are calibrated to the Finance — Gift Processing workload shape: low-and-steady interactive traffic plus an annual-receipt surge that can produce 10,000+ render messages in a single hour when the year-end button is pressed.

Dead-letter queue (DLQ) behaviour

Azure Service Bus is configured for 5 delivery attempts per message (the platform default for the Standard tier) before automatic dead-lettering. Reasons for DLQ:

• Poison message: the receipt template references a partner key that no longer resolves (donor merged or deleted). The renderer raises UnknownPartnerException on every retry.
• Transient infrastructure failure exhaustion: Blob Storage 5xx for > 5 retry windows.
• Bug in renderer: e.g., a tax-deductibility-percentage edge case that crashes the PDF generator.

DLQ messages are surfaced via a gift-receipting-service admin endpoint (GET /admin/dlq/receipt-batch) and a corresponding Angular admin screen. Operators can inspect, requeue (after fixing root cause), or discard. DLQ is not auto-drained — a human must classify each message.

Queue-depth alerts

The receipt-render workload is bursty. Queue-depth alerting is calibrated to the year-end surge:

• Warn at 1,000 messages. Normal interactive backlog should never exceed a few dozen messages; 1,000 means a batch run is in flight or something is wrong.
• Page at 5,000 messages. Year-end annual-receipt batches are intentional and well-known; the on-call engineer is paged so they can confirm "annual run in progress, expected" or escalate if not.
• Hard ceiling: 50,000 messages. Service Bus Standard supports far more, but Petra's typical worst case is 10,000 + safety margin. Crossing 50,000 indicates a runaway producer or stuck consumer.

Consumer-lag SLO

For receipt rendering: p95 receipt rendered within 4 hours of POST under normal load (the year-end-surge envelope). Degraded-mode SLO: 24 hours — i.e., within the same business day the operator initiated the run. SLO violation triggers PagerDuty.

For SEPA exports and ICH exports (the other two queues, defined in target architecture but out of this section's narrative scope): minutes-to-hours SLOs apply, calibrated separately during their respective slices' execution. They share the same DLQ + alerting framework.

Cutover rollback

Rollback for any phase is a single APIM policy revert. The policy artifact is version-controlled; revert is a Git revert + redeploy, ~30 seconds at the gateway. There are two rollback nuances:

1. Idempotency-key cleanup after Phase C rollback. If write traffic was routed to modern for any non-trivial window before rollback, the idempotency_keys table holds keys that the legacy system has no awareness of. After rollback, those keys must be cleared (a single DELETE) before reattempt — otherwise re-issued tokens may collide with stale entries and the second cutover attempt would silently no-op some writes. This is documented in the rollback runbook.
2. In-flight render jobs survive rollback. Service Bus messages enqueued during Phase C are durable; if Phase C is rolled back, the messages already in receipt-batch continue to render — the receipts produced are valid for the gifts that did commit before rollback. A reconciliation run is needed to confirm render_job rows align with a_gift_batch rows that committed pre-rollback.

Both nuances are call-outs to the operations team and do not change the cutover plan.

The narrative above is the authoritative specification of the coexistence design. Bridge code generation, routing-rule deployment, and parity verification harnesses are produced by Sage's migration-artifacts workflow against this specification.

12. How Sage Enabled This Analysis

This closing section steps back from the technical content of Sections 1–11 and explains how the analysis itself was produced. Three approaches are compared throughout: (1) With Sage, where the planning analysis has deep insight into all subsystems via Sage's Language-Agnostic Deep Scan, (2) Without Sage (generic AI tooling) — AI assistants analyzing code with only Read / Grep / Glob and no pre-computed codebase intelligence, and (3) Manual review by an architect or migration consultant. Every comparison in this section includes all three, so the value of Sage is visible relative to both AI-without-Sage and traditional human effort.

Section 12 sits at the end of the report on purpose. The earlier sections argued the migration on its merits — the target architecture in Section 4, the platform unlocks in Section 5, the technical-debt classification in Section 6, the UI and code examples in Sections 7–8, the 16 behavioral rules in Section 9, the data-mapping detail in Section 9, and the coexistence design in Section 11. By the time a reader reaches this section, the analysis has already paid off; the question is no longer "is this credible?" but "how did anyone produce this depth of analysis on a 572,757-line .NET codebase in hours rather than weeks?" The answer is the rest of this section.

12.1 Analysis at a Glance

Petra (OpenPetra) comprises 572,757 lines of code across 27 business-function subsystems and 32 technology subjects — a layered, n-tier .NET Framework 4.7 application with a jQuery + Bootstrap web client, ASP.NET Web Services (.asmx) over Mono FastCGI, an XML-driven code-generated DAL, and a multi-database abstraction over PostgreSQL, MySQL, and SQLite. Sage's Language-Agnostic Deep Scan transformed this heterogeneous C# / JavaScript / SQL surface into structured, queryable intelligence — enabling the planning workflow to evaluate all 27 subsystems, select Finance — Gift Processing as the migration pilot (a five-screen end-to-end donor money-flow slice), design a two-service Azure App Service target, audit 37 dependencies across two contributing manifests, classify 7 architectural concerns + 12 forward-unlock platform constraints against the target, and extract 16 behavioral rules at 0.818 mean confidence — all from pre-computed analysis rather than file-by-file reading.

12.2 Depth of Understanding

Beyond speed, the three approaches differ fundamentally in the depth and completeness of understanding they produce. This subsection compares what each approach actually achieves for six critical analysis capabilities.

12.2.1 Architecture Mapping

12.2.2 Subsystem Classification

12.2.3 Integration Analysis

12.2.4 Code Quality Assessment

12.2.5 Migration Complexity Estimation

12.2.6 Behavioral-Rule Catalog Construction

12.3 Why Sage Language-Agnostic Deep Scan Matters

Could a generic AI assistant alone read a source file and determine legacy behavior? Sure — if it knew which file to read. But the fundamental problem is: you don't know what you don't know. Even if the assistant is pointed at the right file and correctly understands the logic, it still cannot know whether that file is the only part of the overall system that touches that capability.

Consider the most stakeholder-impactful discovery from this analysis: the .NET Framework 4.7 NuGet ceiling cascade. Petra's runtime ceiling is not a single fact about a single file — it manifests across multiple manifests, multiple packages, and multiple architectural layers. The inline comment in csharp/ThirdParty/packages.config documents the ceiling explicitly: "we cannot update to 5.x because that only supports .net 5." That single pin propagates through Npgsql 4.1.10 (the database driver, EOL major version), NUnit 3.13 (the test runner, outdated), and SharpZipLib 1.3 (a compression library, EOL major version). It also forces six BCL polyfill packages (System.Buffers, System.Memory, System.ValueTuple, System.Runtime.CompilerServices.Unsafe, System.Threading.Tasks.Extensions, System.Runtime) to remain in the manifest because the runtime is too old to provide their functionality natively. On the client side, the same generation of dependency drift forces axios 0.21.x (with two known CVEs), Bootstrap 4 (EOL January 2023), browserify (community-deprecated), and popper.js (renamed). That is 14 packages across 2 manifests and 3 architectural layers — all blocked by the same single ceiling.

A tool analyzing one file at a time cannot see this full picture, and worse, it does not know to look for it. If a generic AI assistant reads packages.config and notices Npgsql 4.x, it correctly identifies an outdated database driver. But without Sage's pre-computed lifecycle classification, it cannot connect that pin to the manifest comment, to the BCL-polyfill cluster, or to the client-side build-chain decay. It might recommend upgrading Npgsql while leaving the runtime ceiling untouched — a migration that looks correct in isolation but cannot actually be performed (Npgsql 5.x requires .NET 5+; the upgrade fails before it starts).

The advantage of Sage's Language-Agnostic Deep Scan is that the planning agent instantly has access to the full gamut of business flows, behavioral rules, architecture layers, and integration points — at both business and technology levels — across 100% of the codebase. It does not start by reading files; it starts by knowing what exists. It retrieves actual source code if and only if needed to verify an assertion the Sage analysis has already made — for example, opening packages.config at specific line ranges to confirm the manifest-comment pin rationale, after Sage already identified the dependency lifecycle status. This inverts the workflow from "read code and hope you find what matters" to "know what matters and verify it against the code."

12.4 Specific Examples from This Analysis

12.4.1 Subsystem Selection Across 27 Subsystems

Sage's candidate-selection step evaluated all 27 business-function subsystems and produced a quantified Risk / Feasibility / Strategic Value score for each. (Note: this analysis used single-pass scoring; Sage’s 3-pass consensus configuration is available for production engagements — the Sage data underlying the scoring is identical regardless of pass count.) Sage’s cached get_subject_profile data, weighed under a framework that includes an interactive-UI-surface column and separates compliance-posture risk from live-regulator-integration risk, produced Finance — Gift Processing as the winner without a single additional Sage call.

12.4.2 The .NET Framework 4.7 NuGet Ceiling Cascade

The 37-row dependency audit produced a counterintuitive insight: the apparent 37 individual decisions collapse into one strategic decision. Move off .NET Framework 4.7 and onto .NET 8, and 14 of the 37 entries dissolve automatically — the BCL polyfills are absorbed by the modern BCL, the comment-pinned packages can finally upgrade, and the client-side rebuild on Angular 18 retires the entire browserify / Bootstrap 4 / axios chain. This insight required reading the manifest comments — not just listing the packages.

12.4.3 The .asmx Wire-Format Discovery: Avoiding the "SOAP-to-REST" Misframing

Petra's .asmx services look like SOAP — the file extension, the [WebMethod] attributes, the WSDL endpoint. The naive migration framing would be "migrate from SOAP to REST," with all the WSDL-parsing, contract-first, schema-translation work that implies. Sage's integration insight identified the actual wire format: JSON-over-HTTP RPC, dispatched via THttpConnector.CallWebConnector by method name. The SOAP envelope is cosmetic. This single discovery reframed the target-architecture decision from "SOAP-to-REST" to "RPC-to-Minimal-API" — a materially different (and easier) migration path.

12.4.4 Behavioral-Rule Extraction Across Sibling Subjects

The behavioral-rules phase extracted 16 distinct rules at 0.818 mean confidence for the Finance — Gift Processing slice. The methodology choice that mattered: get_entities_by_subject(Finance — Gift Processing) alone returned only 7 rules. Eight targeted search_entities name-substring sweeps (gift, tax, receipt, sepa, posted, motivation, batch) raised the candidate pool to 24 raw entities, deduplicated to 16 distinct rules. Sage's auto-merge of rules across sibling subjects with 0.92–0.94 convergence (where the same rule was classified under both Finance — Gift Processing and Donations Processing) was a load-bearing capability — without it, the dedup pass would have produced a double-counted catalog.

12.4.5 Architectural-Seam Validation via User Flows

The two-service split — gift-processing-service for sub-second interactive operations and gift-receipting-service for queued workers — is not just an architectural intuition. Sage's bounded-context analysis proposed a single donation-management-service microservice; Sage’s target-architecture analysis split it into two on workload-shape grounds (latency budget, scaling driver, failure mode); the use-case-discovery analysis then validated the split by observing that both primary user flows cross the seam in opposite directions. Use Case 1 (Process a Gift Batch End-to-End) flows from the bank-import worker in gift-receipting-service through Service Bus to interactive batch operations in gift-processing-service; Use Case 2 (Generate the Annual Donor Receipt Run) flows from the form submit in gift-processing-service through Service Bus to receipt-render workers in gift-receipting-service. The seam is justified by user-visible workload-shape evidence, not just stylistic preference — and the validation chain depends on having the integration data, the bounded-context data, and the workflow data all available concurrently.

12.4.6 Platform-Constraint Curation: From 44 Surfaces to 12 Forward-Unlock Entries

The platform affinity analysis (Section 5) curated the tech-debt catalog (44 surfaces — 7 architectural concerns + 37 dependency entries) into 12 forward-unlock entries categorized as Capacity / Processing / UI / Data Type Constraints. The curation decision distribution was 9 ELIMINATE / 3 HYBRID / 0 PRESERVE — a stakeholder-readable answer to the question "what does this migration actually unlock?" Two of those entries (5.1.2 SharpZipLib + PDFsharp; 5.2.1 synchronous-pipeline-for-batch-workloads) reflect the fact that the Gift Processing slice covers a meaningful share of the project surface.

12.5 The Cumulative Advantage

Each step of this analysis built on the intelligence gathered by earlier steps — a cumulative advantage that compounds with project complexity. Sage's project-intelligence step profiled all 27 subsystems and surfaced 34 bounded contexts; the candidate-selection step used those profiles to score and rank every subsystem (and re-scored without re-fetching when framework axes were refined); the target-architecture step used the selected slice's entity inventory (TGiftTransactionWebConnector, GiftBatchTDS, the five interactive screens, the gift-domain table set) to design the data model and migration shape; the tech-debt analysis step used the architectural-insight catalog plus the dependency audit to produce the severity-ranked debt scorecard; the platform-affinity analysis curated the debt catalog into the forward-unlock constraint summary; the behavioral-rules step extracted 16 rules from sibling subjects with 0.818 mean confidence; the use-case-discovery step validated the architectural seam against user flows; and the technical-examples steps (Sections 7, 8, and 10) consumed every prior layer to render UI mockups, code translations, and data-mapping decisions with quantitative backing rather than narrative assertion.

This chain of dependent analyses was possible because Sage's Language-Agnostic Deep Scan provides a stable, comprehensive, queryable foundation that every step can build upon. Without it, each step would need to start from scratch — re-reading files, re-discovering patterns, re-building context — with no guarantee of consistency between steps. The fact that the architectural-insight result is stable across multiple tech-debt-analysis passes (the same 0.85 confidence, the same 7-concern catalog, the same 37-row dependency audit) is concrete evidence of that foundation: the same query produces the same answer when re-issued, which lets each downstream step trust its inputs without re-validation. Re-scoring all 27 subsystems with a refined framework required zero additional Sage calls because the cached get_subject_profile data was still authoritative.

12.6 What This Means for Your Migration

The depth and breadth of this analysis — 27 subsystems evaluated, 34 bounded contexts identified, 151 integration points mapped, 37 dependencies audited, 7 architectural concerns classified against the target architecture, 12 forward-unlock platform constraints curated, and 16 behavioral rules extracted at 0.818 mean confidence — would be impractical to produce manually for a 572,757-line .NET / jQuery codebase. Even with general-purpose AI code-analysis tooling, the absence of pre-computed codebase intelligence would reduce coverage from 100% to approximately 5–15%, with corresponding gaps in integration mapping (the SOAP-vs-JSON-RPC wire-format distinction would likely be missed), constraint discovery (the .NET Framework 4.7 ceiling cascade would surface as 14 isolated package decisions rather than one strategic one), behavioral-rule completeness (rules whose code lives in adjacent files would be missed entirely), and architectural-debt classification.

Sage's Language-Agnostic Deep Scan does not replace human judgment — it replaces the weeks of manual code reading required to inform human judgment. Every decision in this report — from selecting Finance — Gift Processing as the pilot slice, to choosing a two-service Azure App Service target with Service Bus between them, to preserving the entire gift-domain schema end-to-end, to enumerating 16 behavioral rules with golden-master-test flags on the two load-bearing ones — is backed by quantified evidence from the full codebase, not sampled approximations.

Ready to see what Sage can discover in your codebase? Visit sage-tech.ai to learn about pilot programs and schedule a Sage Language-Agnostic Deep Scan for your legacy modernization project.

← Back to Table of Contents

Appendix B: Service Architecture Decision Process

This appendix documents how the Finance — Gift Processing slice was decomposed into modernized services. Section 4.5 stated the result — two services, gift-processing-service and gift-receipting-service — without showing the work. This appendix shows the work: the workload-shape evidence that drove the decision, the alternatives considered, the seam chosen for the boundary, the cross-service communication pattern, and the federated-read posture against the legacy zone.

The headline finding is that the slice contains two genuinely different workload shapes — synchronous interactive request-response on one side, asynchronous queued-worker batch processing on the other — and that collapsing them into a single service trades away the architectural property that most justifies the modernization (independent scaling of receipt rendering against gift entry). The queued-worker boundary is the natural seam, and the posted-batch immutability invariant (BR-GFT-005) is what makes the seam safe.

B.1 Why this slice has TWO services, not one

The Gift Processing surface, viewed as code, looks deceptively uniform — one bounded context (DonationManagement), one schema family (the a_gift_* and a_recurring_gift_* tables), one set of business rules. But viewed as workload, it splits cleanly into two shapes:

Two shapes in one process means one of two outcomes, both bad: either the receipt-rendering run starves interactive requests during the January annual-receipt cycle (the legacy system's existing pain — a five-minute receipt batch monopolises server threads and the donor-entry screens go slow), or the App Service plan is sized for the burst and sits under-utilised the rest of the year. The two-service split lets each side scale on its own driver, which is the architectural property that makes the queued-worker pattern worth introducing in the first place.

B.2 Service granularity decision matrix

Three options were evaluated against the same four criteria used elsewhere in this report — Operational Complexity (20%), Business Alignment (30%), Technical Soundness (30%), and Change Velocity (20%) — with a 7.0 minimum weighted score for acceptance.

Option 2 wins decisively on Technical Soundness and Business Alignment — the two highest-weight criteria — while paying only a modest Operational Complexity premium relative to Option 1. Option 3 clears the 7.0 floor but does not justify its additional complexity at this slice's scale. The decision is not close.

B.3 Service boundaries — what each service owns

The two services divide responsibility along the synchronous / asynchronous workload seam. Within that division, table ownership is explicit: each net-new operational table has a single writer; the preserved gift-domain tables are written by one service and read by the other.

gift-processing-service

gift-receipting-service

Table ownership summary

B.4 The queued-worker boundary as the natural seam

Choosing to split somewhere is not enough — the boundary has to be at a seam where the data doesn't fight back. The queued-worker boundary is that seam, and the reason it is safe is BR-GFT-005 (posted-batch immutability).

BR-GFT-005 says: once a gift batch transitions to batch_status = ‘Posted’, no field on its rows or its children may change. Adjustments are modelled as new gift entries that reference the posted batch, never as edits-in-place. The legacy system has enforced this rule for fifteen-plus years; finance staff and audit procedures rely on it; the resolved patterns table (Section 4) elevates it from an implicit convention into a typed domain rule (BatchAlreadyPostedException).

That invariant is what makes the seam work. Receipting reads only from posted batches. A posted batch cannot change. Therefore the receipting service cannot suffer a read-your-own-writes problem against the gift-processing service: by the time receipting sees a batch, the gift-processing side has already declared the batch closed and the rows immutable. There is no concurrent-modification window to defend against; no read-after-write consistency contract to negotiate; no version-vector reconciliation; no “eventually” in the eventual consistency story for the data receipting actually depends on.

Compare this to alternative boundaries that were implicitly considered and rejected:

The queued-worker seam is the only boundary that aligns workload shape, data ownership, and an existing immutability invariant simultaneously. Take any one of those three away and the case for splitting weakens; with all three, the case is overdetermined.

B.5 Cross-service communication patterns

With two services, three categories of communication exist: gift-processing publishing work to gift-receipting, both services reading legacy data, and both services touching the shared gift-domain database. The first is asynchronous over Service Bus; the second is synchronous HTTP RPC; the third is direct database access governed by the table-ownership rules above.

B.6 Federated reads to legacy subsystems

Both new services depend on data that lives in the legacy zone during the strangler-fig coexistence window. Three legacy subsystems are touched: MPartner (donor identity and addresses), MFinance (ledger / period / account / cost-centre, plus GL posting), and the partner-class lookups that drive motivation defaulting on gift detail lines. None of these are migrated as part of this wave; all three remain authoritative on the legacy side.

The federation client interfaces (IPartnerLookupClient, IFinanceLedgerClient) are constructed via HttpClientFactory with Polly policies for retry, circuit-breaker, and timeout. Authentication across the boundary uses the legacy TOpenPetraOrgSessionManager session token during the coexistence window, bridged from the new services' Entra ID bearer token by API Management policy. When the legacy MPartner / MFinance subsystems migrate in subsequent waves, the federation client interfaces remain in place and their implementations are swapped from HTTP RPC to direct EF Core access — the calling code in both gift services does not change.

B.7 Independent scaling characteristics

The two services scale on different signals at different rhythms, which is the operational payoff of the split. Each service has its own App Service plan with its own autoscale rules, and the rules do not interfere.

On a January 15 annual-receipt run, gift-receipting-service may scale from 1 to 4 instances and back over the course of a few hours while gift-processing-service sits at its normal 2-instance daytime baseline. Under the single-service shape (Option 1), the same compute would be shared and the autoscale signal would be ambiguous: is CPU high because users are entering gifts, or because the receipt run is rendering PDFs? The two-service shape removes the ambiguity and lets each side scale honestly on the signal that actually drives its load.

B.8 Service-architecture decision summary

The Finance — Gift Processing slice is decomposed into two services because the workload has two genuinely different shapes — synchronous interactive on one side, asynchronous queued-worker on the other — and collapsing them into a single service would trade away the architectural property that most justifies the modernization (independent scaling of receipt rendering against gift entry). The queued-worker boundary is the natural seam, and the posted-batch immutability invariant (BR-GFT-005) is what makes the seam safe: receipting reads only from posted batches, posted batches do not change, so there is no read-your-own-writes problem to defend against. Cross-service communication is asynchronous over Azure Service Bus for the work itself and synchronous HTTP RPC against the legacy zone for federated reads of partner and ledger reference data; there is no synchronous RPC between the two new services in v1. This is the slice's load-bearing structural decision — every other architectural choice in this report (the Service Bus queues, the worker scaling envelope, the operational tables on the receipting side, the federation client interfaces) follows from it.

Appendix C: Deployment and Infrastructure

This appendix walks through the deployable Azure infrastructure for the Finance — Gift Processing slice of Petra. The artifact tree under infrastructure/bicep/ provisions an Azure App Service plan, a containerised .NET 8 site for gift-processing-service, a PostgreSQL Flexible Server, a Service Bus namespace with three queues, an Azure Container Registry, a Key Vault, an Application Insights component backed by a Log Analytics workspace, and the role assignments that wire the App Service's managed identity to the registry, the Service Bus, and the vault. Every parameter that varies between a demo posture and a production posture is exposed on main.bicep — the production shift is a parameter override, not a template rewrite.

C.1 Deployment topology

A single subscription-scoped Bicep deployment creates one resource group (default petra-gift-002-rg in westeurope) and provisions nine Azure resources inside it. The App Service runs the Gift Processing container pulled from the registry; the App Service's system-assigned managed identity is the only principal used at runtime — no shared keys, no admin credentials. Connection strings live in Key Vault and are surfaced to the application as appSettings Key Vault references.

The diagram below shows how those resources fit together. The App Service is the only inbound endpoint; everything else is reached via the App Service's managed identity over Azure-internal networking (or, in the demo posture, the public Postgres and Service Bus endpoints behind RBAC).