Concho Modernization Stakeholder Review

Section Takeaways

1. Introduction

1.1 About This Document

This document is a modernization stakeholder review for the Finance — Gift Processing subsystem of OpenPetra (project key petra), an open-source administrative ERP for non-profit organizations. It documents the path from OpenPetra's legacy n-tier .NET Framework 4.7 implementation — ASP.NET Web Services (.asmx / SOAP), code-generated data access driven by an XML schema definition, and a JavaScript/jQuery web client — to a modern .NET 10 + Angular 20 stack targeted at Azure App Service, with PostgreSQL as the primary data store.

The analysis was produced by a multi-agent modernization workflow that queries the Concho Context Graph for codebase intelligence at every phase — architecture, entities, business rules, integration patterns, technical debt — and then composes a target architecture, code-translation examples, data-mapping strategy, and a legacy/modern coexistence plan grounded in that evidence. Every claim in this report traces back to a Concho MCP query, an artifact identifier, or a generated handoff file in run 004's workspace.

1.2 Candidate Selection Process

OpenPetra spans 27 documented business function subjects covering CRM, financial management, gift processing, conference administration, personnel, sponsorship, and reporting. Picking the right modernization slice is itself an architectural decision: too narrow and the demo is unconvincing; too broad and the strangler-fig boundary becomes ill-defined. Section 2 (Modernization Scope) and Appendix A (Multi-Agent Subsystem Selection) document a three-run consensus selection in which independent agent runs each scored every documented subsystem on revenue impact, behavioural-rule density, coupling, and tractability, then voted. Finance — Gift Processing emerged as the consensus pick: it is OpenPetra's revenue-generating core, has the densest catalog of formalizable business rules, and has clean integration seams to General Ledger and Partner Management that make a strangler-fig boundary viable.

1.3 Report Contents

• Executive Summary — one-page framing for non-technical stakeholders.
• Section 1 — Introduction (this section).
• Section 2 — Modernization Scope — subsystem boundary, in-scope/out-of-scope, target stack.
• Section 3 — Legacy System Analysis — Concho-vended architecture, entities, integrations.
• Section 4 — Target Architecture — .NET 10 services on Azure App Service.
• Section 5 — Platform Affinity Analysis — how each legacy element maps onto the target stack.
• Section 6 — Technical Debt Analysis — what carries forward, what gets retired.
• Section 7 — UI/UX Transformation — jQuery forms to Angular 20 components.
• Section 8 — Code Translation — concrete C# legacy-to-modern examples.
• Section 9 — Business Rules Analysis — behavioural rules in Given-When-Then form.
• Section 10 — Data Mapping Strategy — schema translation and slice-boundary FK policy.
• Section 11 — Modernization Execution & Legacy/Modern Coexistence — strangler-fig sequencing.
• Section 12 — How Concho Enabled This Analysis — the Concho capability story.
• Appendix A — Multi-Agent Subsystem Selection; Appendix B — Service Architecture; Appendix C — Deployment.

1.4 What This Report Does NOT Include

To keep the stakeholder review focused on architectural and behavioural decisions, the following are deliberately out of scope for this document:

• Cost estimates. No Azure consumption forecasts, licensing models, or labour-day pricing — those depend on tenancy decisions and SLAs that have not yet been negotiated.
• Timelines and project plans. No Gantt charts, sprint plans, or release dates — the report defines what needs to happen and in what order, not when.
• Deployment plans for the existing OpenPetra installations. Migration runbooks, cutover scripts, and data-extraction tooling for live customer instances are downstream of architectural alignment.
• Organizational change management. Training plans, role redefinitions, and operational hand-offs are owned by the customer and depend on staffing.

1.5 About OpenPetra (Petra)

OpenPetra is a free, open-source administrative system that helps non-profit organizations manage donor contacts, gift processing, accounting, sponsorship programs, conference logistics, publications, and tax-compliant receipting. It was conceived as an ERP for mission organizations and is notable for its multi-currency, multi-country tax compliance features and its International Clearing House mechanism that minimizes currency-exchange charges between sister organizations. The codebase is built around an unusual but highly disciplined pattern: a single master XML schema (db/petra.xml, 24,924 lines) drives code generation of typed datasets, ORM layers, and validation classes across the entire system.

1.6 Stakeholder Reading Guide

2. Modernization Scope

This report leverages Concho's deep insight into all 27 subsystems in Petra (OpenPetra). A variety of criteria was applied against each one in order to find the right balance between technical feasibility, business value, and migration risk in order to select a candidate subsystem for this first migration project.

Three independent evaluation passes were conducted — standard weighted scoring, technical-feasibility emphasis, and business-value emphasis. Two of the three runs (Runs 2 and 3) selected the same candidate; Run 1 dissented in favor of a lower-risk alternative. The 2/3 majority prevails, with Run 1's case for the alternative explicitly documented in Appendix A: Multi-Agent Subsystem Selection.

2.1 Why Finance — Gift Processing

Gift processing is OpenPetra's flagship donor workflow. A donor sends money, the back office posts a gift batch with motivations and tax-deductibility classification, and the system generates annual tax receipts. It is the defining operational capability of a non-profit ERP, spanning bank import through GL posting through year-end receipting.

This is the right pilot for four reasons:

• Marquee business value. Donations are the primary revenue mechanism for non-profit organizations. Modernizing gift processing directly impacts the headline workflow and provides the highest-visibility demonstration of modernization ROI to executive sponsors and boards.
• Pattern reusability across the programme. Gift Processing exercises every spine pattern the rest of the modernization needs: typed-dataset ORM to Entity Framework Core, ASMX web service to ASP.NET Core REST, AngularJS jQuery forms to Angular 20 reactive components, code-generated DAL re-targeting, batch-state machinery for strangler routing, multi-currency and tax-receipt rendering. Patterns proven here transfer directly to Donations Processing, Finance — Banking, Finance — Budgeting, and Reporting — Financial Statements.
• Clean strangler boundary. The implementation is concentrated in a small set of named seams — TGiftTransactionWebConnector, TGiftBatchFunctions, and the AGift/AGiftBatch/AGiftDetail tables. The posted/unposted batch state machine gives the strangler-fig migration a natural routing key.
• Right-sized scope. 279 files is meaningful enough to validate the modernization approach, yet bounded enough to complete as a focused pilot. Substantially smaller than Finance — Accounting (370 files) or System Management — Users (390 files), yet large enough to demonstrate real migration capability — unlike Sponsorship — Program Management (12 files) or Hospitality — Accommodation (5 files).

2.2 Technical Scope and Dependencies

Finance — Gift Processing comprises 279 C# files. Its primary integration affinity is to Donations Processing (0.8) and Finance — Accounting (0.6). The web-connector RPC pattern maps cleanly to ASP.NET Core controllers, and the batch posting workflow provides a natural state-based seam for the classical strangler-fig migration strategy specified in the architecture plan. Integration with the legacy MFinance GL is direct but narrow (batch posting contract), enabling a strangler boundary that preserves legacy ledger writes while the new system fronts donor entry and receipting.

2.3 Alternative Methodology: Multi-Agent Subsystem Selection

Finance — Gift Processing was identified through Concho's multi-agent consensus methodology, where three independent AI agents evaluate all subsystems from different perspectives using quantified criteria, then reach consensus on optimal modernization priorities. Two of the three runs converged on Gift Processing; Run 1 advocated for Finance — Banking as a lower-risk alternative. See Appendix A: Multi-Agent Subsystem Selection for the complete three-run analysis, scoring matrices, divergence rationale, and the credible-alternative case for Banking.

3. Legacy System Analysis

3.1 High-Level System Architecture

OpenPetra implements a layered monolithic architecture with extensive code generation driven by XML schema definitions. The Database Schema Definition (db/petra.xml) serves as the single source of truth, orchestrating a Code Generation Pipeline that produces strongly-typed datasets, ORM layers, and RPC interfaces across every layer. The result is a data-centric design: the schema is not merely persistence, it is the architectural backbone.

Five characteristics stand out from the Concho analysis:

• Report-heavy presentation layer — XML report templates account for 42,307 lines (12.6% of source code), reflecting the regulatory and transparency demands of non-profit operations.
• Multi-database abstraction — a unified data-access layer supports PostgreSQL, MySQL, and SQLite via a single typed-dataset / ORM-generation pattern (TDBType enum, CommonTypes.ParseDBType()).
• Extensive validation framework — 14,465 lines (4.3% of source code) of cross-domain validation, ensuring data integrity for financial operations.
• Bidirectional integration patterns — 83 of 150 integration points are bidirectional, indicating heavy synchronous request/response coupling.
• Legacy .NET Framework foundation — .NET Framework 4.7 with .NET Remoting underpinning RPC-based client-server communication.

The Mermaid diagram below is the Concho-vended architecture-layer diagram retrieved from the Concho Context Graph artifact store.

Source: Concho Context Graph — architecture_layer_diagram artifact, confidence 0.95.

3.2 Architectural Layers

Concho's architecture-tree analysis decomposes the codebase into eight top-level layers with a line-count distribution that immediately reveals where the legacy weight lives.

Three observations matter for modernization planning:

• Finance Management dominates application logic (61,632 LOC), and within it Gift Processing (17,103 LOC) sits next to General Ledger (22,615 LOC) — the chosen subsystem boundary therefore has a real, measurable presence rather than being a token slice.
• Report Templates are the largest single sub-cluster (43,521 LOC). They use a proprietary NO-SQL template syntax that escapes static analysis; the modernization plan needs an explicit strategy for them (see Section 6 and Section 10).
• Code Generation is itself 12,379 LOC. The build system generates a significant share of the C# in the Data Layer and Application Layer — meaning the modernization plan cannot simply "translate the code"; it must decide whether to keep the generation pipeline, port it, or replace it (Section 4, Section 8).

3.3 Data Entities

Concho's entity extraction discovered 48 aggregate roots across 34 bounded contexts with 100% STRUCTURAL evidence (i.e., every root is grounded in a concrete code structure, not inferred). The average is 6.4 relationships per entity, and the domain enforces 265 business rules across these roots at an average confidence of 0.80. The table below lists the highest-confidence aggregate roots that participate in or border the Finance — Gift Processing slice.

Source: Concho search_entities (aggregate_root, confidence ≥ 0.75) plus the business_domain_map and bounded_context_map artifacts. The full Concho catalogue contains 40 aggregate roots at confidence ≥ 0.75 across all domains; only those participating in or bordering the Gift Processing slice are shown here.

The ER diagram below is derived from Concho entity discovery (relationships above are extracted from the Concho aggregate-root metadata; cardinalities follow the OpenPetra typed-dataset definitions referenced by Concho as PPartnerTable, AGiftBatchTable, AGiftTable, AGiftDetailTable). It is intentionally scoped to the Gift Processing slice and its immediate borders.

Derived from Concho entity / architecture discovery (search_entities + business_domain_map). Not a single Concho-vended artifact; constructed by the project-intel agent from Concho data.

3.4 Business Rules & Behavior

Concho's Business Rule Matrix artifact (confidence 0.92) catalogues 216 business rules distributed across 48 aggregate roots and 100 workflows within 33 bounded contexts:

• 43% validation rules — data integrity, format constraints, domain invariants.
• 17% authorization rules — module-level access control, permission gates.
• 16% derivation rules — computed fields, currency conversions, allocations.
• The remaining 24% cover orchestration, lifecycle, and integration rules.
• Overall mean confidence: 0.70; 40 rules are explicitly flagged as compliance-relevant.

Section 9 (Business Rules Analysis) populates this rule catalogue with explicit Given-When-Then specifications for the rules that govern the Gift Processing slice — sequential batch numbering, financial-period validation, partner existence, motivation-code assignment, multi-currency exchange-rate lookup, SEPA mandate compliance, posting-status transitions, and tax-receipt eligibility. These specifications then feed the BDD/TDD code-generation loop described in Section 1.6.

Placeholder: the full Given-When-Then catalogue is generated by the behavioral-rules phase (Section 9) and is not duplicated here.

3.5 Technology Stack

OpenPetra's documented technology footprint as catalogued by Concho:

Across all 34 technology subjects, three observations frame the target-architecture decisions in Section 4: (1) the language is already C#, so the move to .NET 10 is a runtime/library port rather than a re-write; (2) the front-end is jQuery, so an Angular 20 rebuild is unavoidable but localized; (3) the data tier already runs PostgreSQL, so the modernization can lift-and-shift schemas while flattening the multi-RDBMS abstraction layer.

3.6 Integration Patterns

Concho's Integration Boundary Map (confidence 0.95) documents 150–151 integration points across 216 files: 28% file integrations, 25% web connectors, 88.7% supported by STRUCTURAL evidence, average confidence 0.71. Bidirectional connections dominate (83 of 151), indicating heavy synchronous request/response coupling rather than event-driven decoupling. The dominant integrations are TSponsorshipWebConnector, TImportExportWebConnector, the OpenPetra SOAP Web Service, Partner Contact Search, and TGiftTransactionWebConnector.

The data-flow diagram below is the Concho-vended data_flow_diagram artifact. It highlights four primary data channels: web-form imports, automated bank imports, gift-batch CSV imports, and report generation. All four converge on the Finance Operations Engine and Partner Management Operations, which persist through the multi-RDBMS Database Abstraction Layer.

Source: Concho Context Graph — data_flow_diagram artifact, confidence 0.88.

Three properties of this picture become design constraints for the modernization:

• The Gift Processing slice has a sharp inbound seam (CSV/MT940/CAMT) and a sharp outbound seam (GL posting). Both are good strangler-fig boundaries: replaceable independently of the rest of the application.
• RPC web connectors are the dominant client/server protocol, not REST or events. The target architecture replaces these with explicit REST endpoints on ASP.NET Core 10 (Section 4 and Appendix B).
• The Code Generation Pipeline is wired into the runtime data path, not just the build — the ORM that runs is generated by the same pipeline that builds. The legacy/modern coexistence plan in Section 11 has to keep that pipeline working on the legacy side while the modern side migrates to EF Core.

4. Target Architecture

This section defines the target Azure App Service architecture for the modernized Finance — Gift Processing subsystem (279 files, DonationManagement bounded context), including design principles, technology stack, code-level architecture decisions, and target data model. A multi-agent service architecture analysis determined the optimal decomposition: 2 microservices for this modernization — Gift Processing API and Receipt Generation Service.

The 2-service architecture was selected through unanimous consensus of Domain-Driven Design, Technical Architecture, and Business Capability analyses, achieving a composite decision score of 7.8 / 10 (gate: ≥ 7.0). Section 4.5 summarizes the decision; the full multi-perspective analysis — per-lens proposals, rejected alternatives, per-service API contracts, and the implementation roadmap — is documented in Appendix B: Service Architecture.

4.1 Target Architecture Overview

The modernized Gift Processing subsystem is deployed as a multi-service .NET 10 application on Azure App Service, replacing the legacy Mono/FastCGI-hosted ASP.NET Web Services (.asmx/SOAP) architecture with a modern REST API backed by Entity Framework Core on Azure Database for PostgreSQL. The Angular 20 single-page application replaces the legacy jQuery/AngularJS front-end, delivering a responsive donor management experience served as static files from the same App Service plan.

The architecture follows the classical strangler-fig modernization strategy: Azure API Management routes gift-processing traffic to the new .NET 10 services while legacy subsystems (GL posting, Partner management) continue operating on the existing infrastructure. As each subsystem is modernized, traffic shifts from legacy to modern without requiring a big-bang cutover. The DonationManagement bounded context (confidence 0.84) maps directly to the service boundary, with read-only Partner validation and one-way GL posting accessed through well-defined integration interfaces fronted by the strangler bridge.

Key Architecture Principles

• API-first design. All gift processing operations are exposed through ASP.NET Core Minimal APIs with OpenAPI documentation (Swashbuckle), enabling both the Angular SPA and future integrations to consume the same contract.
• Bounded context alignment. Service decomposition maps to the DonationManagement bounded context identified by Concho analysis, keeping gift batch processing, receipt generation, and recurring gift management within a cohesive service boundary.
• Same-language modernization. C# to C# transition (from .NET Framework 4.7 to .NET 10) preserves domain knowledge embedded in the existing codebase while modernizing the runtime, dependency injection, async patterns, and configuration model.
• Strangler-fig routing. Azure API Management owns the public surface and routes per-path: modern endpoints to the new App Services, unmodified routes (Partner, GL, Reporting until later phases) to the legacy server. This enables incremental traffic shifting without coordinated big-bang cutovers.
• Observability by default. OpenTelemetry tracing and Serilog structured logging with correlation IDs feed into Azure Application Insights, providing end-to-end visibility across gift processing workflows from bank import through GL posting and annual receipt generation.
• Infrastructure as Code. All Azure resources are defined in Bicep templates, enabling repeatable provisioning across development, staging, and production environments with slot-based blue/green deployments.
• Resilience through Polly. Transient fault handling with exponential backoff and circuit breaker patterns protect against downstream dependency failures (Partner validation, GL posting bridge), ensuring gift processing degrades gracefully rather than failing completely.

4.2 Target Architecture Diagram

graph TB
    subgraph "Client Layer"
        SPA["Angular 20 SPA
(Gift Batches, Recurring Gifts,
Motivations, Bank Import,
Annual Receipts)"]
    end

    subgraph "Edge & Gateway"
        FD["Azure Front Door
(WAF + TLS Termination)"]
        APIM["Azure API Management
(Strangler-Fig Routing)"]
    end

    subgraph "Azure App Service Plan (P1v3 Linux)"
        API["Gift Processing API
(.NET 10 Minimal API)
- Batch CRUD & Posting
- Tax Deductibility Calc
- Multi-Currency Handling
- Recurring Gift Mgmt"]
        RECEIPT["Receipt Generation Service
(.NET 10)
- Annual Receipt PDF
- HTML Template Processing
- Donor Statement Export"]
    end

    subgraph "Data & State"
        PG[("Azure Database
for PostgreSQL
(Gift Batches, Gifts,
Gift Details, Motivations,
Recurring Gifts)")]
        REDIS["Azure Cache
for Redis
(Session, Caching)"]
        BLOB["Azure Blob Storage
(Receipt PDFs,
Import Files)"]
    end

    subgraph "Security & Config"
        KV["Azure Key Vault
(Connection Strings,
API Keys)"]
        ENTRA["Microsoft Entra ID
(User Auth)"]
    end

    subgraph "Observability"
        AI["Azure Application Insights
(Traces, Metrics, Logs)"]
        LAW["Log Analytics
Workspace"]
    end

    subgraph "Legacy Bridge (Strangler-Fig)"
        LEGACY_PARTNER["Legacy Partner Service
(Read-Only Validation)"]
        LEGACY_GL["Legacy GL Service
(One-Way Posting)"]
    end

    SPA --> FD
    FD --> APIM
    APIM --> API
    APIM --> RECEIPT
    APIM -.->|"unmodified routes"| LEGACY_PARTNER
    APIM -.->|"unmodified routes"| LEGACY_GL
    API --> PG
    API --> REDIS
    API --> BLOB
    API --> KV
    API --> ENTRA
    API --> AI
    API -.->|"REST/JSON"| LEGACY_PARTNER
    API -.->|"REST/JSON"| LEGACY_GL
    RECEIPT --> PG
    RECEIPT --> BLOB
    RECEIPT --> AI
    AI --> LAW

    classDef modern fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    classDef azure fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef legacy fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dasharray:5
    classDef client fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px

    class SPA client
    class API,RECEIPT modern
    class FD,APIM,PG,REDIS,BLOB,KV,ENTRA,AI,LAW azure
    class LEGACY_PARTNER,LEGACY_GL legacy
  

Target Azure App Service architecture for Finance — Gift Processing — 2-microservice decomposition (Gift Processing API + Receipt Generation Service) from multi-agent consensus analysis (composite score 7.8/10). Full analysis in Appendix B.

4.3 Target Technology Stack

The technology choices above are deliberately conservative for a pilot modernization: Azure App Service eliminates container orchestration complexity, PostgreSQL preserves the existing data engine, and the C#-to-C# path reduces translation risk. Each choice is proven at scale in Azure-hosted .NET workloads and provides a reusable pattern for subsequent subsystem modernizations (Finance — Banking, Finance — Accounting).

4.3.1 Target Code-Level Architecture Decisions

The following table documents code-level patterns and library choices that govern all generated code examples throughout this report (Sections 7–9 and Appendix C). These decisions are resolved from the Azure App Service architecture template's targetPatterns block (no project-specific overrides applied) and apply uniformly across all services in the subsystem.

4.4 Target Data Model

The target data model is derived from Concho's analysis of the legacy petra.xml-generated typed datasets and the 11 SQL query files associated with the Finance — Gift Processing subsystem. The model normalizes the legacy schema into PostgreSQL-native types while preserving the core entity relationships: gift batches contain gifts, gifts contain gift details, and motivations categorize donations for financial reporting and tax compliance.

erDiagram
    GIFT_BATCH {
        int batch_id
        int ledger_id
        varchar batch_description
        varchar batch_status "Posted | Unposted | Cancelled"
        date gl_effective_date
        varchar currency_code
        decimal exchange_rate_to_base
        int batch_year
        int batch_period
        timestamp created_at
        timestamp updated_at
    }

    GIFT {
        int gift_id
        int batch_id
        int gift_transaction_number
        bigint donor_partner_key
        date date_entered
        boolean receipt_printed
        boolean first_time_gift
        varchar method_of_giving_code
        varchar method_of_payment_code
        varchar receipt_letter_code
        varchar reference
    }

    GIFT_DETAIL {
        int gift_detail_id
        int gift_id
        int detail_number
        bigint recipient_partner_key
        decimal gift_transaction_amount
        decimal gift_amount_in_base_currency
        decimal gift_amount_intl
        varchar motivation_group_code
        varchar motivation_detail_code
        varchar cost_centre_code
        varchar account_code
        decimal tax_deductible_pct
        boolean tax_deductible
        varchar gift_comment_one
        varchar gift_comment_two
        varchar gift_comment_three
        boolean modified_detail
        boolean confidential_gift
    }

    MOTIVATION_GROUP {
        varchar motivation_group_code
        int ledger_id
        varchar motivation_group_description
        boolean group_status_active
    }

    MOTIVATION_DETAIL {
        varchar motivation_group_code
        varchar motivation_detail_code
        int ledger_id
        varchar motivation_detail_desc
        varchar account_code
        varchar cost_centre_code
        decimal tax_deductible_pct
        boolean receipt_eligible
        boolean active
    }

    RECURRING_GIFT_BATCH {
        int batch_id
        int ledger_id
        varchar batch_description
        varchar batch_status
        varchar currency_code
        decimal exchange_rate_to_base
    }

    RECURRING_GIFT {
        int recurring_gift_id
        int batch_id
        bigint donor_partner_key
        varchar frequency_code
        date start_donations
        date end_donations
        varchar sepa_mandate_reference
        date sepa_mandate_date
    }

    RECURRING_GIFT_DETAIL {
        int recurring_gift_detail_id
        int recurring_gift_id
        int detail_number
        bigint recipient_partner_key
        decimal gift_amount
        decimal gift_amount_intl
        varchar motivation_group_code
        varchar motivation_detail_code
        varchar cost_centre_code
        varchar account_code
        decimal tax_deductible_pct
    }

    GIFT_BATCH ||--o{ GIFT : "contains"
    GIFT ||--o{ GIFT_DETAIL : "has details"
    GIFT_DETAIL }o--|| MOTIVATION_DETAIL : "categorized by"
    MOTIVATION_GROUP ||--o{ MOTIVATION_DETAIL : "groups"
    RECURRING_GIFT_BATCH ||--o{ RECURRING_GIFT : "contains"
    RECURRING_GIFT ||--o{ RECURRING_GIFT_DETAIL : "has details"
    RECURRING_GIFT_DETAIL }o--|| MOTIVATION_DETAIL : "categorized by"
  

Target Table Structure Details

Cross-service data access: The donor_partner_key and recipient_partner_key columns reference Partner records managed by the legacy system. These are not foreign keys in the target database — the drop-constraints slice-boundary FK policy (specified in report-plan.json) means partner validation is enforced at the application layer through the strangler-fig bridge to the legacy Partner service, not through database-level referential integrity. This enables independent deployment of the gift-processing slice without requiring Partner modernization to complete first.

For detailed schema mappings from legacy typed datasets and SQL query files to this target data model, see Section 10: Data Mapping Strategy.

4.5 Target Service Architecture

4.5.1 Consensus Across Lenses

4.5.2 Open Questions Resolved

4.5.3 Target Service Summary

4.5.4 Target Integration Pattern

Gift Processing API is the authoritative source of donation data. Receipt Generation Service is a one-way downstream consumer that reads posted gifts via REST and produces immutable PDF artifacts. There is no shared database, no shared EF Core context, and no Gift Processing dependency on Receipt Generation. Both services sit behind Azure API Management with the same authentication, observability, and strangler-fig routing surface described in Section 4.1.

For the complete multi-perspective analysis — per-lens proposals, rationale for rejecting alternatives, full per-service API contracts, sample C# interfaces, OpenAPI excerpts, message envelopes, and the implementation roadmap — see Appendix B: Service Architecture.

5. Platform Affinity Analysis

Every legacy platform imposes constraints on the software that runs on it. Some of those constraints encode genuine business requirements — a tax-deductibility percentage reflecting national charity law, a SEPA mandate window enforcing banking compliance, or a posted/unposted state machine protecting financial integrity. Others are pure platform artifacts: an EOL runtime that lacks types now in-box on newer frameworks, a hosting bridge that splits responsibility across three layers, or a UI toolchain whose bundler is no longer maintained. Getting the distinction right is critical to avoiding two failure modes — replicating unnecessary limitations in the modern system (wasting engineering effort reproducing constraints that serve no purpose), or accidentally breaking a business rule that was disguised as a platform constraint (producing software that silently violates business intent).

The Petra slice is unusual in that the language family is unchanged (C# → C#), but the runtime, hosting model, client framework, and toolchain all move. That makes every entry below highly concrete: each constraint either (a) goes away because the runtime is .NET 10 instead of .NET Framework 4.7, (b) goes away because the host is Azure App Service + Kestrel instead of Mono FastCGI, (c) goes away because the client is Angular 20 instead of jQuery 3.6, or (d) collapses because the storage abstraction reduces to PostgreSQL-only on the modern side. Entries are classified platform-driven (ELIMINATE), hybrid (eliminate the platform artifact, preserve the business intent), or business-driven (PRESERVE). Pure PRESERVE entries are uncommon in Section 5 by design — this section is fundamentally about unlocks; pure business preservation lives in Section 9 (Business Rules Analysis).

5.1 Capacity Constraints

5.1.1 .NET Framework 4.7 Runtime Ceiling

5.2 Processing Model Constraints

5.2.1 ASP.NET Web Services (.asmx) Synchronous SOAP/RPC Pipeline

5.2.2 Mono FastCGI Hosting Model and [ThreadStatic] Isolation

5.2.3 Multi-Currency Engine Observability Gap

5.3 User Interface Constraints

5.3.1 jQuery / ES5 Web Client Ceiling

5.3.2 Bootstrap 4 + popper.js 1.x + FontAwesome 5 EOL UI Library Stack

5.3.3 i18n Toolchain Lock-In (i18next 10 + GNU Gettext PO)

5.4 Data Type Constraints

5.4.1 Code-Generated Typed Dataset / SortedList Parameter Rigidity

5.4.2 Newtonsoft.Json Reflection-Based Serialization Defaults

6. Technical Debt Analysis

6.1 Methodology

This section presents a structured analysis of technical debt in the Petra (OpenPetra) codebase, drawing on two distinct evidence sources. Architectural concerns (Sections 6.2–6.6) are derived from Concho’s architectural assessment (get_architecture_insight), which evaluates the system’s 12 major and secondary architectural elements across 8 root layers and identifies severity-ranked areas of concern with element-level scoping. Outdated dependencies (Section 6.7) are derived from direct inspection of the dependency manifest files Concho catalogs in the source — the server-side csharp/ThirdParty/packages.config (NuGet, 19 packages) and the front-end js-client/package.json (npm, 13 packages, including dev/build tooling).

The architectural concerns in 6.2 are each classified against the proposed target architecture (.NET 10 + Angular 20 on Azure App Service with Azure Database for PostgreSQL — see Section 4) using four buckets: retired by target, mitigated by target, inherited, and out of scope. Section 6.7 uses a separate two-axis framework appropriate for library-level debt (lifecycle status × target action) because a per-version catalog is the right artifact for that category of debt. Both classification frameworks are intended to give stakeholders a defensible answer to the question “what specifically is broken today, and what does the modernization fix?”

This section is not a code-quality lint report, a comprehensive security audit, or a bug list. 6.2–6.6 are architectural-level debt — patterns and design choices — while 6.7 is library-level debt — specific package versions with known EOL dates, migration paths, or modern equivalents. The two categories deserve separate framings because they reach different stakeholders.

6.2 Severity-Ranked Architectural Concerns

Concho’s architectural assessment (LLM confidence: 0.85) identified 7 areas of concern across the Petra codebase. Each concern is classified against the target architecture defined in Section 4. Highest severity first.

Severity is Concho’s assessment, not re-weighted by this analysis. Classification reflects how the resolved target architecture (Section 4) handles each concern.

6.3 Detailed Concern Narratives

jQuery / ES5 Web Client (High — Retired by Target)

The Web Client Interface is the single high-severity concern in Concho’s assessment. The current front-end (6,682 LOC, 2.3% of the project) is implemented in jQuery 3.6 and vanilla JavaScript targeting ES5, with browserify as the module bundler, popper.js for tooltip positioning, and Bootstrap 4.6 for layout. The stack was reasonable circa 2016–2018, but in 2026 it constrains the team on three axes: (1) no component model, so reusable UI is copy/paste at the template level rather than encapsulated components; (2) no reactive change detection, so screens that touch many fields (Annual Receipts, Gift Batch posting) hand-wire DOM updates; (3) developer recruitment friction — jQuery experience is increasingly rare in junior hires.

The Gift Processing modernization slice replaces this layer wholesale with Angular 20 (standalone components, signals, reactive forms, the official Angular Material accessibility surface). All five in-scope screens — Gift Batches, Recurring Gifts, Motivations, Bank Import, Annual Receipts — are rebuilt as Angular components consuming the new ASP.NET Core 10 REST endpoints. Section 7 walks through one example end-to-end. The legacy jQuery client remains in production for non-Gift-Processing surfaces (Partner, GL, Reporting) during the strangler-fig coexistence window, but the slice is fully retired from a UI-stack perspective.

Multi-Currency Performance in the Finance Operations Engine (Medium — Mitigated by Target)

The Finance Operations Engine is the largest architectural element (49,362 LOC, 17.2%) and houses the multi-currency, multi-country tax-deductibility, and ledger-posting math that defines Petra’s value. Concho flags it as medium severity not because the math is wrong but because (a) workflow complexity is concentrated — the engine carries 70% of the system’s HIGH-complexity workflows per the workflow-complexity artifact — and (b) automated batch operations (annual receipts, recurring-gift processing) have no observability today, making bottlenecks invisible until they show up as user-reported slowdowns.

The target architecture mitigates rather than retires this concern: the calculations themselves are correct domain logic that must be preserved verbatim, and they cross the modernization boundary unchanged (see Section 8 for the per-currency rounding example). What the target adds is observability — OpenTelemetry instrumentation through Serilog and Azure Application Insights gives per-batch latency, throughput, and per-currency calculation timing; the FluentValidation pipeline replaces hand-rolled TVerificationResult validation with consistent ProblemDetails responses; xUnit + WebApplicationFactory testing brings the engine under coverage that the legacy NUnit suite touches only at the integration boundary. The bottleneck risk is not eliminated — it is made visible, which is the precondition for fixing it when it materializes.

TPetraPrincipal Session Authentication (Medium — Retired by Target)

The Security Authorization Framework (6,685 LOC) is built on TPetraPrincipal + TOpenPetraOrgSessionManager, a custom session-based auth scheme rooted in .NET Remoting conventions. Sessions are stored server-side, sessions cookies are scoped to the ASP.NET host, and credential validation happens against a Petra-specific user store with custom permission tables. Concho flags this as medium severity for the absence of modern patterns: no OAuth flow, no JWT bearer tokens, no federation, no MFA support, no audit-trail of token issuance separate from request logs.

The target retires the framework entirely. Section 4 specifies Microsoft Entra ID (formerly Azure AD) for user authentication via the OIDC authorization-code-with-PKCE flow, JWT bearer tokens for API authorization, and Managed Identity for service-to-service authentication (Gift Processing API → Receipt Generation Service, Gift Processing API → Azure Key Vault, Gift Processing API → Azure Service Bus). Petra’s permission-table semantics are preserved as role claims on the JWT — the modernization keeps the authorization model while replacing the authentication mechanism. Annual receipt PDF access (today gated by the session cookie + a custom token table) is replaced by short-lived SAS URIs minted by the Gift Processing API after a JWT-authenticated request.

Medium-Severity Concerns Outside the Slice

XML Report Template Definitions (Out of Scope). The proprietary “NO-SQL” report template syntax (39,992 LOC, 14.0% of the analyzed source) is a significant maintenance surface but lives entirely outside the Gift Processing slice. Receipt PDF generation in the modernized service uses an HTML/CSS template processed by a headless renderer rather than the legacy XML templates. The legacy report templates continue to drive the GL, Partner, Conference, and Reporting subsystems during strangler-fig coexistence and are inventoried here as future-investment debt — not a debt the Gift Processing modernization addresses.

Partner Management Transaction Complexity (Out of Scope). TPartnerEditWebConnector coordinates many distinct CRUD operations within a single transaction boundary, and Concho flags this as a transaction-management risk. The Gift Processing slice consumes Partner data read-only through a REST bridge (validation of donor_partner_key and recipient_partner_key) — it does not write to the Partner aggregate. The Partner write surface remains on the legacy stack post-cutover; its modernization is a future slice, not this one.

Low-Severity Concerns

• Common Utilities Framework — Concho flags shared ArrayList and Utilities classes as a tight-coupling risk. The target reduces this through dependency injection, scoped services, and typed collections (List<T>, IReadOnlyList<T>) replacing the non-generic legacy collections. Coupling is mitigated, not eliminated — some shared helpers (currency formatting, partner-key parsing) remain as a small Shared.Domain library on the .NET 10 side.
• Development Tools Suite — TinyWebServer and the assorted in-tree utilities are retired by moving to Kestrel + the standard dotnet CLI + Azure DevOps / GitHub Actions tooling. No bespoke development server is needed; the Angular CLI handles the SPA dev server independently.

6.4 Architectural Strengths to Preserve

Concho’s assessment identifies 5 architectural strengths. Each is paired below with an explicit note on how the target architecture preserves the underlying property, because a section that catalogs only debt reads as a hatchet job and undermines stakeholder trust in the analysis.

• XML-driven schema generation provides single-source-of-truth. (Data Layer.Database Schema) The db/petra.xml master schema is the canonical definition of every table, field, and relationship. The target preserves the single-source-of-truth property by keeping a code-generation step — the EF Core entities for the Gift Processing slice are themselves generated from a curated subset of petra.xml for the 8 gift tables, ensuring that schema drift between the legacy and modern stores is mechanically prevented during coexistence (and discoverable via migration diffing thereafter).
• Code Generation Pipeline (TDataDefinitionParser / TDataDefinitionStore). (Build & Deployment.Code Generation) The pipeline that transforms XML schema into C# code, RPC interfaces, and database DDL is automated, repeatable, and well-isolated. The target preserves the idea of generated infrastructure but replaces the NAnt-driven implementation with EF Core migrations + a one-time generator. The generator is retired once the EF Core baseline is committed; the property of “schema changes propagate without manual edits” is retained.
• Multi-database abstraction. (Data Layer.Data Access) The legacy TDBType enum supports PostgreSQL, MySQL, and SQLite through a unified connection-factory pattern. The target collapses to PostgreSQL only (Azure Database for PostgreSQL Flexible Server) but preserves the abstraction property at a different level: EF Core providers + repository interfaces let the team add a different store later without rewriting business code. The fact that Petra runs on PostgreSQL today made the modernization’s engine choice mechanical, not contested.
• Business Rules Validation Engine (TVerificationResult). (Cross-Cutting Concerns.Validation Framework) The cross-layer validator pattern enforces business rules consistently across modules and is the single most reused infrastructure in the codebase. The target preserves the property — consistent validation across all API boundaries — through FluentValidation, with the same rules expressed as validator classes and the same domain-exception → RFC 7807 ProblemDetails translation in the middleware. The validation semantics are preserved verbatim; only the framework changes.
• Integration Test Infrastructure. (Test.Integration Tests) The NUnit-based integration suite (9,461 LOC) provides specialized fixtures for partner editing, gift processing, and financial-period rollover. The target preserves this property — comprehensive integration coverage — through xUnit + WebApplicationFactory + Testcontainers (PostgreSQL), with the same fixture concepts ported (a GiftBatchFixture that seeds a posted/unposted batch pair is a direct port of the legacy NUnit setup). The 80% coverage target in Section 4 is set explicitly to honor the strength.

6.5 Source-Language Anti-Patterns Observed

The active dotnet-angularjs source profile carries an antiPatternsToCheck list — common framings that get applied incorrectly to .NET+AngularJS prospects. The following items from that list are observable in the Petra codebase and are called out here so the modernization plan handles them correctly:

• .asmx is not “hard SOAP.” Petra’s TGiftTransactionWebConnector and related .asmx endpoints use the SOAP envelope shape but a JSON wire format with binary-serialized SortedList parameters — closer to JSON-RPC over SOAP framing. The modernization narrative in Section 8 treats this as “HTTP-RPC → REST”, not “SOAP → REST”, because the SOAP framing is cosmetic.
• Code-gen-from-XML is the source of truth. The data access layer (*.Generated.cs files emitted by TDataDefinitionParser) is not hand-maintained — editing the generated files is futile. The target retires the generation pipeline first (one-time export to EF Core entities for the 8 gift tables) before the EF Core migration begins, so the generated layer cannot overwrite EF Core changes mid-modernization.
• Multi-database assumption. The connection string and TDBType abstraction support PostgreSQL, MySQL, and SQLite. Petra production runs on PostgreSQL; the modernization commits to PostgreSQL only on the modern side, but the legacy stack continues to run against whichever backend it is configured for during coexistence.
• AngularJS framing does not apply. Petra uses jQuery, not AngularJS — the source profile shares an ID with AngularJS prospects but Petra’s UI is older. The modernization plan treats this as a jQuery → Angular rewrite, not an AngularJS → Angular upgrade. The migration is years lighter than an ngUpgrade-based hybrid would be, because there is no Angular 1.x scope hierarchy to bridge.
• Mono FastCGI hosting. Petra’s Linux deployments run under fastcgi-mono-server4 with Apache or nginx in front. This is incompatible with Azure App Service Linux. The target replaces it with Kestrel + the standard ASP.NET Core hosting model; no Mono runtime is involved in the modern slice.

6.6 Debt Outside Migration Scope

Two of the seven Concho-surfaced concerns are real architectural debt but live outside the Gift Processing modernization slice (Section 2):

• XML Report Template Definitions. 39,992 LOC of proprietary “NO-SQL” report templates drive the GL, Partner, Conference, and Reporting subsystems. The modernization slice produces HTML/CSS receipt templates only; the legacy report templates continue to operate on the legacy stack. A future modernization slice would inventory these templates and decide whether to port them to a modern reporting engine (e.g., FastReport, JS Reports, or HTML/PDF) or rewrite the subsystem they belong to entirely.
• Partner Management Operations. TPartnerEditWebConnector remains on the legacy stack. The Gift Processing slice consumes Partner data read-only through a REST bridge; the Partner write surface and its transaction-management complexity are inherited by the legacy system until a Partner-focused modernization slice is commissioned.

Calling these out as out-of-scope is deliberate: stakeholders should know they are real debts that the engagement does not address. A future investment case for Partner or Reporting modernization would inherit these line items as starting evidence.

6.7 Outdated Dependencies

Library-level debt is a different category from architectural debt and gets its own catalog. Concho’s file inventory confirms two dependency manifests in the Petra source tree:

• csharp/ThirdParty/packages.config — NuGet packages for the .NET Framework 4.7 server (19 packages, 35 lines).
• js-client/package.json — npm packages for the jQuery web client (13 dependencies including dev/build tooling, 37 lines).

Two other .csproj files exist in the source (inc/nanttasks/NanttasksForDevelopers.csproj and inc/template/vscode/template.csproj) but reference only NAnt build assemblies and a template skeleton respectively — no third-party application dependencies. They are excluded from the catalog.

The two manifests below give stakeholders the actual bill of materials, classified on lifecycle status (current / outdated / EOL-major / EOL-project / known-CVE) and target action (removed / replaced / upgraded / kept-with-risk / outside-slice).

Server-side — csharp/ThirdParty/packages.config (NuGet)

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="NUnit"                              version="3.13.3"/>
  <package id="NUnit.Console"                      version="3.15.2"/>
  <package id="NUnit.ConsoleRunner"                version="3.15.2"/>
  <package id="MySqlConnector"                     version="2.2.5" />
  <package id="Npgsql"                             version="4.1.10"/> <!-- pinned: 5.x requires .NET 5+ -->
  <package id="System.Buffers"                     version="4.5.1" />
  <package id="System.Diagnostics.DiagnosticSource" version="7.0.0"/>
  <package id="Microsoft.Bcl.AsyncInterfaces"      version="7.0.0" />
  <package id="System.Runtime.CompilerServices.Unsafe" version="6.0.0"/>
  <package id="System.Memory"                      version="4.5.5" />
  <package id="System.Text.Json"                   version="7.0.1" />
  <package id="System.Threading.Tasks.Extensions"  version="4.5.4" />
  <package id="System.ValueTuple"                  version="4.5.0" />
  <package id="System.Text.Encodings.Web"          version="7.0.0" />
  <package id="MimeKit"                            version="3.5.0" />
  <package id="MailKit"                            version="3.5.0" />
  <package id="System.Runtime"                     version="4.3.1" />
  <package id="Portable.BouncyCastle"              version="1.9.0" />
  <package id="HtmlAgilityPack"                    version="1.11.46"/>
  <package id="Newtonsoft.Json"                    version="13.0.2"/>
  <package id="libsodium-net"                      version="0.10.0"/>
  <package id="SharpZipLib"                        version="1.3.3" /> <!-- pinned: 1.4.x requires .NET 6+ -->
  <package id="PDFsharp"                           version="1.50.5147"/>
  <package id="NPOI"                               version="2.6.0" />
</packages>

Front-end — js-client/package.json (npm)

{
  "name": "openpetra-client-js",
  "version": "2018.2.0",
  "dependencies": {
    "@fortawesome/fontawesome-free":   "^5.15.4",
    "axios":                           "^0.21.4",
    "bootstrap":                       "^4.6.1",
    "browserify":                      "^16.5.2",
    "browserify-css":                  "^0.15.0",
    "cypress":                         "^5.6.0",
    "i18next":                         "^10.6.0",
    "i18next-browser-languagedetector":"^2.2.4",
    "i18next-xhr-backend":             "^1.5.1",
    "jquery":                          "^3.6.0",
    "popper.js":                       "^1.16.1",
    "uglify-js":                       "^3.16.0"
  }
}

Dependency catalog — lifecycle + target action

Specific high-priority items requiring narrative.

axios 0.21.4 is the single known-CVE entry. Pre-1.0 axios has documented SSRF and prototype-pollution issues (CVE-2021-3749, CVE-2023-45857) that affect any application that forwards user-supplied URLs or parses untrusted JSON without input bounds. The migration path is not “upgrade axios” — it is “replace with Angular HttpClient,” which removes the axios surface entirely. No additional defensive code is needed in the legacy client during coexistence because the affected screens are within the slice and are being rewritten in Angular.

.NET Framework 4.7 is the load-bearing runtime EOL. Although Microsoft still ships security patches for 4.8, version 4.7.0 specifically is past mainstream support. Every server-side dependency in packages.config is pinned to a version that compiles against 4.7; removing the runtime requires committing to the .NET 10 baseline across the slice. The Gift Processing modernization treats this as the modernization’s anchoring decision — the platform target (Section 4) is .NET 10 specifically because the runtime is past EOL.

browserify / Bower-style toolchain (browserify, browserify-css, uglify-js) is the front-end’s build pipeline and is collectively retired by adopting the Angular CLI. Bower itself is not in package.json (good — Petra already moved off Bower at some prior point) but the bundler choice is similarly stale. No upgrade path exists; the Angular CLI is the replacement.

Summary. Of 28 dependencies surveyed across the two manifests plus three runtime-level entries (.NET Framework, Mono FastCGI, NAnt):

• 10 removed by target (jquery, browserify, browserify-css, uglify-js, popper.js, axios, Mono FastCGI, NAnt, MySqlConnector, System.* polyfills)
• 10 replaced by target with a different package serving the same role (.NET Framework, bootstrap, cypress, i18next, FontAwesome, Newtonsoft.Json, NUnit, libsodium-net, plus stack-wide replacements)
• 7 upgraded by target (Npgsql, SharpZipLib, PDFsharp, NPOI, MimeKit/MailKit, Portable.BouncyCastle)
• 1 kept outside slice (HtmlAgilityPack — remains on legacy stack for report templates)
• 0 kept with risk noted in the modern slice

The dependency burden of the modern Gift Processing slice is therefore dramatically smaller than the legacy footprint — most legacy packages exist to fill gaps that .NET 10 closes in-box (System.* polyfills) or to support a runtime + UI stack that is replaced entirely (jQuery + browserify era tooling).

7. UI/UX Transformation Examples

The Finance — Gift Processing subsystem has a heavy UI surface — gift batch headers, detail rows, donor lookups, motivation pickers, and posting confirmations that the legacy implementation spreads across separate jQuery/AngularJS HTML pages. Modernization to Angular 20 + ASP.NET Core 10 is an opportunity not just to re-implement those pages, but to consolidate them around the actual user journey. The use-case-discovery phase identified Gift Batch Entry through Posted GL as the highest-density use case in the subsystem (8 of 14 catalog business rules fire along its path), so it is the journey featured here.

Section 7.1 through 7.6 present the 1:1 screen translations — legacy screen on the left, modern Angular 20 mockup in the middle, platform-affinity wins on the right. Section 7.7 is the "Beyond 1:1" consolidated walkthrough: the unified Gift Batch Workspace shown in six successive scenes from empty state through pre-commit preview, commit, downstream GL view, and side-by-side coexistence with the legacy reader. Section 7.8 enumerates the modern UI design tokens; Section 7.9 (a separate fragment, appended below this section in the assembled report) is the complete field-inventory reference table derived from the same storyboard JSON.

7.1 Legacy UI Inventory

Concho’s get_files_for_architecture_layer_with_metadata("Presentation Layer") returned 12 legacy UI artifacts (6,682 lines) for the Gift Processing subsystem. The three that drive the canonical use case are:

Server-side, all three pages talk to TGiftTransactionWebConnector in csharp/ICT/Petra/Server/lib/MFinance/Gift/Gift.Batch.cs — specifically the CreateAGiftBatch and PostGiftBatch operations. The state machine across them is BATCH_CREATED → DETAILS_ENTERED → PERIOD_VALIDATED → AMOUNTS_CALCULATED → BATCH_POSTED → GL_JOURNAL_EMITTED, but no single legacy screen renders that whole pipeline; the clerk has to hop between three pages plus a server-side modal to walk it.

7.2 Gift Batches List (1:1 Translation)

The Gift Batches list page is the entry point for the use case. It enumerates today’s batches (unposted and posted), highlights which are eligible for posting, and offers a "New Gift Batch" action.

7.3 Gift Detail Entry (1:1 Translation)

The legacy Gift Detail Entry page hosts the inline grid of donations within a batch. Donor selection requires an exact partner key at a blank prompt; motivation codes are entered by typing into a separate field; no live currency conversion is shown until save. The modern equivalent puts donor autocomplete, motivation auto-fill, and live multi-currency totals into a single grid.

7.4 Motivation Picker (1:1 Translation)

The legacy Motivation Picker is a modal triggered from the Detail Entry page; in the modern unified workspace it becomes a docked side-panel that auto-updates as the donor changes. Both surface the same data — motivation groups, details, and the partner-class-driven auto-assignment — but the modern variant is always visible and always reflects the row currently in focus.

7.5 Period Validation Chip (1:1 Translation)

BR-GIFT-002’s Financial Period Validation is, in the legacy system, an invisible save-time check that throws a server error if the effective date is outside an open period. In the modern workspace it surfaces as a chip in the header that turns green/amber/red as the date is typed.

7.6 Posted Confirmation (1:1 Translation)

The final 1:1 screen is the post-commit confirmation. Legacy Petra shows a plain modal alert ("Batch 46 posted successfully"); the modern workspace converts the entire page state from amber to green and surfaces the assigned GL journal number with a deep link to the GL view.

7.7 Beyond 1:1 — The Unified Gift Batch Workspace (Multi-Scene Walkthrough)

While screen-for-screen conversions are useful, legacy modernization often offers the opportunity to combine multiple screens into a single cohesive experience. In Petra’s gift-processing slice, three legacy pages (GiftBatches.html, GiftDetailEntry.html, MotivationPicker.html) all participate in a single user journey — the daily gift-batch entry → post cycle. The modern Angular 20 unified workspace renders all three concerns at once, with responsive layout, modern form elements (autocomplete, sliders, chips), interaction patterns like live multi-currency conversion and pending-to-confirmed state transitions, and progressive disclosure of the GL posting payload.

The unified view below was auto-generated by the Concho modernization workflow. For the human-in-the-loop part, a companion storyboard in Markdown format is also auto-generated and can be edited by humans and fed back through the workflow to regenerate the screen mockups. "Scene" is a standard storyboarding term for a distinct moment in the user’s interaction; the walkthrough below has six scenes covering the empty state, donor lookup, pre-commit preview, commit, downstream GL view, and side-by-side legacy coexistence.

# Storyboard: Gift Batch Entry through Posted GL — Draft (Inferred from Code Analysis)

**Source:** Concho workflow entities + TGiftTransactionWebConnector operations (cycle 23), plus the use-case-discovery handoff (use case 1) and the behavioral-rules catalog (BR-GIFT-001/002/003/007/008/009/010/011).
**Programs Combined:** legacy GiftBatches.html, GiftDetailEntry.html, MotivationPicker.html, posting confirmation modal.
**Status:** DRAFT — inferred from TGiftTransactionWebConnector state machine + behavioral-rules catalog.
**Flow:** BATCH_CREATED → DETAILS_ENTERED → PERIOD_VALIDATED → AMOUNTS_CALCULATED → BATCH_POSTED → GL_JOURNAL_EMITTED
**Actor:** Finance Operations Clerk, processing the day’s incoming gift cheques and electronic transfers for a European non-profit ledger denominated in EUR.

---

## Scene 1: Three Screens Become One
- User: the finance clerk.
- User action: The finance clerk opens the modern unified route /forms/Finance/Gift/GiftEntry/UnifiedGiftBatch.
- Visible state: The workspace renders in empty state — header (ledger picker, effective date, batch number reserved as "next: 47"), an empty Gift Details grid, a collapsed Motivation Picker side-panel, Multi-Currency Summary showing zeros, GL Journal Preview saying "No posting payload yet".
- Business rule fired: BR-GIFT-001 has been *reserved* but no atomic increment occurs until the first save.
- Platform affinity win: legacy splits this workspace across three jQuery/AngularJS pages.

## Scene 2: Donor Search with Autocomplete
- User: the finance clerk.
- User action: The finance clerk types "Mül" into the Donor field on the first gift-detail row.
- Visible state: Autocomplete dropdown opens with three matches showing partner key, partner class, last gift date, YTD total in EUR, receipt cadence. Motivation Picker side-panel previews the motivation assignment for the highlighted match. Effective-date chip shows green "Period 5 (May 2026) — open".
- Business rule fired: BR-GIFT-002 lights up the period chip; BR-GIFT-011 drives the live motivation hint.
- Platform affinity win: legacy required exact 8-digit donor key at a blank prompt with no preview.

## Scene 3: Preview / Pending State — Multi-Currency Allocation
- User: the finance clerk.
- User action: The finance clerk selects Müller, Heinrich [UNIT · 43005001], types 500.00 into Amount, selects USD, types 87 into Tax %.
- Visible state: row in amber pending state; Multi-Currency Summary live (USD 500.00, EUR 454.55, USD 500.00 intl); Tax % shows 87.00 within bounds; GL Journal Preview populated with amber dry-run: Dr. 0100-Bank-EUR 454.55, Cr. 4500-Gift Income 395.46, Cr. 4501-Non-Deductible 59.09 — no journal number; Post button labelled "Preview only — click to post".
- Business rule fired: BR-GIFT-003, BR-GIFT-009 (clamp), BR-GIFT-010, BR-GIFT-008 (modified_detail=0 staged).
- Platform affinity win: legacy computed FX only on save; no GL preview ever possible.

## Scene 4: Commit / Confirmed State — Batch Posted
- User: the finance clerk.
- User action: The finance clerk clicks the Post Batch button. Confirmation toast slides in.
- Visible state: amber rows transition to green; "Est." prefix dropped; header shows "Batch #47 · Status: POSTED · Posted by the finance clerk · 2026-05-21 14:32 UTC"; GL Journal Preview now shows journal number GL-2026-05-21-014; Post button replaced by "Posted" chip + "View GL Posting →" link; lock icons appear on rows.
- Business rule fired: BR-GIFT-007 (Unposted → Posted + immutability); BR-GIFT-001 (atomic ++46 → 47); BR-GIFT-008 (modified_detail=0 baseline locked).
- Platform affinity win: legacy posting was a modal alert with no journal reference.

## Scene 5: Downstream Consequence — GL Posting Bridge
- User: the finance clerk.
- User action: The finance clerk clicks "View GL Posting →" in the status bar.
- Visible state: GL Posting panel expands inline; journal number GL-2026-05-21-014; three journal lines; bridged-status pill "Modern Gift Processing API → Azure API Management → Legacy GL (.asmx)"; Posting Receipt subsection with legacy GL ack id; chip "Bridged via classical-strangler-fig".
- Business rule fired: BR-GIFT-007 (Posted gate); BR-GIFT-003 (EUR base amounts with USD memo).
- Platform affinity win: legacy required navigating to a separate program to look up the GL effect.

## Scene 6 (optional): Side-by-Side Coexistence
- User: Tony, the finance manager auditing the day’s work.
- User action: Tony clicks toolbar toggle "Show legacy view".
- Visible state: page splits; legacy GiftBatches.html iframe renders read-only on the right; both halves show batch #47 with matching donor, amount, and Posted status; banner reads "Coexistence: Modern API owns writes for posted/unposted gift-batch state. Legacy reads continue against the same database."
- Business rule fired: coexistence-level; BR-GIFT-001/007/008 invariants verified across both readers.
- Platform affinity win: classical-strangler-fig commitment becomes auditable in the UI.

Scene 1: Three Screens Become One

The finance clerk opens the modernized unified route /forms/Finance/Gift/GiftEntry/UnifiedGiftBatch. The workspace renders in its empty initial state — one route, three panels, no navigation to other pages required.

Triggering user action: The finance clerk clicks the bookmark Gift Batch Workspace in their browser, which routes Angular to the unified view.

Three legacy programs collapse into one route. The header panel takes the place of GiftBatches.html, the inline grid takes the place of GiftDetailEntry.html, and the side-panel takes the place of MotivationPicker.html. No business rule has fired yet — BR-GIFT-001 has reserved the next batch number but the atomic increment will not occur until the finance clerk posts. The first state transition happens when the finance clerk interacts with the donor field, which leads us to Scene 2.

Scene 2: Donor Search with Autocomplete

The finance clerk starts typing the donor’s name into the Donor field on the first detail row. The autocomplete dropdown opens with three matches, each carrying the financial context the legacy system never surfaced: partner key, partner class, last gift date, YTD total in the ledger base currency, and a receipt-cadence indicator. The Motivation Picker side-panel updates live to preview the motivation that BR-GIFT-011 will assign for the highlighted match.

Triggering user action: The finance clerk types Mül into the Donor input.

Two business rules light up at glance time. BR-GIFT-002 (Financial Period Validation) renders the green "Period 5 / May 2026 — open" pill in the header because the finance clerk’s effective date is bound to an open accounting period. BR-GIFT-011 (Motivation Detail Assignment by Partner Class) previews the motivation that will be auto-assigned once the finance clerk selects a match — their cursor is on Heinrich Müller (partner class UNIT, no specifically-linked motivation detail, no key-ministry mapping), so the side-panel previews GIFT › SUPPORT. In Scene 3, the finance clerk will pick the match and start typing amounts.

Scene 3: Preview / Pending State — Multi-Currency Allocation

The finance clerk selects Heinrich Müller from the dropdown and types the amount, transaction currency, and tax-deductible percentage. The detail row enters pending state (amber background), and three side-panels recompute in real time: the Multi-Currency Summary shows the three running totals; the Motivation Picker confirms the auto-assigned motivation; and the GL Journal Preview — a panel that legacy Petra could never offer — shows the dry-run posting payload that will hit the GL when the finance clerk commits.

Triggering user action: The finance clerk selects Müller, types Amount 500.00, Currency USD, Tax % 87, and adds two more rows (a EUR-denominated family gift and an EUR-denominated field-project gift). They have not yet clicked Post.

Four business rules now run live. BR-GIFT-003 (Multi-Currency Gift Processing) drives the three-currency Summary — Müller’s USD 500.00 gift is converted to EUR 454.55 at the 1.10 USD/EUR rate, while the two EUR-denominated rows pass through. BR-GIFT-009 (Tax Deductible Percentage Bounds) clamped the finance clerk’s 87 % to within the [0, 100] range; had they typed 120, the input would have rejected back to 100. BR-GIFT-010 (Tax Deductibility Compliance Calculation) recomputed the deductible / non-deductible split across all three currencies and projected it into the GL Journal Preview. BR-GIFT-008 (Unmodified Detail Filter) is implicit but visible — every row is staged with a_modified_detail_l = 0, the baseline that makes future GiftAdjustment workflows idempotent. None of this preview was possible in legacy Petra because the GL journal was constructed only at posting time and held in memory.

Scene 4: Commit / Confirmed State — Batch Posted

The finance clerk clicks Post Batch. The workspace transitions from amber to green: rows lock, the batch status flips from Unposted to Posted, the GL journal number is assigned, and a confirmation toast slides in. The same data is on the page; only its colour and metadata have changed.

Triggering user action: The finance clerk clicks Post Batch → in the GL Journal Preview panel.

The pending-to-confirmed transition is the visible representation of three database transactions that happened inside a single PostgreSQL BEGIN/COMMIT block: BR-GIFT-001 atomically incremented LastGiftBatchNumber from 46 to 47 (the next clerk to start a batch will see #48); BR-GIFT-007 flipped a_batch_status_c from Unposted to Posted and locked the rows against direct edit (subsequent changes require an explicit GiftAdjustment workflow); BR-GIFT-008 set a_modified_detail_l = 0 on every row to establish the idempotency baseline. The legacy posting confirmation was a one-line modal alert with no journal reference; in the modern workspace, the journal number, posted-by user, timestamp, and the immutability state are all part of the page state.

Scene 5: Downstream Consequence — GL Posting Bridge

The finance clerk clicks the View GL Posting → link in the status bar. Instead of navigating to a different program (as the legacy GL051 enquiry would have required), the modern workspace expands an inline panel that shows the GL journal as the legacy general ledger received it — including the strangler-fig bridge metadata. This makes the coexistence pattern visible to the user: the data lives in the modern Gift Processing API, but the canonical GL journal landed in the legacy GL (which remains the system of record for ledger balances until the GL itself is modernized in a later phase).

Triggering user action: The finance clerk clicks View GL Posting → in the confirmation toast or in the Status bar.

[Modern Gift Processing API]
            |
            v
[Azure API Management]
   route: gl-journal-bridge
            |
            v
[Legacy GL (.asmx SOAP)]
   endpoint: TGLBatchWebConnector
   ack id:   LGL-2026-014-ACK

Two business rules quietly govern this view. BR-GIFT-007 is what permitted the panel to open at all — only Posted batches have an associated journal; unposted or cancelled batches return an empty panel. BR-GIFT-003 is visible in the journal lines themselves: the base-currency amount (€454.55) is the converted value of Müller’s USD 500 gift, while the memo retains the transaction-currency original. The platform-affinity win is "everything visible without leaving the page" — the legacy clerk would have had to navigate to GL051 (a separate program with its own login session) to see this; the modern clerk reads it inline.

Scene 6: Side-by-Side Coexistence (legacy mirror)

Tony, the finance manager, is auditing the day’s work. He wants to verify that the modern workspace and the legacy reader agree on the data — the contract that the classical-strangler-fig modernization plan promises. He clicks the toolbar toggle Show legacy view; the modern workspace stays where it is on the left, and the legacy GiftBatches.html page renders read-only on the right.

Triggering user action: Tony clicks the toolbar toggle Show legacy view.

No new business rule fires here — this is a coexistence-level check — but the scene is what makes the strangler-fig pattern auditable in the UI. Tony can verify in one screen that the modern endpoint and the legacy reader agree on the data. The platform-affinity win is the modernization plan’s commitment becoming first-class in the product: classical strangler-fig stops being plumbing and starts being a visible operational mode that the audit user can toggle.

7.8 Design Tokens and Modern UI Conventions

The Angular 20 mockups in this section use a small set of design tokens that recur across every screen and scene. Codifying them keeps the modernization deliberate — not ad-hoc — and makes them easy to enforce in the demo app the code-generation phase will produce.

The Section 7.9 fragment that follows enumerates every field on the unified workspace as a single inventory table. That table is the ground truth that the mockups above, the modern Angular components, and the Playwright drift-detection spec all derive from.

8. Code Translation Examples

The legacy Petra server is a .NET Framework 4.7 / Mono application that exposes Finance — Gift Processing through ASMX SOAP web services (notably TGiftTransactionWebConnector). State lives in petra-XML–generated typed DataSets; database access goes through a hand-rolled DBAccess facade that issues string-concatenated SQL against PostgreSQL, MySQL, or SQLite via the TDBType abstraction. Server-side validation is implicit in business-logic classes; logging is TLogging.Log() with severity levels; error handling is throw new EFinanceException("…") caught at the SOAP boundary; observability is essentially absent.

The target Petra server is an ASP.NET Core 10 Minimal API. Entities live in EF Core 10 (Npgsql), persisted to Azure Database for PostgreSQL Flexible Server. Validation is FluentValidation at every API boundary. Outbound calls to the legacy Partner and GL services are wrapped in Polly resilience pipelines (retry + circuit breaker). Logging is Serilog in JSON. Distributed tracing is OpenTelemetry .NET SDK, exporting OTLP to Azure Application Insights. Errors surface as RFC 7807 Problem Details. The same C# language flows through both ends — the modernization win is shape, not syntax.

8.1 Translation Principles

Seven concrete translation patterns appear in the examples below. Read together they describe the full transformation:

Where the legacy code carries implicit behavior (the SOAP layer caught exceptions and translated them into SOAP faults; the typed DataSet held cross-screen state in memory; SQL strings encoded confidentiality via aliasing), the modernized code makes it explicit: FluentValidation owns input checks, RFC 7807 owns error shape, Polly owns retry, OpenTelemetry owns trace context. The eight catalog rules that fire in the canonical Gift-Batch-Entry use case map directly onto these seven patterns.

8.2 ASMX SOAP Endpoint → Minimal-API Post-Batch (Example 1)

The most architecturally important endpoint in the subsystem is PostGiftBatch — the modernized version of this single method is the strangler-fig routing key (per Section 11). Legacy clients invoke it as a SOAP operation on TGiftTransactionWebConnector; the modernized clients hit POST /api/gift-processing/v1/batches/{batchId}/post.

// csharp/ICT/Petra/Server/lib/MFinance/
//   Gift/Gift.Batch.cs

[WebMethod]
[RequireModulePermission("FINANCE-2")]
public bool PostGiftBatch(
    Int32 ALedgerNumber,
    Int32 ABatchNumber,
    out TVerificationResultCollection
        AVerifications)
{
    AVerifications = new
        TVerificationResultCollection();

    TDBTransaction Tx = null;
    bool ok = false;

    DBAccess.GetDBAccessObj(null)
        .WriteTransaction(
            ref Tx, ref ok,
            delegate
    {
        var batchTbl = AGiftBatchAccess
            .LoadByPrimaryKey(
                ALedgerNumber,
                ABatchNumber, Tx);

        if (batchTbl.Rows.Count == 0)
            throw new EFinanceException(
                "Batch not found");

        var row = (AGiftBatchRow)
            batchTbl.Rows[0];

        if (row.BatchStatus != "Unposted")
            throw new EFinanceException(
                "Batch not Unposted");

        row.BatchStatus = "Posted";
        AGiftBatchAccess.SubmitChanges(
            batchTbl, Tx, AVerifications);

        TGLPosting.PostBatch(
            ALedgerNumber, ABatchNumber,
            Tx);
        ok = true;
    });
    return ok;
}

// src/Petra.GiftProcessing/Api/
//   GiftBatchEndpoints.cs

public static class GiftBatchEndpoints
{
  public static void MapGiftBatchPost(
    this IEndpointRouteBuilder app)
  {
    app.MapPost(
      "/api/gift-processing/v1/batches/" +
        "{batchId:int}/post",
      async (
        int batchId,
        PostBatchCommand cmd,
        IValidator<PostBatchCommand> v,
        IGiftBatchPoster poster,
        ILogger<Program> log,
        CancellationToken ct) =>
    {
      using var act = Tracing.Source
        .StartActivity("post_batch");
      act?.SetTag("batch_id", batchId);

      var vr = await v.ValidateAsync(
        cmd, ct);
      if (!vr.IsValid)
        return Results.ValidationProblem(
          vr.ToDictionary());

      var r = await poster
        .PostAsync(batchId, cmd, ct);

      log.LogInformation(
        "gift.batch.posted {BatchId} " +
        "{JournalRef}",
        batchId, r.GlJournalRef);

      return Results.Ok(r);
    })
    .RequireAuthorization(
      "Finance.WriteGifts")
    .WithName("PostGiftBatch")
    .WithOpenApi();
  }
}

8.3 Typed DataSet → EF Core 10 Entity with Atomic Sequence (Example 2)

Petra's legacy data layer is generated from db/petra.xml into typed DataSets — e.g. AGiftBatchTable with strongly-typed columns and a hand-rolled accessor (AGiftBatchAccess). Modernization replaces both with one EF Core entity. The atomic increment behavior of BR-GIFT-001 survives the rewrite: legacy code did ++ALedgerTbl[0].LastGiftBatchNumber inside a serializable transaction; the modern code uses an EF Core concurrency token plus a row-level lock.

// csharp/ICT/Petra/Server/lib/MFinance/
//   Gift/Gift.Batch.cs:111

ALedgerTable ALedgerTbl =
    ALedgerAccess.LoadByPrimaryKey(
        ALedgerNumber, Tx);

if (ALedgerTbl.Rows.Count == 0)
    throw new EFinanceException(
        "Ledger not found");

// Atomic ++ on the row in memory;
// safety relies on the SQL
// transaction's row lock.
Int32 newBatchNumber =
    ++ALedgerTbl[0]
        .LastGiftBatchNumber;

AGiftBatchRow newBatch =
    NewGiftBatchTbl.NewRowTyped();

newBatch.LedgerNumber = ALedgerNumber;
newBatch.BatchNumber  = newBatchNumber;
newBatch.BatchStatus  = "Unposted";
newBatch.GlEffectiveDate =
    ADateEffective;

NewGiftBatchTbl.Rows.Add(newBatch);

ALedgerAccess.SubmitChanges(
    ALedgerTbl, Tx, AVerifications);
AGiftBatchAccess.SubmitChanges(
    NewGiftBatchTbl, Tx, AVerifications);

// src/Petra.GiftProcessing/Domain/
//   GiftBatch.cs + Ledger.cs

public class Ledger
{
    public int Id { get; set; }
    public int LastGiftBatchNumber
        { get; private set; }

    [ConcurrencyCheck]
    public uint Xmin { get; private set; }

    public int AssignNextBatchNumber()
    {
        // BR-GIFT-001: monotonic, per-ledger.
        // EF Core writes the new value
        // back with WHERE xmin = @oldXmin;
        // PostgreSQL rejects concurrent
        // writers via OCC.
        return ++LastGiftBatchNumber;
    }
}

// Application service usage
await using var tx = await db.Database
    .BeginTransactionAsync(
        IsolationLevel.Serializable, ct);

var ledger = await db.Ledgers
    .SingleAsync(l => l.Id == ledgerId, ct);

var number = ledger
    .AssignNextBatchNumber();

var batch = new GiftBatch
{
    LedgerId       = ledgerId,
    BatchNumber    = number,
    BatchStatus    = BatchStatus.Unposted,
    GlEffectiveDate = effectiveDate
};

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

8.4 Static Utility → Injectable Validator (Example 3)

Petra's legacy code uses static-utility classes pervasively — TFinancialYear.GetLedgerDatePostingPeriod is a representative case. The static design makes the helper untestable in isolation and forces every caller to depend on TDBTransaction being threaded through. The modernized version turns it into a DI-registered service backed by FluentValidation for the input rule (BR-GIFT-002: effective date must fall in an open accounting period).

// csharp/ICT/Petra/Server/lib/
//   MFinance/Common/Common.FinancialYear.cs

public static class TFinancialYear
{
  public static bool
    GetLedgerDatePostingPeriod(
      Int32 ALedgerNumber,
      ref DateTime ADateEffective,
      out Int32 ABatchYear,
      out Int32 ABatchPeriod,
      bool AForceEffectiveDateToFit,
      TDBTransaction ATransaction,
      bool AShowErrorMessages)
  {
    ABatchYear   = -1;
    ABatchPeriod = -1;

    var periods = AAccountingPeriodAccess
      .LoadViaALedger(
        ALedgerNumber, ATransaction);

    foreach (AAccountingPeriodRow p
        in periods.Rows)
    {
      if (ADateEffective >=
            p.PeriodStartDate &&
          ADateEffective <=
            p.PeriodEndDate)
      {
        ABatchYear   = p.AccountingYear;
        ABatchPeriod = p.AccountingPeriod;
        return true;
      }
    }

    if (AForceEffectiveDateToFit)
    {
      // … clamp to nearest boundary
      return true;
    }

    return false;
  }
}

// src/Petra.GiftProcessing/Domain/
//   Validation/FinancialPeriodValidator.cs

public interface IFinancialPeriodValidator
{
  Task<PeriodResolution> ResolveAsync(
    int ledgerId, DateOnly effectiveDate,
    bool forceFit, CancellationToken ct);
}

public sealed record PeriodResolution(
  int Year, int Period, DateOnly FittedDate);

public class FinancialPeriodValidator
    : IFinancialPeriodValidator
{
  private readonly GiftDbContext _db;
  private readonly ILogger _log;

  public FinancialPeriodValidator(
    GiftDbContext db,
    ILogger<FinancialPeriodValidator> log)
  { _db = db; _log = log; }

  public async Task<PeriodResolution>
    ResolveAsync(int ledgerId,
      DateOnly date, bool forceFit,
      CancellationToken ct)
  {
    var p = await _db.AccountingPeriods
      .AsNoTracking()
      .Where(x => x.LedgerId == ledgerId)
      .Where(x => date >= x.PeriodStart
        && date <= x.PeriodEnd)
      .SingleOrDefaultAsync(ct);

    if (p is not null)
      return new(p.AccountingYear,
        p.AccountingPeriod, date);

    if (!forceFit)
      throw new PeriodOutOfRangeException(
        ledgerId, date);

    // … nearest-boundary fit
  }
}

// FluentValidation rule on the request DTO:
public class CreateBatchValidator
    : AbstractValidator<CreateBatchCommand>
{
  public CreateBatchValidator(
    IFinancialPeriodValidator periods)
  {
    RuleFor(c => c.EffectiveDate)
      .NotEmpty()
      .MustAsync(async (c, d, _) =>
      {
        try { await periods.ResolveAsync(
            c.LedgerId, d, c.ForceFit, _);
          return true; }
        catch (PeriodOutOfRangeException)
          { return false; }
      })
      .WithMessage(
        "Effective date is outside any " +
        "open accounting period.");
  }
}

8.5 Static Math.Max/Min Clamp → Domain Method (Example 4)

TaxDeductibility.UpdateTaxDeductibiltyAmounts is the focal point of BR-GIFT-009 (Tax Deductible Percentage Bounds) and BR-GIFT-010 (Tax Deductibility Compliance Calculation). The legacy code is a static helper that mutates a ref AGiftDetailRow; the modernized version is a domain method on the GiftDetail aggregate, with the input clamp expressed as a FluentValidation rule co-located with the entity.

// csharp/ICT/Petra/Shared/lib/MFinance/
//   TaxDeductibility.cs:50

public static class TaxDeductibility
{
  public static void
    UpdateTaxDeductibiltyAmounts(
      ref AGiftDetailRow AGiftDetail)
  {
    if (AGiftDetail.IsTaxDeductiblePctNull())
      AGiftDetail.TaxDeductiblePct = 0.0m;

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

    decimal pct =
      AGiftDetail.TaxDeductiblePct / 100m;

    AGiftDetail.TaxDeductibleAmount =
      AGiftDetail.GiftAmount * pct;
    AGiftDetail.NonDeductibleAmount =
      AGiftDetail.GiftAmount * (1m - pct);

    AGiftDetail.TaxDeductibleAmountBase =
      AGiftDetail.GiftAmountBase * pct;
    AGiftDetail.NonDeductibleAmountBase =
      AGiftDetail.GiftAmountBase * (1m - pct);

    AGiftDetail.TaxDeductibleAmountIntl =
      AGiftDetail.GiftAmountIntl * pct;
    AGiftDetail.NonDeductibleAmountIntl =
      AGiftDetail.GiftAmountIntl * (1m - pct);
  }
}

// src/Petra.GiftProcessing/Domain/
//   GiftDetail.cs

public class GiftDetail
{
  public decimal GiftAmount { get; set; }
  public decimal GiftAmountBase { get; set; }
  public decimal GiftAmountIntl { get; set; }
  public decimal TaxDeductiblePct
    { get; private set; }
  public decimal TaxDeductibleAmount
    { get; private set; }
  public decimal NonDeductibleAmount
    { get; private set; }
  public decimal TaxDeductibleAmountBase
    { get; private set; }
  public decimal NonDeductibleAmountBase
    { get; private set; }
  public decimal TaxDeductibleAmountIntl
    { get; private set; }
  public decimal NonDeductibleAmountIntl
    { get; private set; }

  // BR-GIFT-009 + BR-GIFT-010
  public void ApplyTaxDeductiblePct(
    decimal pct)
  {
    // Clamp 0..100 (legacy parity)
    var p = Math.Max(0m, Math.Min(100m, pct));
    TaxDeductiblePct = p;
    var f = p / 100m;

    TaxDeductibleAmount =
      decimal.Round(GiftAmount * f, 2);
    NonDeductibleAmount =
      GiftAmount - TaxDeductibleAmount;

    TaxDeductibleAmountBase =
      decimal.Round(GiftAmountBase * f, 2);
    NonDeductibleAmountBase =
      GiftAmountBase - TaxDeductibleAmountBase;

    TaxDeductibleAmountIntl =
      decimal.Round(GiftAmountIntl * f, 2);
    NonDeductibleAmountIntl =
      GiftAmountIntl - TaxDeductibleAmountIntl;
  }
}

// Co-located FluentValidation rule
// (input check; clamp still defensive)
public class GiftDetailValidator
    : AbstractValidator<GiftDetailDto>
{
  public GiftDetailValidator()
  {
    RuleFor(d => d.TaxDeductiblePct)
      .InclusiveBetween(0m, 100m)
      .WithMessage(
        "Tax deductible percentage " +
        "must be between 0 and 100.");
  }
}

8.6 Switch-Case String Constants → Strongly-Typed Switch Expression (Example 5)

TGuiTools.GetMotivationGroupAndDetailForPartner drives BR-GIFT-011 (Motivation Detail Assignment by Partner Class). The legacy implementation is a string-on-string switch tracing p_partner.p_partner_class_c + p_unit.u_unit_type_code_c through hardcoded constants in MPartnerConstants + MFinanceConstants. The modernized version becomes a switch expression on strongly-typed enums returning a typed record.

// csharp/ICT/Petra/Server/lib/MFinance/
//   Gift/Gift.gui.tools.cs:105-173

public static void
  GetMotivationGroupAndDetailForPartner(
    Int64 APartnerKey,
    ref string AMotivationGroup,
    ref string AMotivationDetail,
    TDBTransaction ATransaction)
{
  var pTable = PPartnerAccess
    .LoadByPrimaryKey(APartnerKey,
      ATransaction);
  if (pTable.Rows.Count == 0) return;

  var partnerClass =
    ((PPartnerRow)pTable.Rows[0])
      .PartnerClass;

  if (partnerClass !=
      MPartnerConstants.PARTNERCLASS_UNIT)
    return;

  // try the linked-detail lookup first
  var linked = AMotivationDetailAccess
    .LoadViaPPartner(APartnerKey,
      ATransaction);
  if (linked.Rows.Count > 0)
  {
    var r = (AMotivationDetailRow)
      linked.Rows[0];
    if (r.MotivationStatus)
    {
      AMotivationGroup  =
        r.MotivationGroupCode;
      AMotivationDetail =
        r.MotivationDetailCode;
      return;
    }
  }

  var unit = PUnitAccess
    .LoadByPrimaryKey(APartnerKey,
      ATransaction);
  string ut = ((PUnitRow)unit.Rows[0])
    .UnitTypeCode;

  if (ut == MPartnerConstants
        .UNIT_TYPE_AREA ||
      ut == MPartnerConstants
        .UNIT_TYPE_FUND ||
      ut == MPartnerConstants
        .UNIT_TYPE_FIELD)
  {
    AMotivationDetail =
      MFinanceConstants
        .GROUP_DETAIL_FIELD;
  }
  else if (ut == MPartnerConstants
        .UNIT_TYPE_KEYMIN)
  {
    AMotivationDetail =
      MFinanceConstants
        .GROUP_DETAIL_KEY_MIN;
  }
  else
  {
    AMotivationDetail =
      MFinanceConstants
        .GROUP_DETAIL_SUPPORT;
  }
}

// src/Petra.GiftProcessing/Domain/
//   Motivation/MotivationResolver.cs

public enum PartnerClass
{ Person, Family, Organisation,
  Unit, Bank, Church, Venue }

public enum UnitType
{ Area, Fund, Field, KeyMin, Country,
  Conference, Team, WorkingGroup,
  Other, Root }

public sealed record MotivationAssignment(
  string Group, string Detail);

public interface IMotivationResolver
{
  Task<MotivationAssignment?> ResolveAsync(
    long partnerKey, CancellationToken ct);
}

public class MotivationResolver
    : IMotivationResolver
{
  private readonly GiftDbContext _db;

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

  public async Task<MotivationAssignment?>
    ResolveAsync(long partnerKey,
      CancellationToken ct)
  {
    var partner = await _db.Partners
      .AsNoTracking()
      .SingleOrDefaultAsync(
        p => p.PartnerKey == partnerKey,
        ct);
    if (partner is null) return null;

    if (partner.PartnerClass !=
        PartnerClass.Unit)
      return null; // caller-default preserved

    // Linked-detail wins if active.
    var linked = await _db.MotivationDetails
      .AsNoTracking()
      .Where(m =>
        m.LinkedPartnerKey == partnerKey
        && m.MotivationStatus)
      .FirstOrDefaultAsync(ct);
    if (linked is not null)
      return new(linked.MotivationGroupCode,
        linked.MotivationDetailCode);

    var unit = await _db.Units
      .AsNoTracking()
      .SingleAsync(
        u => u.PartnerKey == partnerKey, ct);

    return unit.UnitType switch
    {
      UnitType.Area
        or UnitType.Fund
        or UnitType.Field
          => new("GIFT", "FIELD"),
      UnitType.KeyMin
          => new("GIFT", "KEYMIN"),
      _   => new("GIFT", "SUPPORT"),
    };
  }
}

8.7 Concatenated SQL → LINQ Specification (Example 6)

The receipt-eligibility query is the single most-cited SQL in the subsystem — csharp/ICT/Petra/Server/sql/Gift.ReceiptPrinting.GetDonationsOfDonor.sql encodes BR-GIFT-004 (dual-flag receipt eligibility), BR-GIFT-007 (posted only), BR-GIFT-008 (unmodified detail filter), and BR-GIFT-006 (confidential-gift dual partner alias) in one 60-line statement. The modernized version expresses each rule as a separate LINQ specification, so each can be unit-tested independently.

-- Gift.ReceiptPrinting
--   .GetDonationsOfDonor.sql

SELECT
  g.a_ledger_number_i,
  g.a_batch_number_i,
  g.a_gift_transaction_number_i,
  d.a_detail_number_i,
  d.a_gift_amount_n,
  d.a_gift_amount_intl_n,
  d.a_tax_deductible_pct_n,
  destn.p_partner_short_name_c
    AS gift_destination_name,
  rcp.p_partner_short_name_c
    AS recipient_name
FROM a_gift_batch b
INNER JOIN a_gift g
  ON g.a_ledger_number_i =
       b.a_ledger_number_i
 AND g.a_batch_number_i =
       b.a_batch_number_i
INNER JOIN a_gift_detail d
  ON d.a_ledger_number_i =
       g.a_ledger_number_i
 AND d.a_batch_number_i =
       g.a_batch_number_i
 AND d.a_gift_transaction_number_i =
       g.a_gift_transaction_number_i
INNER JOIN a_motivation_detail m
  ON m.a_ledger_number_i =
       d.a_ledger_number_i
 AND m.a_motivation_group_code_c =
       d.a_motivation_group_code_c
 AND m.a_motivation_detail_code_c =
       d.a_motivation_detail_code_c
INNER JOIN p_partner destn
  ON destn.p_partner_key_n =
       d.a_recipient_ledger_number_n
INNER JOIN p_partner rcp
  ON rcp.p_partner_key_n =
       d.p_recipient_key_n
WHERE b.a_batch_status_c = 'Posted'
  AND g.a_print_receipt_l = TRUE
  AND m.a_receipt_l = TRUE
  AND d.a_modified_detail_l = FALSE
  AND g.p_donor_key_n = {ADonorKey}
  AND g.a_date_entered_d BETWEEN
    '{ADateFrom}' AND '{ADateTo}'
ORDER BY g.a_date_entered_d ASC,
         d.a_detail_number_i DESC;

// src/Petra.GiftProcessing/Domain/
//   Specifications/GiftDetailSpecs.cs

public static class GiftDetailSpecs
{
  // BR-GIFT-007
  public static IQueryable<GiftDetail> Posted(
    this IQueryable<GiftDetail> q)
    => q.Where(d =>
      d.Gift.Batch.BatchStatus
        == BatchStatus.Posted);

  // BR-GIFT-008
  public static IQueryable<GiftDetail>
    Unmodified(this IQueryable<GiftDetail> q)
    => q.Where(d => !d.ModifiedDetail);

  // BR-GIFT-004 (dual flag)
  public static IQueryable<GiftDetail>
    ReceiptEligible(
      this IQueryable<GiftDetail> q)
    => q.Where(d =>
        d.Gift.PrintReceipt
        && d.MotivationDetail.ReceiptL);

  public static IQueryable<GiftDetail>
    ForDonor(this IQueryable<GiftDetail> q,
      long donorKey)
    => q.Where(d =>
      d.Gift.DonorKey == donorKey);

  public static IQueryable<GiftDetail>
    EnteredBetween(
      this IQueryable<GiftDetail> q,
      DateOnly from, DateOnly to)
    => q.Where(d =>
      d.Gift.DateEntered >= from
      && d.Gift.DateEntered <= to);
}

// Usage in the receipt service
var q = _db.GiftDetails.AsNoTracking()
  .Posted()           // BR-GIFT-007
  .Unmodified()       // BR-GIFT-008
  .ReceiptEligible()  // BR-GIFT-004
  .ForDonor(donorKey)
  .EnteredBetween(from, to)
  .Include(d => d.GiftDestination)
  .Include(d => d.Recipient) // BR-GIFT-006
  .OrderBy(d => d.Gift.DateEntered)
  .ThenByDescending(d => d.DetailNumber);

// BR-GIFT-006: authorization filter
// applied at the projection step
var dtos = await q
  .Select(d => new GiftDetailDto(
    d.Id, d.GiftAmount,
    d.GiftAmountIntl,
    d.TaxDeductiblePct,
    d.GiftDestination.ShortName,
    user.CanSeeConfidential
      || !d.Gift.ConfidentialGiftFlag
        ? d.Recipient.ShortName
        : "[Confidential]"))
  .ToListAsync(ct);

8.8 Hand-Rolled HttpWebRequest → Polly Resilience Pipeline (Example 7)

The strangler-fig bridge calls out to the legacy GL service (one-way posting) and the legacy Partner service (read-only validation) over REST. Legacy code wraps these calls in HttpWebRequest with hand-rolled try/catch and no retry; the modernized code uses HttpClient registered with a Polly resilience pipeline (retry + circuit breaker + timeout) and OpenTelemetry HTTP-client instrumentation.

// csharp/ICT/Petra/Server/lib/
//   MFinance/GL/Gl.PostBatch.cs (sketch)

public static bool PostBatchToLegacyGL(
    Int32 ALedgerNumber,
    Int32 ABatchNumber,
    string APayload)
{
  try
  {
    var req = (HttpWebRequest)
      WebRequest.Create(
        TAppSettingsManager.GetValue(
          "Server.LegacyGlUrl"));

    req.Method = "POST";
    req.ContentType =
      "application/x-www-form-urlencoded";
    req.Timeout = 30000;

    using (var s = req.GetRequestStream())
    {
      var bytes = Encoding.UTF8
        .GetBytes(APayload);
      s.Write(bytes, 0, bytes.Length);
    }

    using (var resp = (HttpWebResponse)
      req.GetResponse())
    {
      return resp.StatusCode ==
        HttpStatusCode.OK;
    }
  }
  catch (WebException ex)
  {
    TLogging.Log(
      "GL POST failed: " + ex.Message);
    return false;
  }
  catch (Exception ex)
  {
    TLogging.Log(
      "GL POST unexpected: " + ex.Message);
    return false;
  }
}

// src/Petra.GiftProcessing/Program.cs
// HttpClient registration with Polly v8

builder.Services
  .AddHttpClient<ILegacyGlClient,
    LegacyGlClient>(c =>
  {
    c.BaseAddress = new Uri(
      builder.Configuration[
        "LegacyGl:BaseUrl"]!);
    c.Timeout = TimeSpan.FromSeconds(15);
  })
  .AddStandardResilienceHandler(o =>
  {
    o.Retry.MaxRetryAttempts   = 3;
    o.Retry.BackoffType         =
      DelayBackoffType.Exponential;
    o.Retry.UseJitter           = true;
    o.CircuitBreaker
      .FailureRatio = 0.5;
    o.CircuitBreaker
      .SamplingDuration =
        TimeSpan.FromSeconds(30);
    o.AttemptTimeout.Timeout =
      TimeSpan.FromSeconds(10);
  });

// src/Petra.GiftProcessing/Bridges/
//   LegacyGlClient.cs

public class LegacyGlClient : ILegacyGlClient
{
  private readonly HttpClient _http;
  private readonly ILogger _log;
  private static readonly ActivitySource
    _act = new("Petra.LegacyGl");

  public LegacyGlClient(
    HttpClient http,
    ILogger<LegacyGlClient> log)
  { _http = http; _log = log; }

  public async Task<GlPostingResult>
    PostBatchAsync(
      GlPostingPayload payload,
      CancellationToken ct)
  {
    using var span = _act.StartActivity(
      "legacy_gl.post_batch");
    span?.SetTag("ledger_id",
      payload.LedgerId);
    span?.SetTag("batch_id",
      payload.BatchId);

    try
    {
      var resp = await _http
        .PostAsJsonAsync(
          "/api/legacy/gl/post",
          payload, ct);

      resp.EnsureSuccessStatusCode();

      var r = await resp.Content
        .ReadFromJsonAsync<
          GlPostingResult>(
            cancellationToken: ct);

      _log.LogInformation(
        "legacy_gl.posted {LedgerId} " +
        "{BatchId} {JournalRef}",
        payload.LedgerId,
        payload.BatchId,
        r!.JournalRef);

      return r;
    }
    catch (Exception ex)
    {
      span?.SetStatus(
        ActivityStatusCode.Error,
        ex.Message);
      throw new LegacyGlPostingException(
        payload.LedgerId,
        payload.BatchId, ex);
    }
  }
}

8.9 Error Handling: SOAP Fault → RFC 7807 Problem Details

The legacy SOAP layer caught EFinanceException at the boundary and serialized it as a SOAP fault with an arbitrary string. The modernized error pipeline turns domain exceptions into RFC 7807 Problem-Details JSON documents, with a stable type URI, a typed status code, and an Application-Insights-queryable correlation ID.

// Domain exception (BR-GIFT-002 violation)
public sealed class PeriodOutOfRangeException
    : Exception
{
  public int LedgerId { get; }
  public DateOnly EffectiveDate { get; }

  public PeriodOutOfRangeException(
    int ledgerId, DateOnly date)
    : base($"Date {date} is outside any " +
           $"open period for ledger " +
           $"{ledgerId}.")
  { LedgerId = ledgerId;
    EffectiveDate = date; }
}

// Program.cs: ProblemDetails registration
builder.Services
  .AddProblemDetails(o =>
  {
    o.CustomizeProblemDetails = ctx =>
    {
      var act = Activity.Current;
      ctx.ProblemDetails.Extensions[
        "traceId"] = act?.TraceId.ToString();
    };
  });

builder.Services
  .AddExceptionHandler<GiftExceptionHandler>();

// GiftExceptionHandler.cs
public class GiftExceptionHandler
    : IExceptionHandler
{
  public async ValueTask<bool>
    TryHandleAsync(HttpContext ctx,
      Exception ex, CancellationToken ct)
  {
    var pd = ex switch
    {
      PeriodOutOfRangeException p =>
        new ProblemDetails
        {
          Type = "https://petra.openpetra" +
            ".org/problems/period-out-of-" +
            "range",
          Title = "Effective date outside " +
            "open period",
          Status =
            StatusCodes.Status422Unprocessable
            Entity,
          Detail = p.Message
        },
      LegacyGlPostingException g =>
        new ProblemDetails
        {
          Type = "https://petra.openpetra" +
            ".org/problems/legacy-gl-down",
          Title = "Legacy GL service " +
            "unavailable",
          Status =
            StatusCodes.Status502BadGateway,
          Detail = g.Message
        },
      _ => (ProblemDetails?)null
    };

    if (pd is null) return false;

    ctx.Response.StatusCode =
      pd.Status ?? 500;
    await ctx.Response.WriteAsJsonAsync(
      pd, ct);
    return true;
  }
}

8.10 Summary

Same language. Different shape. The seven translation examples above describe the entire transformation: SOAP boundary becomes Minimal-API endpoint, typed DataSets become EF Core 10 entities, static utilities become DI services, hand-rolled SQL becomes LINQ specifications, untyped string-status filters become typed enums, raw HttpWebRequest becomes HttpClient + Polly, ad-hoc exceptions become RFC 7807 documents. Every business rule from the Section 9 catalog has at least one translation example anchoring it (BR-GIFT-001 in 8.3, BR-GIFT-002 in 8.4 + 8.9, BR-GIFT-003 in 8.5, BR-GIFT-004/006/007/008 in 8.7, BR-GIFT-007 in 8.2 + 8.8, BR-GIFT-009/010 in 8.5, BR-GIFT-011 in 8.6). The schemas these examples write to are detailed in Section 10; the runtime that hosts them is detailed in Appendix C.

9. Business Rules Analysis

This section documents the behavioral rules extracted from the Petra Finance — Gift Processing subsystem (279 files, 23-cycle Concho analysis), showing C# legacy source implementation alongside C# .NET 10 translations with formal Given-When-Then specifications. All 14 rules were discovered through Concho's Context Graph analysis and verified against source code; 5 are additionally corroborated by surviving OpenPetra NUnit test files (`csharp/ICT/Testing/lib/MFinance/server/Gift/*.test.cs`). A companion subsection — Section 9.8: Field-Level Business Rules — extends this catalog with per-field validation and formatting rules auto-derived from the UI field inventory; those field-level rules feed directly into Playwright test generation for the artifact workflow.

9.1 Business Rules Overview

Concho's codebase intelligence identified 14 behavioral rules governing the Finance — Gift Processing subsystem across 10 verified source files. These rules span five categories: validation (4 rules), calculation (3), state transition (2), workflow (3), and authorization (2). Confidence scores range from 0.70 to 0.95, with 9 rules at or above the 0.75 high-confidence threshold; the remaining 5 (confidence 0.70) are included because they represent important gift-processing behaviors verified directly against source. Project-level context: the Concho cycle-23 context graph catalogs 215 business rules across the full Petra codebase, of which these 14 are the subset tied to the Gift Processing bounded context.

Since the legacy and target platforms share the same language (C#), the majority of rules transfer with minimal behavioral change. The primary modernization impact is architectural: static utility classes become injectable services, typed datasets become EF Core entities, raw SQL becomes parameterized LINQ queries, runtime ALTER TABLE upgrades become EF Core migrations, and XML report templates become a typed .NET reporting service. One rule (BR-GIFT-002, period validation) is a deliberate improvement — the modern workspace warns live instead of silently force-fitting the date — and one rule (BR-GIFT-006) requires explicit mitigation because confidentiality was previously an emergent property of the SQL query layer.

Rule Distribution by Category

Rule Discovery Methodology

Rules were discovered through Concho's Context Graph, which analyzes code structure, control flow, data dependencies, and naming conventions to identify business-significant logic patterns. Concho provided rule descriptions, confidence scores, evidence classifications (all 14 are STRUCTURAL), and source-file references with line numbers. The workflow then assigned BR-GIFT-NNN identifiers, derived formal Given-When-Then specifications from Concho's descriptions, and verified each cited source file and code snippet via Concho's get_file_content_in_range API.

Seven rules originated as business_rule entities and seven as implementation_constraint entities in Concho's domain model. Both categories encode enforceable behavioral contracts that must be preserved during modernization, so they are treated uniformly in this analysis. After source verification, the workflow ran legacy-test discovery against the OpenPetra `Testing/lib/MFinance/server/Gift/` directory and found 7 surviving NUnit test files; 5 of the 14 rules carry test corroboration as a result, and those rules have their GWT badged accordingly.

GWT Origin Distribution

Of the 14 rules, 5 are code-inferred-test-corroborated (badged orange below) — the code-inferred GWT was within the ≥0.85 agreement threshold of the test-derived GWT, so the two sources are recorded as agreeing. The remaining 9 are code-inferred (badged grey) because no surviving test exercises the rule directly. No rule landed in legacy-test-derived (which would require a 0.5–0.85 agreement band) or conflict-halt (which would block emission). One nuance worth calling out: for a non-UNIT partner the rule leaves the operator's motivation unchanged — and in the source that behavior is the *absence* of an action (a fall-through that writes nothing), which reads ambiguously on its own. The surviving legacy test states the intent explicitly, asserting the unchanged outcome directly, so BR-GIFT-011 is sharpened to exactly the behavior the original developers pinned down. That is the value of reading the legacy tests alongside the code: they record the original team's intent on the edge and do-nothing cases that source alone leaves implicit.

9.2 Validation Rules

BR-GIFT-001: Gift Batch Sequential Numbering

NewRow = AMainDS.AGiftBatch
    .NewRowTyped(true);

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

Int32 BatchYear, BatchPeriod;
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;

public async Task<GiftBatch> CreateBatchAsync(
    int ledgerNumber,
    DateTime dateEffective,
    bool forceEffectiveDateToFit,
    CancellationToken ct = default)
{
    await using var tx = await
        _db.Database.BeginTransactionAsync(ct);

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

    // Atomic increment — same sequential
    // numbering as legacy ++LastGiftBatchNumber
    ledger.LastGiftBatchNumber++;

    var (year, period) = await _periodValidator
        .GetPostingPeriodAsync(
            ledgerNumber, dateEffective,
            forceEffectiveDateToFit, ct);

    var batch = new GiftBatch
    {
        LedgerNumber = ledgerNumber,
        BatchNumber = ledger.LastGiftBatchNumber,
        BatchYear = year,
        BatchPeriod = period,
        GlEffectiveDate = dateEffective,
        ExchangeRateToBase = 1.0m,
        CurrencyCode = ledger.BaseCurrency
    };

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

    return batch;
}

BR-GIFT-002: Gift Batch Financial Period Validation

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;

public interface IFinancialPeriodValidator
{
    Task<(int year, int period)> GetPostingPeriodAsync(
        int ledgerNumber,
        DateTime dateEffective,
        bool forceEffectiveDateToFit,
        CancellationToken ct);
}

// Service impl uses EF Core query over
// a_accounting_period rows for the ledger
var period = await _db.AccountingPeriods
    .Where(p => p.LedgerNumber == ledgerNumber
        && p.PeriodStartDate <= dateEffective
        && p.PeriodEndDate   >= dateEffective)
    .SingleOrDefaultAsync(ct);

if (period is null && forceEffectiveDateToFit)
{
    period = await _db.AccountingPeriods
        .Where(p => p.LedgerNumber == ledgerNumber)
        .OrderBy(p => Math.Abs(
            (p.PeriodStartDate - dateEffective)
                .TotalDays))
        .FirstAsync(ct);
}
return (period.YearNumber, period.PeriodNumber);

BR-GIFT-009: Tax Deductible Percentage Bounds

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 void UpdateTaxDeductibilityAmounts(
    GiftDetail detail)
{
    // Clamp percentage to [0, 100]
    detail.TaxDeductiblePct = Math.Clamp(
        detail.TaxDeductiblePct ?? 0m, 0m, 100m);

    var (deduct, nonDeduct) =
        CalculateAmounts(
            detail.GiftTransactionAmount,
            detail.TaxDeductiblePct.Value);

    if (detail.TaxDeductibleAmount != deduct
        || detail.NonDeductibleAmount != nonDeduct)
    {
        detail.TaxDeductibleAmount    = deduct;
        detail.NonDeductibleAmount    = nonDeduct;
    }

    // Repeat for base and intl currency amounts
    UpdateBaseAmounts(detail);
    UpdateIntlAmounts(detail);
}

BR-GIFT-014: Barcode Character Validation for Receipts

foreach (char c in AText)
{
    if (((c < 32) || (c > 126))
        && (c != 203))
    {
        // invalid character
        return "";
    }
}

bool tableB = true;
int ind = 0;
int length = AText.Length;
int checksum = 0;
// ... checksum computation follows ...

public sealed class BarcodeEncoderService
    : IBarcodeEncoder
{
    public string EncodeCode128(string text)
    {
        if (string.IsNullOrEmpty(text))
            return string.Empty;

        // Same ASCII range check as legacy:
        // 32..126 OR 203
        foreach (char c in text)
        {
            if ((c < 32 || c > 126) && c != 203)
                return string.Empty;
        }

        return ComputeChecksumAndEncode(text);
    }
}

9.3 Calculation Rules

BR-GIFT-003: Multi-Currency Gift Processing

-- Three-currency amount projection
SELECT
  a_gift_transaction_amount_n  AS TxAmount,
  a_gift_amount_n              AS BaseAmount,
  a_gift_amount_intl_n         AS IntlAmount,
  a_tax_deductible_amount_n,
  a_tax_deductible_amount_base_n,
  a_non_deductible_amount_n,
  a_non_deductible_amount_base_n,
  a_gift_batch.a_currency_code_c AS Currency
FROM a_gift_batch,
     a_gift,
     a_gift_detail,
     a_motivation_detail
WHERE GiftDetail.a_ledger_number_i = ?
  AND a_gift_batch.a_batch_status_c
      = 'Posted'
GROUP BY a_recipient_key_n,
         a_currency_code_c

// Entity preserves three currency amounts
public class GiftDetail
{
    public decimal GiftTransactionAmount { get; set; }
    public decimal GiftAmount            { get; set; } // base
    public decimal GiftAmountIntl        { get; set; }
    public decimal TaxDeductibleAmount   { get; set; }
    public decimal TaxDeductibleAmountBase { get; set; }
    public decimal NonDeductibleAmount   { get; set; }
    public decimal NonDeductibleAmountBase { get; set; }
}

// LINQ aggregation by recipient + currency
var hosaTotals = _db.GiftDetails
    .Include(d => d.GiftBatch)
    .Where(d => d.GiftBatch.LedgerNumber == ledgerId
        && d.GiftBatch.BatchStatus == BatchStatus.Posted)
    .GroupBy(d => new {
        d.RecipientKey,
        d.GiftBatch.CurrencyCode })
    .Select(g => new HosaSummary
    {
        RecipientKey = g.Key.RecipientKey,
        Currency     = g.Key.CurrencyCode,
        TotalTransaction = g.Sum(d =>
            d.GiftTransactionAmount),
        TotalBase    = g.Sum(d => d.GiftAmount),
        TotalIntl    = g.Sum(d => d.GiftAmountIntl)
    });

BR-GIFT-010: Tax Deductibility Compliance Calculation

[RequireModulePermission("FINANCE-1")]
public static bool GetGiftsForTaxDeductiblePct
    Adjustment(ref GiftBatchTDS AGiftDS,
        Int64 ARecipientKey,
        DateTime ADateFrom,
        decimal ANewPct,
        out TVerificationResultCollection AMessages)
{
    db.ReadTransaction( ref Transaction,
        delegate
        {
            string Query = "SELECT a_gift_detail.*"
              + " FROM a_gift_detail, a_gift_batch"
              + " WHERE p_recipient_key_n = "
              + ARecipientKey
              + " AND a_tax_deductible_pct_n <> "
              + ANewPct
              + " AND a_modified_detail_l <> true"
              + " AND a_tax_deductible_l = true"
              + " AND a_batch_status_c = 'Posted'"
              + " AND a_gl_effective_date_d >= '"
              + ADateFrom.ToString("yyyy-MM-dd")
              + "'";
            db.Select(MainDS, Query,
                MainDS.AGiftDetail.TableName,
                Transaction);
            foreach (Row in MainDS.AGiftDetail.Rows)
            {
                Row.TaxDeductiblePct = ANewPct;
                TaxDeductibility
                    .UpdateTaxDeductibiltyAmounts(
                        ref Row);
            }
            AGiftDetailAccess.SubmitChanges(
                Table, Transaction);
        });
}

[Authorize(Policy = "Finance.WriteGifts")]
public async Task<AdjustmentResult>
    AdjustTaxDeductiblePctAsync(
        long recipientKey,
        DateTime dateFrom,
        decimal newPct,
        CancellationToken ct = default)
{
    await using var tx = await
        _db.Database.BeginTransactionAsync(ct);

    // Parameterized query (no SQL injection risk)
    var details = await _db.GiftDetails
        .Where(d =>
            d.RecipientKey == recipientKey
            && d.TaxDeductiblePct != newPct
            && !d.ModifiedDetail
            && d.TaxDeductible
            && d.GiftBatch.BatchStatus
                == BatchStatus.Posted
            && d.GiftBatch.GlEffectiveDate
                >= dateFrom)
        .ToListAsync(ct);

    foreach (var detail in details)
    {
        detail.TaxDeductiblePct = newPct;
        _taxService.UpdateTaxDeductibilityAmounts(
            detail);
    }

    await _db.SaveChangesAsync(ct);
    await tx.CommitAsync(ct);
    return new AdjustmentResult(details.Count);
}

BR-GIFT-011: Motivation Detail Assignment by Partner Class

// First check for linked motivation detail
AMotivationDetailTable MotivationDetailTable =
    AMotivationDetailAccess.LoadViaPPartner(
        APartnerKey, readTransaction);

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

if (!KeyMinFound)
{
    // Map UnitTypeCode to motivation detail
    PUnitTable pUnitTable =
        PUnitAccess.LoadByPrimaryKey(
            APartnerKey, readTransaction);

    switch (pUnitTable[0].UnitTypeCode)
    {
        case UNIT_TYPE_AREA:
        case UNIT_TYPE_FUND:
        case UNIT_TYPE_FIELD:
            motivationDetail =
                GROUP_DETAIL_FIELD;
            break;
        case UNIT_TYPE_KEYMIN:
            motivationDetail =
                GROUP_DETAIL_KEY_MIN;
            break;
        default:
            motivationDetail =
                GROUP_DETAIL_SUPPORT;
            break;
    }
}

public async Task<MotivationAssignment?>
    ResolveAsync(long partnerKey,
        CancellationToken ct = default)
{
    var partner = await _db.Partners
        .SingleOrDefaultAsync(
            p => p.PartnerKey == partnerKey, ct);

    if (partner is null) return null;

    if (partner.PartnerClass != "UNIT")
        // Non-UNIT: leave caller defaults
        // unchanged (test-corroborated)
        return MotivationAssignment.Unchanged;

    // Check for partner-linked motivation
    var linked = await _db.MotivationDetails
        .Where(m => m.PartnerKey == partnerKey
            && m.MotivationStatus)
        .FirstOrDefaultAsync(ct);

    if (linked is not null)
        return new MotivationAssignment(
            linked.GroupCode,
            linked.DetailCode);

    // Fall back to unit type mapping
    var unit = await _db.Units
        .SingleAsync(
            u => u.PartnerKey == partnerKey, ct);

    return unit.UnitTypeCode switch
    {
        "AREA" or "FUND" or "FIELD"
            => MotivationAssignment.Field,
        "KEYMIN"
            => MotivationAssignment.KeyMin,
        _ => MotivationAssignment.Support
    };
}

9.4 State Transition Rules

BR-GIFT-007: Gift Batch Posting Status Constraint

SELECT PUB_a_gift_detail.*
FROM PUB_a_gift_batch,
     PUB_a_gift,
     PUB_a_gift_detail
WHERE PUB_a_gift_batch.a_ledger_number_i = ?
  AND PUB_a_gift_batch.a_gl_effective_date_d
      >= ?
  AND PUB_a_gift_batch.a_gl_effective_date_d
      <= ?
  AND PUB_a_gift_batch.a_batch_status_c
      = 'Posted'
  AND PUB_a_gift.a_ledger_number_i
      = PUB_a_gift_batch.a_ledger_number_i
  AND PUB_a_gift.a_batch_number_i
      = PUB_a_gift_batch.a_batch_number_i
  AND PUB_a_gift_detail.a_ledger_number_i
      = PUB_a_gift_batch.a_ledger_number_i
  AND PUB_a_gift_detail.a_batch_number_i
      = PUB_a_gift_batch.a_batch_number_i
  AND PUB_a_gift_detail.
      a_gift_transaction_number_i
      = PUB_a_gift.a_gift_transaction_number_i
  AND PUB_a_gift_detail.a_modified_detail_l = 0
  AND p_recipient_key_n = ?
  AND a_recipient_ledger_number_n = ?

// Global query filter applied at model level
modelBuilder.Entity<GiftBatch>()
    .HasQueryFilter(b =>
        b.BatchStatus == BatchStatus.Posted);

// Caller can opt out with IgnoreQueryFilters()
// for admin scenarios that need draft batches.

public async Task<List<GiftDetail>>
    GetDetailsForAdjustmentAsync(
        int ledgerNumber,
        DateOnly from, DateOnly to,
        long recipientKey,
        long recipientLedgerNumber,
        CancellationToken ct = default)
{
    return await _db.GiftDetails
        .Include(d => d.Gift)
        .Include(d => d.GiftBatch)
        .Where(d =>
            d.GiftBatch.LedgerNumber == ledgerNumber
            && d.GiftBatch.GlEffectiveDate >= from
            && d.GiftBatch.GlEffectiveDate <= to
            && !d.ModifiedDetail
            && d.RecipientKey == recipientKey
            && d.RecipientLedgerNumber
                == recipientLedgerNumber)
        .ToListAsync(ct);
    // BatchStatus = Posted applied globally
}

BR-GIFT-008: Unmodified Detail Filter

-- Line 11: idempotency guard
AND PUB_a_gift_detail.a_modified_detail_l = 0

public class AdjustmentSpecification
    : Specification<GiftDetail>
{
    public override Expression<
        Func<GiftDetail, bool>>
        ToExpression() =>
        detail => !detail.ModifiedDetail;
}

// Usage:
.Where(new AdjustmentSpecification()
    .ToExpression())

// After adjustment, the flag is set
// to prevent re-processing:
detail.ModifiedDetail = true;

9.5 Workflow Rules

BR-GIFT-004: Donation Receipt Generation Workflow

-- Dual-flag eligibility: print + receipt
WHERE a_gift_batch.a_ledger_number_i    = ?
  AND a_gift_batch.a_batch_status_c     = 'Posted'
  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
ORDER BY a_gift.a_date_entered_d ASC,
    a_gift_detail.a_detail_number_i DESC

public class ReceiptEligibilitySpec
    : Specification<GiftDetail>
{
    public ReceiptEligibilitySpec(
        long donorKey,
        DateOnly from, DateOnly to)
    {
        AddCriteria(d =>
            d.Gift.DonorKey == donorKey
            && d.GiftBatch.GlEffectiveDate
                >= from
            && d.GiftBatch.GlEffectiveDate
                <= to
            && d.GiftBatch.BatchStatus
                == BatchStatus.Posted
            && d.Gift.PrintReceipt
            && d.MotivationDetail.Receipt
            && !d.ModifiedDetail);
        OrderBy(d => d.Gift.DateEntered);
        ThenByDescending(
            d => d.DetailNumber);
    }
}

// Razor template renders the receipt PDF
var details = await _db.GiftDetails
    .Specify(new ReceiptEligibilitySpec(
        donorKey, from, to))
    .ToListAsync(ct);
var html = await _razor.RenderAsync(
    "ReceiptTemplate", new ReceiptModel(donor, details));
var pdf = await _pdfRenderer.RenderAsync(html);

BR-GIFT-005: Recurring Donation Frequency Scheduling

// Schema upgrade: add SEPA columns at runtime
if (!ColumnExists)
{
    sql = "ALTER TABLE PUB_a_recurring_gift "
        + "ADD COLUMN a_sepa_mandate_reference_c "
        + "varchar(70) DEFAULT NULL "
        + "AFTER p_banking_details_key_i";
    ADataBase.ExecuteNonQuery(
        sql, SubmitChangesTransaction);

    sql = "ALTER TABLE PUB_a_recurring_gift "
        + "ADD COLUMN a_sepa_mandate_given_d "
        + "date DEFAULT NULL "
        + "AFTER a_sepa_mandate_reference_c";
    ADataBase.ExecuteNonQuery(
        sql, SubmitChangesTransaction);
}

// Per-donor scheduling config:
// p_partner.a_receipt_letter_frequency_c
//   ("Annual"/"Monthly"/...)
// p_partner.a_receipt_each_gift_l
//   (true/false)

// EF Core migration replaces runtime ALTER
public partial class AddSepaMandate : Migration
{
    protected override void Up(MigrationBuilder mb)
    {
        mb.AddColumn<string>(
            name: "SepaMandateReference",
            table: "RecurringGift",
            type: "varchar(70)",
            nullable: true);
        mb.AddColumn<DateOnly?>(
            name: "SepaMandateGiven",
            table: "RecurringGift",
            nullable: true);
    }
}

// Background scheduler emits SEPA mandate refs
public class RecurringGiftScheduler
    : BackgroundService
{
    protected override async Task ExecuteAsync(
        CancellationToken ct)
    {
        // ... process per-donor schedule,
        //     generate SEPA refs in YYYYMMDD
    }
}

BR-GIFT-006: Confidential Gift Privacy Handling [Mitigation needed]

-- Dual partner alias: destination + recipient
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
     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
-- (confidentiality is implicit:
--  callers must use the right alias
--  in their reports)

public class GiftDetail
{
    // Distinct navigation paths preserve
    // the legacy dual-alias intent
    public Partner GiftDestination { get; set; }
    public Partner Recipient       { get; set; }
    public bool    Confidential    { get; set; }
}

// Explicit authorization policy: required to
// view recipient details for confidential gifts
[Authorize(Policy = "Gifts.ViewConfidential")]
public async Task<GiftDetailDto>
    GetGiftDetailAsync(int id, ClaimsPrincipal user)
{
    var detail = await _db.GiftDetails
        .Include(d => d.GiftDestination)
        .Include(d => d.Recipient)
        .SingleAsync(d => d.Id == id, ct);

    // Redact recipient if confidential AND
    // caller lacks the policy:
    if (detail.Confidential &&
        !user.HasClaim("gifts.viewConfidential"))
    {
        return GiftDetailDto.WithRedactedRecipient(
            detail);
    }
    return GiftDetailDto.From(detail);
}

9.6 Authorization Rules

BR-GIFT-012: Posted-Batch Financial Integrity for Reports

<calculation id="GetGiftBatchCurrencies"
        returns="line_a_currency_code_c"
        returnsFormat="row">
    <query>
        <queryDetail><value>
        Select Distinct
            batch.a_currency_code_c
                as line_a_currency_code_c
        FROM PUB_a_gift_batch as batch
        WHERE batch.a_gl_effective_date_d
            BETWEEN {#param_start_date#}
            AND {#param_end_date#}
        AND batch.a_ledger_number_i
            = {{param_ledger_number_i}}
        AND batch.a_batch_status_c = 'Posted'
        ORDER BY batch.a_currency_code_c
        </value></queryDetail>
    </query>
</calculation>

// Typed report parameters replace XML tokens
public record MethodOfGivingParams(
    int LedgerNumber,
    DateOnly StartDate,
    DateOnly EndDate);

public async Task<MethodOfGivingReport>
    GenerateAsync(
        MethodOfGivingParams p,
        CancellationToken ct = default)
{
    var batches = _db.GiftBatches
        .Where(b =>
            b.LedgerNumber == p.LedgerNumber
            && b.GlEffectiveDate >= p.StartDate
            && b.GlEffectiveDate <= p.EndDate);
    // BatchStatus=Posted via global filter

    var groupedGifts = await batches
        .SelectMany(b => b.Gifts)
        .SelectMany(g => g.Details)
        .Where(d => d.MotivationDetail.Receipt)
        .GroupBy(d => new {
            d.MotivationGroupCode,
            d.GiftBatch.CurrencyCode })
        .ToListAsync(ct);

    return MethodOfGivingReport.From(groupedGifts);
}

BR-GIFT-013: SEPA Mandate Reference Format

// Column DDL: enforces the storage shape
sql = "ALTER TABLE PUB_a_recurring_gift "
    + "ADD COLUMN a_sepa_mandate_reference_c "
    + "varchar(70) DEFAULT NULL "
    + "AFTER p_banking_details_key_i";
ADataBase.ExecuteNonQuery(
    sql, SubmitChangesTransaction);

// Format convention enforced by callers:
//   {donor_key}{YYYYMMDD}
// e.g. "27000000020220714"
//      where 2700000002 = donor partner key
//            20220714  = mandate-given date

public readonly record struct SepaMandateReference
{
    public string Value { get; }

    private SepaMandateReference(string value)
        => Value = value;

    public static SepaMandateReference Create(
        long donorKey,
        DateOnly mandateGiven)
    {
        var s =
            $"{donorKey}{mandateGiven:yyyyMMdd}";

        if (s.Length > 70)
            throw new ArgumentException(
                "SEPA mandate exceeds varchar(70)");

        return new SepaMandateReference(s);
    }

    public override string ToString() => Value;
}

// On the EF Core entity:
public class RecurringGift
{
    [MaxLength(70)]
    public string? SepaMandateReference { get; set; }
    public DateOnly? SepaMandateGiven   { get; set; }
}

9.7 Business Rule Traceability

The following matrix maps each rule to its Concho-verified source file and line range, evidence type, confidence score, GWT origin badge, and legacy-test corroboration:

10. Data Mapping Strategy

Petra's legacy data layer is unusual for a system its age: it is already SQL-based (PostgreSQL, MySQL, or SQLite via the TDBType abstraction in the legacy code), and the table definitions are generated from a single master XML schema (db/petra.xml) into typed C# DataSets. The modernization replaces both ends of that chain: the master schema becomes EF Core migrations targeting PostgreSQL exclusively, and the typed DataSets become EF Core 10 entities. Because the data store is already SQL-on-Postgres in the production deployment, this section focuses on shape change (typed DataSet → entity / VARCHAR boolean suffixes → bool properties / column-name normalisation) rather than the radical structural transform that a COBOL VSAM modernization would require.

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

10.1 Legacy Data Analysis

The subsystem owns 8 tables in the legacy schema (all rooted at db/petra.xml):

Three observations from the data analysis:

1. COBOL-style column naming. Even though petra is a C# system, the SQL column names still carry COBOL-era suffixes — _l for boolean, _n for numeric, _c for character, _d for date, _i for integer. This is a vestige of the Pascal-language ancestor that petra modernized away from decades ago. The modernized schema drops these suffixes in favour of standard typed columns; the Section 4.4 ER diagram shows the target names.
2. Composite primary keys. Every table uses a composite PK that includes the ledger ID and runs through batch → gift → detail numbers. This composite-key strategy is preserved in the modernization — it makes natural-key idempotency in the CDC bridge (Section 11) trivial and avoids the impedance mismatch of inventing surrogate UUIDs.
3. Three-currency amount columns. Every monetary value appears three times: transaction currency, base currency, international (ICH clearing) currency. This is structural to BR-GIFT-003 (Multi-Currency Gift Processing) and is preserved column-for-column in the modernized schema.

10.2 Schema Mappings

Three representative entities are mapped in detail below: gift_batch (the batch envelope), gift_detail (the multi-currency line item), and motivation_detail (the reference data joined into every gift). The remaining five tables follow the same patterns and are mapped in the code-and-test-generation workflow's EF Core migrations.

10.2.1 a_gift_batch → gift_batch

<!-- db/petra.xml (excerpt) -->
<Table name="a_gift_batch">
 <Field name="a_ledger_number_i"
   type="integer" not-null="yes"/>
 <Field name="a_batch_number_i"
   type="integer" not-null="yes"/>
 <Field name="a_batch_description_c"
   type="varchar" length="80"/>
 <Field name="a_batch_status_c"
   type="varchar" length="16"
   default="Unposted"/>
 <Field name="a_currency_code_c"
   type="varchar" length="10"
   not-null="yes"/>
 <Field name="a_exchange_rate_to_base_n"
   type="number" precision="24"
   scale="10" default="1.0"/>
 <Field name="a_gl_effective_date_d"
   type="date" not-null="yes"/>
 <Field name="a_batch_year_i"
   type="integer"/>
 <Field name="a_batch_period_i"
   type="integer"/>
 <Field name="a_batch_total_n"
   type="number" precision="13"
   scale="2" default="0"/>
 <Field name="a_hash_total_n"
   type="number" precision="13"
   scale="2" default="0"/>
 <Field name="a_gift_type_c"
   type="varchar" length="16"
   default="Gift"/>
 <Field name="a_method_of_payment_code_c"
   type="varchar" length="20"/>
 <PrimaryKey>
  <Column name="a_ledger_number_i"/>
  <Column name="a_batch_number_i"/>
 </PrimaryKey>
</Table>

-- migrations/001_create_gift_batch.sql
CREATE TABLE gift_processing.gift_batch (
  ledger_id            INTEGER NOT NULL,
  batch_number         INTEGER NOT NULL,
  batch_description    VARCHAR(80),
  batch_status         VARCHAR(16) NOT NULL
    DEFAULT 'Unposted'
    CHECK (batch_status IN
      ('Unposted','Posted','Cancelled')),
  currency_code        VARCHAR(10)
    NOT NULL,
  exchange_rate_to_base
    NUMERIC(24, 10) NOT NULL DEFAULT 1.0,
  gl_effective_date    DATE NOT NULL,
  batch_year           INTEGER,
  batch_period         INTEGER,
  batch_total          NUMERIC(13, 2)
    NOT NULL DEFAULT 0,
  hash_total           NUMERIC(13, 2)
    NOT NULL DEFAULT 0,
  gift_type            VARCHAR(16)
    NOT NULL DEFAULT 'Gift',
  method_of_payment_code VARCHAR(20),
  gl_journal_ref       VARCHAR(40),
  posted_at            TIMESTAMPTZ,
  posted_by            VARCHAR(64),
  created_at           TIMESTAMPTZ
    NOT NULL DEFAULT now(),
  updated_at           TIMESTAMPTZ
    NOT NULL DEFAULT now(),
  created_by           VARCHAR(64)
    NOT NULL,
  updated_by           VARCHAR(64)
    NOT NULL,
  PRIMARY KEY (ledger_id, batch_number)
);

CREATE INDEX
  ix_gift_batch_effective_date
  ON gift_processing.gift_batch
    (ledger_id, gl_effective_date);

CREATE INDEX
  ix_gift_batch_status
  ON gift_processing.gift_batch
    (batch_status)
  WHERE batch_status = 'Unposted';

// src/Petra.GiftProcessing/Domain/
//   GiftBatch.cs

public enum BatchStatus
{ Unposted, Posted, Cancelled }

public class GiftBatch
{
  public int LedgerId { get; set; }
  public int BatchNumber
    { get; private set; }
  public string? BatchDescription
    { get; set; }
  public BatchStatus BatchStatus
    { get; private set; }
    = BatchStatus.Unposted;
  public string CurrencyCode { get; set; }
    = "EUR";
  public decimal ExchangeRateToBase
    { get; set; } = 1.0m;
  public DateOnly GlEffectiveDate
    { get; set; }
  public int? BatchYear { get; set; }
  public int? BatchPeriod { get; set; }
  public decimal BatchTotal { get; set; }
  public decimal HashTotal { get; set; }
  public string GiftType { get; set; }
    = "Gift";
  public string? MethodOfPaymentCode
    { get; set; }
  public string? GlJournalRef
    { get; private set; }
  public DateTimeOffset? PostedAt
    { get; private set; }
  public string? PostedBy
    { get; private set; }

  // Audit
  public DateTimeOffset CreatedAt
    { get; set; } = DateTimeOffset.UtcNow;
  public DateTimeOffset UpdatedAt
    { get; set; } = DateTimeOffset.UtcNow;
  public string CreatedBy { get; set; } = "";
  public string UpdatedBy { get; set; } = "";

  // Children
  public List<Gift> Gifts { get; }
    = new();

  // Behaviour (BR-GIFT-007)
  public void MarkPosted(
    string user,
    string journalRef)
  {
    if (BatchStatus != BatchStatus.Unposted)
      throw new BatchAlreadyPostedException(
        LedgerId, BatchNumber);
    BatchStatus = BatchStatus.Posted;
    PostedAt    = DateTimeOffset.UtcNow;
    PostedBy    = user;
    GlJournalRef = journalRef;
  }
}

10.2.2 a_gift_detail → gift_detail (the multi-currency line item)

<Table name="a_gift_detail">
 <Field name="a_ledger_number_i"
   type="integer" not-null="yes"/>
 <Field name="a_batch_number_i"
   type="integer" not-null="yes"/>
 <Field name="a_gift_transaction_number_i"
   type="integer" not-null="yes"/>
 <Field name="a_detail_number_i"
   type="integer" not-null="yes"/>
 <Field name="a_motivation_group_code_c"
   type="varchar" length="24"
   not-null="yes"/>
 <Field name="a_motivation_detail_code_c"
   type="varchar" length="24"
   not-null="yes"/>
 <Field name="p_recipient_key_n"
   type="bigint" default="0"/>
 <Field name="a_recipient_ledger_number_n"
   type="bigint" default="0"/>
 <Field name="a_gift_transaction_amount_n"
   type="number" precision="13"
   scale="2" not-null="yes"/>
 <Field name="a_gift_amount_n"
   type="number" precision="13"
   scale="2" not-null="yes"/>
 <Field name="a_gift_amount_intl_n"
   type="number" precision="13"
   scale="2" not-null="yes"/>
 <Field name="a_tax_deductible_pct_n"
   type="number" precision="5"
   scale="2" default="0"/>
 <Field name="a_tax_deductible_amount_n"
   type="number" precision="13"
   scale="2" default="0"/>
 <Field name="a_non_deductible_amount_n"
   type="number" precision="13"
   scale="2" default="0"/>
 <Field
   name="a_tax_deductible_amount_base_n"
   type="number" precision="13"
   scale="2" default="0"/>
 <Field
   name="a_non_deductible_amount_base_n"
   type="number" precision="13"
   scale="2" default="0"/>
 <Field name="a_modified_detail_l"
   type="bit" default="0"/>
 <Field name="a_confidential_gift_flag_l"
   type="bit" default="0"/>
 <PrimaryKey>
  <Column name="a_ledger_number_i"/>
  <Column name="a_batch_number_i"/>
  <Column
    name="a_gift_transaction_number_i"/>
  <Column name="a_detail_number_i"/>
 </PrimaryKey>
</Table>

CREATE TABLE gift_processing.gift_detail (
  ledger_id              INTEGER NOT NULL,
  batch_number           INTEGER NOT NULL,
  gift_transaction_number INTEGER
    NOT NULL,
  detail_number          INTEGER NOT NULL,
  motivation_group_code  VARCHAR(24)
    NOT NULL,
  motivation_detail_code VARCHAR(24)
    NOT NULL,
  recipient_partner_key  BIGINT
    NOT NULL DEFAULT 0,
  recipient_ledger_number BIGINT
    NOT NULL DEFAULT 0,
  gift_transaction_amount
    NUMERIC(13, 2) NOT NULL,
  gift_amount            NUMERIC(13, 2)
    NOT NULL,
  gift_amount_intl       NUMERIC(13, 2)
    NOT NULL,
  tax_deductible_pct     NUMERIC(5, 2)
    NOT NULL DEFAULT 0
    CHECK (tax_deductible_pct
      BETWEEN 0 AND 100),
  tax_deductible_amount  NUMERIC(13, 2)
    NOT NULL DEFAULT 0,
  non_deductible_amount  NUMERIC(13, 2)
    NOT NULL DEFAULT 0,
  tax_deductible_amount_base
    NUMERIC(13, 2) NOT NULL DEFAULT 0,
  non_deductible_amount_base
    NUMERIC(13, 2) NOT NULL DEFAULT 0,
  tax_deductible_amount_intl
    NUMERIC(13, 2) NOT NULL DEFAULT 0,
  non_deductible_amount_intl
    NUMERIC(13, 2) NOT NULL DEFAULT 0,
  modified_detail        BOOLEAN
    NOT NULL DEFAULT FALSE,
  confidential_gift_flag BOOLEAN
    NOT NULL DEFAULT FALSE,
  created_at             TIMESTAMPTZ
    NOT NULL DEFAULT now(),
  updated_at             TIMESTAMPTZ
    NOT NULL DEFAULT now(),
  created_by             VARCHAR(64)
    NOT NULL,
  updated_by             VARCHAR(64)
    NOT NULL,
  PRIMARY KEY
    (ledger_id, batch_number,
     gift_transaction_number,
     detail_number),
  FOREIGN KEY
    (ledger_id, batch_number,
     gift_transaction_number)
    REFERENCES
    gift_processing.gift
      (ledger_id, batch_number,
       gift_transaction_number)
);

CREATE INDEX
  ix_gift_detail_recipient
  ON gift_processing.gift_detail
    (recipient_partner_key);

CREATE INDEX
  ix_gift_detail_motivation
  ON gift_processing.gift_detail
    (motivation_group_code,
     motivation_detail_code);

// src/Petra.GiftProcessing/Domain/
//   GiftDetail.cs

public class GiftDetail
{
  // Composite PK (parts mirror DDL)
  public int LedgerId { get; set; }
  public int BatchNumber { get; set; }
  public int GiftTransactionNumber
    { get; set; }
  public int DetailNumber { get; set; }

  public string MotivationGroupCode
    { get; set; } = "GIFT";
  public string MotivationDetailCode
    { get; set; } = "SUPPORT";

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

  // BR-GIFT-003 three-currency
  public decimal GiftTransactionAmount
    { get; set; }
  public decimal GiftAmount { get; set; }
  public decimal GiftAmountIntl
    { get; set; }

  // BR-GIFT-009 + BR-GIFT-010 outputs
  public decimal TaxDeductiblePct
    { get; private set; }
  public decimal TaxDeductibleAmount
    { get; private set; }
  public decimal NonDeductibleAmount
    { get; private set; }
  public decimal TaxDeductibleAmountBase
    { get; private set; }
  public decimal NonDeductibleAmountBase
    { get; private set; }
  public decimal TaxDeductibleAmountIntl
    { get; private set; }
  public decimal NonDeductibleAmountIntl
    { get; private set; }

  // BR-GIFT-008
  public bool ModifiedDetail
    { get; private set; }
  // BR-GIFT-006
  public bool ConfidentialGiftFlag
    { get; set; }

  public DateTimeOffset CreatedAt
    { get; set; } = DateTimeOffset.UtcNow;
  public DateTimeOffset UpdatedAt
    { get; set; } = DateTimeOffset.UtcNow;
  public string CreatedBy { get; set; } = "";
  public string UpdatedBy { get; set; } = "";

  // Navigation
  public Gift Gift { get; set; } = null!;
  public MotivationDetail MotivationDetail
    { get; set; } = null!;
  public Partner Recipient { get; set; }
    = null!;
  public Partner GiftDestination
    { get; set; } = null!;
}

10.2.3 a_motivation_detail → motivation_detail (reference data)

<Table name="a_motivation_detail">
 <Field name="a_ledger_number_i"
   type="integer" not-null="yes"/>
 <Field name="a_motivation_group_code_c"
   type="varchar" length="24"
   not-null="yes"/>
 <Field name="a_motivation_detail_code_c"
   type="varchar" length="24"
   not-null="yes"/>
 <Field name="a_motivation_detail_desc_c"
   type="varchar" length="80"/>
 <Field name="a_account_code_c"
   type="varchar" length="16"/>
 <Field name="a_cost_centre_code_c"
   type="varchar" length="20"/>
 <Field name="a_motivation_status_l"
   type="bit" default="1"/>
 <Field name="a_receipt_l"
   type="bit" default="1"/>
 <Field name="a_tax_deductible_l"
   type="bit" default="1"/>
 <Field name="p_linked_partner_key_n"
   type="bigint" default="0"/>
 <PrimaryKey>
  <Column name="a_ledger_number_i"/>
  <Column
    name="a_motivation_group_code_c"/>
  <Column
    name="a_motivation_detail_code_c"/>
 </PrimaryKey>
</Table>

CREATE TABLE
  gift_processing.motivation_detail
(
  ledger_id              INTEGER NOT NULL,
  motivation_group_code  VARCHAR(24)
    NOT NULL,
  motivation_detail_code VARCHAR(24)
    NOT NULL,
  motivation_detail_desc VARCHAR(80),
  account_code           VARCHAR(16),
  cost_centre_code       VARCHAR(20),
  motivation_status      BOOLEAN
    NOT NULL DEFAULT TRUE,
  receipt_eligible       BOOLEAN
    NOT NULL DEFAULT TRUE,
  tax_deductible         BOOLEAN
    NOT NULL DEFAULT TRUE,
  linked_partner_key     BIGINT
    NOT NULL DEFAULT 0,
  created_at             TIMESTAMPTZ
    NOT NULL DEFAULT now(),
  updated_at             TIMESTAMPTZ
    NOT NULL DEFAULT now(),
  created_by             VARCHAR(64)
    NOT NULL,
  updated_by             VARCHAR(64)
    NOT NULL,
  PRIMARY KEY
    (ledger_id, motivation_group_code,
     motivation_detail_code),
  FOREIGN KEY
    (ledger_id, motivation_group_code)
    REFERENCES
    gift_processing.motivation_group
      (ledger_id, motivation_group_code)
);

// src/Petra.GiftProcessing/Domain/
//   MotivationDetail.cs

public class MotivationDetail
{
  // Composite PK
  public int LedgerId { get; set; }
  public string MotivationGroupCode
    { get; set; } = "";
  public string MotivationDetailCode
    { get; set; } = "";

  public string? MotivationDetailDesc
    { get; set; }
  public string? AccountCode { get; set; }
  public string? CostCentreCode
    { get; set; }

  public bool MotivationStatus
    { get; set; } = true;

  // BR-GIFT-004 (receipt eligibility flag)
  public bool ReceiptEligible
    { get; set; } = true;

  public bool TaxDeductible
    { get; set; } = true;

  // BR-GIFT-011 (linked partner lookup)
  public long LinkedPartnerKey
    { get; set; }

  public DateTimeOffset CreatedAt
    { get; set; } = DateTimeOffset.UtcNow;
  public DateTimeOffset UpdatedAt
    { get; set; } = DateTimeOffset.UtcNow;
  public string CreatedBy { get; set; } = "";
  public string UpdatedBy { get; set; } = "";

  // Navigation
  public MotivationGroup Group
    { get; set; } = null!;
  public List<GiftDetail> GiftDetails
    { get; } = new();
}

// Domain method for receipt eligibility
public static class MotivationSpecs
{
  // BR-GIFT-004 second flag
  public static IQueryable<GiftDetail>
    OnReceiptEligibleMotivation(
      this IQueryable<GiftDetail> q)
    => q.Where(d =>
      d.MotivationDetail.ReceiptEligible);
}

10.3 Data Type Mappings

Because petra is already a SQL-on-PostgreSQL system, the petra.xml → PostgreSQL DDL type map is small and mostly identity. The handful of consequential rules:

10.4 Data Transfer Procedures

Petra is already SQL-on-Postgres in production, so the data-transfer story is two parts: an initial backfill from the legacy database into the modernized schema, and the ongoing CDC stream that keeps the modern schema in sync until the legacy database is decommissioned. The CDC stream is the strangler-fig bridge described in detail in Section 11; this subsection covers the backfill side.

10.4.1 Backfill Pipeline (One-Time Per Ledger)

The backfill is run once per ledger and once per pre-cutover validation rehearsal. It is a pure SQL pipeline — no application code involved — because the legacy and modernized schemas live on the same PostgreSQL engine family.

1. Snapshot. pg_dump --schema-only --table='a_gift_*' --table='a_motivation_*' against the legacy DB to capture the schema; then a SELECT with FOR SHARE on the ledger's rows to lock the source while the snapshot is taken.
2. Transform. A single SQL statement per target table renames columns, casts types, and adds audit columns:

   -- backfill: gift_batch
   INSERT INTO gift_processing.gift_batch (
     ledger_id, batch_number,
     batch_description, batch_status,
     currency_code, exchange_rate_to_base,
     gl_effective_date, batch_year,
     batch_period, batch_total, hash_total,
     gift_type, method_of_payment_code,
     gl_journal_ref, posted_at, posted_by,
     created_at, updated_at, created_by,
     updated_by
   )
   SELECT
     a_ledger_number_i,
     a_batch_number_i,
     NULLIF(a_batch_description_c, ''),
     a_batch_status_c,
     a_currency_code_c,
     a_exchange_rate_to_base_n,
     a_gl_effective_date_d,
     a_batch_year_i,
     a_batch_period_i,
     COALESCE(a_batch_total_n, 0),
     COALESCE(a_hash_total_n, 0),
     COALESCE(a_gift_type_c, 'Gift'),
     NULLIF(a_method_of_payment_code_c, ''),
     NULL,  -- gl_journal_ref backfilled
            -- from legacy GL via bridge
     CASE WHEN a_batch_status_c = 'Posted'
          THEN a_date_modified_d::TIMESTAMPTZ
          ELSE NULL END,
     CASE WHEN a_batch_status_c = 'Posted'
          THEN a_modified_by_c
          ELSE NULL END,
     COALESCE(a_date_created_d::TIMESTAMPTZ,
              now()),
     COALESCE(a_date_modified_d::TIMESTAMPTZ,
              now()),
     COALESCE(a_created_by_c, 'backfill'),
     COALESCE(a_modified_by_c, 'backfill')
   FROM legacy.a_gift_batch
   WHERE a_ledger_number_i = $1
   ON CONFLICT (ledger_id, batch_number)
   DO NOTHING;

3. Load. INSERT … ON CONFLICT DO NOTHING on every table; idempotent so the backfill is re-runnable.
4. Verify. See §10.5 below.

10.4.2 Schema Transformation Pipeline

Once backfill completes, the schema-transformation pipeline takes over for incremental sync:

10.5 Data Validation Strategy

Four independent validation paths run during backfill rehearsals and after every cutover stage; all four must pass for the stage to be considered green.

The BR-rule sampling pass is the only one that exercises the modernized domain code path — if FluentValidation, the EF Core entity, or the BR-GIFT-010 calculation diverges from legacy by even 0.01 EUR per detail, this is where it surfaces. Tolerance is set tight (≤ 0.01) because monetary fidelity is the load-bearing property of the subsystem.

10.6 Rollback Procedures

Three rollback affordances stack from cheapest to most expensive:

1. APIM traffic flip. Reverse the per-endpoint traffic shift in Section 11: route 100% of traffic back to the legacy ASMX endpoint. Modern PostgreSQL is left intact (read-only); CDC stream continues running but no new writes hit the modern API. Reversible in < 1 minute.
2. Per-ledger replay. Truncate the modern tables for a single ledger; re-run the backfill INSERT statements. The composite PK (ledger_id, batch_number, ...) scopes the truncate cleanly; other ledgers stay live. Reversible in 10–30 minutes per ledger.
3. Point-in-time recovery. Azure Database for PostgreSQL Flexible Server is configured with 7-day backup retention; a full PITR restore takes 15–90 minutes depending on database size. Used only if the modern DB has been corrupted in a way that the targeted truncate cannot fix.

10.7 Mapping Summary

10.8 Schema Migration Design Rules

These rules govern every design decision when translating legacy data structures to the modernized data model. They are split into universal rules (apply regardless of target database engine) and engine-specific rules (implementation details for PostgreSQL, DynamoDB, MongoDB). Together they ensure consistency between the schema artifact (DDL), the ORM/document model, and the seed data.

10.8.1 Universal Rules (Engine-Agnostic)

10.8.2 Engine-Specific Rules

For the overall modernization execution plan including phased cutover, dual-write implementation, and rollback procedures, see Section 11: Modernization Strategy.

11. Modernization Strategy

This section defines the modernization execution strategy and the legacy/modern coexistence plan for the Finance — Gift Processing subsystem. The goal is to keep donation processing — the core revenue workflow for non-profit organizations — running uninterrupted on the existing Petra (OpenPetra) platform while the new Angular 20 + .NET 10 stack is incrementally validated and accepts production traffic.

11.1 Why the Classical Strangler-Fig Pattern Fits This System

The coexistence pattern is selected by applying a decision tree to the legacy system's interaction surface — the shape of the interface through which clients reach the system's business logic. The tree has one pivotal question:

Does the source system have a request-routing surface (load balancer, API gateway, reverse proxy)?

For Petra, the answer is unambiguously YES.

Concho analysis of Petra's Finance — Gift Processing entry points confirms a conventional HTTP-routable interaction surface. The legacy subsystem is reached through ASP.NET Web Services (.asmx) served by Mono / FastCGI behind an nginx reverse proxy, with four primary entry points:

• TGiftTransactionWebConnector (confidence 0.90) — RPC endpoint exposing gift batch creation, posting, validation, transaction management, annual receipt generation, and financial-period operations.
• AnnualReceiptGenerationInterface (confidence 0.70) — HTTP form interface for template upload, email configuration, and bulk annual tax-receipt generation.
• GiftBatchManagementInterface (confidence 0.65) — HTTP interface for managing gift batches and transactions, with bookmarkable URL navigation.
• BankImportManagementInterface (confidence 0.60) — HTTP interface for uploading bank statements (CAMT v053, MT940, CSV, ZIP).

These four entry points all sit behind the same nginx routing layer. That alone rules out SAROC, which is reserved for systems whose only interaction surface is a green-screen terminal, a batch-file drop, or a thick desktop client writing directly to a shared database. With a request-routing surface present, the decision tree advances to its second branch:

Are writes idempotent and is divergence acceptable for short windows?

For Petra Gift Processing, the answer is unambiguously NO. Three Concho-identified business rules establish non-idempotent, ordering-sensitive write semantics that make symmetric dual-write unsafe:

1. GiftBatchSequentialNumbering (confidence 0.95) — Gift batch numbers are assigned by atomically incrementing LastGiftBatchNumber on the ledger table. The counter is non-idempotent; if both systems accept the same logical batch-creation in parallel, the two writes claim different batch numbers and the resulting gift → gift_detail → motivation hierarchy diverges between systems.
2. GiftBatchFinancialPeriodValidation (confidence 0.90) — Gift batch effective dates must fall within an open accounting period, validated by TFinancialYear with a force-fit option. A batch posted in legacy that references a period later closed in the modern system (or vice versa) violates this constraint and silently corrupts the GL.
3. MultiCurrencyGiftProcessingRule (confidence 0.83) — Multi-currency processing maintains separate tracking of transaction amounts, base amounts, and international amounts derived from exchange-rate snapshots. If the two systems pick the same gift up with different exchange-rate snapshots, the tax-deductible total and the GL credit diverge in opposite directions.

The middle branch of the decision tree therefore selects classical strangler-fig: an API gateway progressively shifts traffic from legacy endpoints to modern endpoints, reads first then writes, with a single source of truth at every moment for every endpoint. Symmetric dual-write — where both systems accept writes during the overlap — is explicitly off the table.

11.2 EIP Notation Diagram of the Bridge

Although the classical strangler-fig pattern operates primarily at the routing layer — Azure API Management shifts traffic per endpoint group — the data plane still requires a synchronization bridge during the overlap window. As long as some endpoints route to legacy, the writes those endpoints accept must reach the modern PostgreSQL before any modernized endpoint reads stale data. That synchronization bridge follows the canonical four-component Enterprise Integration Pattern (EIP) shape from Hohpe & Woolf (2003): Channel Adapter → Message Translator → Message Channel → Message Endpoint.

Figure 11.1 — Reliable Message Queue Pattern (EIP component view). During the strangler-fig coexistence window, mutations applied through legacy serverMFinance.asmx endpoints are captured by a Debezium connector on the legacy PostgreSQL WAL, translated into JSON domain events, and forwarded through Azure Service Bus (session-ordered per gift batch) to a background-thread consumer in the modern Gift Processing API.

Note on Figure 11.2 / 11.3. The SAROC topology diagram (two-paths bulk-ETL + queue-replay) is specific to the SAROC pattern and does not apply to classical strangler-fig — strangler-fig is driven by per-endpoint traffic shifting, not a one-shot bulk ETL. The temporal sequence for strangler-fig is shown in Section 11.3 as a Mermaid sequence diagram (Figure 11.2 below). Per-pattern Figure 11.2 / 11.3 templates for classical strangler-fig will land in the legacy-coexistence skill when the code-and-test-generation workflow's bridge generation for this pattern reaches implementationStatus: full.

11.3 Cutover Choreography

The classical strangler-fig cutover is driven by Azure API Management (APIM) traffic-shifting policies, not by a queue-replay event. APIM owns the public surface; behind it sit the legacy Mono / serverMFinance.asmx endpoints and the modern .NET 10 services. Each APIM policy decides, per request path and per HTTP method, which backend handles the call. The cutover advances through six phases.

Phase 1 — Deploy modern services in shadow mode

Gift Processing API and Receipt Generation Service are deployed to Azure App Service (P1v3 Linux) alongside the legacy Mono/FastCGI infrastructure. APIM routes 100% of gift-processing traffic to legacy. The modern services are reachable only through their staging-slot URLs and internal health probes (/health/ready, /health/live, /health/startup). Azure Database for PostgreSQL is provisioned and the EF Core migrations are applied, but production data has not yet been loaded.

Estimated duration: 2–3 weeks (provisioning + smoke testing). Risk: low — no production traffic touches the modern stack.

Phase 2 — Activate the data-synchronization bridge

A Debezium connector is configured against the legacy PostgreSQL write-ahead log to capture mutations on the eight watched 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). Change events flow through Azure Service Bus — a session-ordered topic, persistent, with dead-lettering enabled. The session key is (ledger_id, batch_id), ensuring every event for a given batch arrives at the consumer in FIFO order. A bulk-ETL snapshot of existing data loads first; the background-thread consumer in Gift Processing API then drains the queue and applies events to the modern PostgreSQL schema via Entity Framework Core with natural-key idempotency.

The APIM policy that performs traffic shifting is parameterized on a sample APIM policy fragment; the canonical form is shown below in the dark BR theme.

<!-- APIM policy: per-endpoint traffic shift for Gift Processing -->
<policies>
  <inbound>
    <base />
    <choose>
      <!-- Read-only endpoints: serve from modern once Phase 3 lands -->
      <when condition="@(context.Request.Method == &quot;GET&quot; &amp;&amp; context.Request.Url.Path.StartsWith(&quot;/api/gift-processing/v1/batches&quot;))">
        <set-backend-service base-url="https://petra-gift-api.azurewebsites.net" />
      </when>
      <!-- Default: legacy Mono / .asmx until each write stage is migrated -->
      <otherwise>
        <set-backend-service base-url="https://petra-legacy.openpetra.org" />
        <rewrite-uri template="/serverMFinance.asmx" />
      </otherwise>
    </choose>
    <set-header name="X-Petra-Routing-Source" exists-action="override">
      <value>@(context.Request.Url.Path)</value>
    </set-header>
  </inbound>
  <backend><base /></backend>
</policies>

# Debezium connector config (legacy Petra PostgreSQL WAL -> Azure Service Bus)
name: petra-gift-cdc
connector.class: io.debezium.connector.postgresql.PostgresConnector
plugin.name: pgoutput
database.hostname: legacy-petra-db.example.org
database.dbname: petra_prod
slot.name: petra_gift_slot
publication.name: petra_gift_publication
table.include.list: public.a_gift_batch,public.a_gift,public.a_gift_detail,public.a_motivation_group,public.a_motivation_detail,public.a_recurring_gift_batch,public.a_recurring_gift,public.a_recurring_gift_detail
key.converter: org.apache.kafka.connect.json.JsonConverter
value.converter: org.apache.kafka.connect.json.JsonConverter
transforms: unwrap,routeBySession
transforms.unwrap.type: io.debezium.transforms.ExtractNewRecordState
transforms.routeBySession.type: org.apache.kafka.connect.transforms.RegexRouter
transforms.routeBySession.regex: .*
transforms.routeBySession.replacement: petra.gift.cdc.v1
# Azure Service Bus sink emits each event with sessionId = ${ledger_id}.${batch_id}

// Concho domain event envelope (sage-domain-event-v1) — emitted by the translator
{
  "eventId": "01J8K3Z9R7VYM2QH3F4XW2C6T8",
  "eventType": "petra.gift.gift_detail.upserted.v1",
  "eventTime": "2026-06-14T09:21:07.412Z",
  "source": "petra-legacy/serverMFinance.asmx",
  "sessionId": "43.1047",
  "naturalKey": {
    "ledger_id": 43,
    "batch_id": 1047,
    "gift_transaction_number": 1,
    "detail_number": 1
  },
  "payload": {
    "motivation_group_code": "SUPPORT",
    "motivation_detail_code": "FIELD",
    "gift_transaction_amount": 3000.00,
    "gift_amount_in_base_currency": 2580.00,
    "currency_code": "EUR",
    "exchange_rate_to_base": 0.86,
    "tax_deductible_pct": 100.00
  }
}

Estimated duration: 3–4 weeks (connector configuration, snapshot ETL, reconciliation tooling, alerting). Risk: medium — the bridge must demonstrably catch up to the live legacy database before any traffic is shifted.

Phase 3 — Migrate read-only endpoints

APIM policies begin routing read-only gift-processing requests to the modern API: gift-batch listings, gift detail queries, motivation group/detail lookups, donor gift history, recurring-gift batch queries, and exchange-rate lookups. Reads are safe to migrate first because they have no side effects on the source of truth (still legacy). APIM uses URL-path matching (e.g., GET /api/gift-processing/v1/batches → modern; everything else → legacy) with canary stepping 10% → 25% → 50% → 100%. Application Insights monitors error rate, p99 latency, and response-content diff (sampled) between legacy and modern; rollback is a single APIM policy revert.

Estimated duration: 2–3 weeks (canary progression with bake periods). Risk: low — reads are side-effect-free; rollback is < 1 minute.

Phase 4 — Migrate write endpoints in risk-ordered stages

Write endpoints migrate in five risk-ordered stages. Each stage has its own validation gate; the next stage cannot start until the previous gate has held green for a defined bake period.

Once a write endpoint moves to modern, the data synchronization bridge for the affected tables reverses direction or is shut off, depending on whether any legacy paths still read those tables. The reversal pattern is documented per stage in Appendix B's implementation roadmap.

Estimated duration: 10–12 weeks (sum of stages and bake periods). Risk: rises from low to high across the stages; the bake periods are the controls.

Phase 5 — Verify full synchronization

After stages 4a–4e complete and the modern stack owns all gift-processing writes, the team runs a full reconciliation: row-count parity across all eight target tables, checksum comparison on gift-batch totals by period, sample-row diffs on 100 randomly selected gift detail records (transaction amount, base amount, motivation codes, tax-deductible percentage), Application Insights confirmation that consumer lag is ≤ 0 and error rate is < 0.1%, and a full Playwright regression suite against the modern Angular SPA.

Estimated duration: 1–2 weeks. Risk: low — the reconciliation is fact-finding, not state-changing.

Phase 6 — Decommission legacy Gift Processing endpoints

When Finance Ops confirms operational confidence (a business decision, not a technical deadline): APIM policies are updated to route 100% of gift-processing traffic to the modern services; legacy serverMFinance.asmx gift-processing operations are deprecated (HTTP 301 redirect, then HTTP 410 Gone after a defined sunset window); the CDC bridge is stopped and the queue drained and removed; the legacy Mono/FastCGI server stays online for unmigrated subsystems (Partner, GL, Reporting, System Management) until their own modernization cycles complete; the Angular 20 SPA becomes the sole gift-processing interface.

Estimated duration: 2 weeks (sunset window + telemetry confirmation). Risk: low if Phase 5 held green.

Temporal view — Figure 11.2

sequenceDiagram
    participant U as Users
    participant APIM as Azure API Management
    participant L as "Legacy Petra
(.asmx / Mono)"
    participant CDC as Debezium CDC
    participant SB as "Azure Service Bus
(session-ordered)"
    participant M as Modern .NET 10 API
    participant DB as Azure PostgreSQL

    Note over U,DB: Phase 1 — Deploy modern services (shadow mode)
    U->>APIM: All gift processing requests
    APIM->>L: 100% routed to legacy
    Note right of M: Modern services deployed
but receive no production traffic

    Note over U,DB: Phase 2 — Activate data-synchronization bridge
    L->>CDC: Debezium tails PostgreSQL WAL
    CDC->>SB: Domain events (sessionId = ledger.batch)
    Note right of SB: Snapshot ETL +
ongoing CDC capture
    SB->>M: Background-thread consumer drains queue
    M->>DB: Apply with natural-key idempotency

    Note over U,DB: Phase 3 — Migrate read-only endpoints
    U->>APIM: GET /api/gift-processing/v1/batches
    APIM->>M: Reads to modern (canary 10→25→50→100%)
    U->>APIM: POST /serverMFinance.asmx (writes)
    APIM->>L: Writes still to legacy

    Note over U,DB: Phase 4 — Migrate writes in stages (4a–4e)
    U->>APIM: POST /api/gift-processing/v1/batches
    APIM->>M: Stage 4b: batch creation to modern
    M->>DB: Modern is source of truth for this stage
    Note right of L: Bridge reverses direction
for migrated tables

    Note over U,DB: Phase 5 — Verify synchronization
    Note right of DB: Row counts, checksums,
batch totals reconciled
Consumer lag = 0

    Note over U,DB: Phase 6 — Decommission legacy gift processing
    U->>APIM: All gift processing requests
    APIM->>M: 100% to modern
    Note over L: serverMFinance.asmx gift ops return 301/410
    Note over CDC: CDC bridge stopped
    Note over SB: Queue drained and removed
  

Figure 11.2 — Classical strangler-fig cutover sequence for Petra Gift Processing. Phases 1–2 establish infrastructure; Phase 3 shifts reads; Phase 4 shifts writes in five risk-ordered stages (4a–4e); Phases 5–6 verify and decommission.

11.4 Why Ordering and Idempotency Matter for Gift Processing

Gift processing is a financially ordered domain: the sequence in which mutations arrive determines the correctness of downstream outcomes — GL postings, tax-deductible receipts, donor statements, and the regulator-facing audit trail. The data-synchronization bridge must deliver per-batch events in FIFO order, and the consumer must enforce idempotency. The worked example below shows why, using realistic figures from MultiCurrencyGiftProcessingRule (confidence 0.83) and GiftBatchSequentialNumbering (confidence 0.95).

Worked example — multi-currency gift with split tax-deductibility

A donor (partner key 43000127) makes a EUR 5,000 gift to a UK non-profit whose base currency is GBP. The gift is entered in legacy batch #1047 (ledger 43, period 2026/03), with exchange rate 0.86 GBP/EUR snapshotted at batch creation. The donor wants the gift split across two motivations with different tax-deductibility percentages.

What breaks if events replay out of order:

• E5 arrives before E3 / E4. The batch post finds the batch and the gift but no gift details. Per GiftBatchSequentialNumbering and the posting state machine, the post either fails (and is retried indefinitely until E3 / E4 arrive — head-of-line blocking) or, worse, posts a zero-amount batch to GL. If E3 and E4 then arrive after a zero-amount post, the modern GL trial balance permanently disagrees with the legacy GL trial balance by EUR 5,000 for period 2026/03 — a Finance-Ops-visible reconciliation break.
• E4 arrives before E2. The gift detail insert references a gift (transaction number 1) that does not yet exist in the modern database. The insert fails on the natural-key constraint; if naively retried after E2 arrives, the detail's detail_number may be claimed by a parallel insert, producing detail-numbering drift. The annual receipt for partner 43000127 would then list the wrong detail order.
• E1 replayed twice without idempotency. The second replay attempts to increment LastGiftBatchNumber a second time (per GiftBatchSequentialNumbering, confidence 0.95), creating a phantom batch #1048 in modern that does not exist in legacy. Every subsequent batch number is then off by one between systems — an unrecoverable cross-system identity drift that breaks reconciliation for every future batch.

What breaks for the annual tax receipt:

If E3 and E4 arrive out of order and the consumer naively writes whichever arrives first into detail_number = 1, the motivation-to-amount mapping is silently swapped: the SUPPORT motivation now carries GBP 1,720 instead of GBP 2,580, and the KEYMIN motivation carries GBP 2,580 instead of GBP 1,720. The annual tax-receipt PDF for donor 43000127 (issued by Receipt Generation Service) then reports GBP 1,720 as tax-deductible instead of GBP 2,580 — an £860 understatement on the donor's tax filing. Per MultiCurrencyGiftProcessingRule (confidence 0.83), this is exactly the dual-tracking failure mode the rule exists to prevent, and it carries regulatory-compliance consequences in jurisdictions that audit non-profit tax receipts (HMRC Gift Aid, US IRS Form 990, German § 50 EStDV).

How the bridge prevents this:

• Ordering. Azure Service Bus sessions use (ledger_id, batch_id) as the session key. All events for batch #1047 are delivered in strict FIFO order to a single session-receiver; E1 always precedes E2, which always precedes E3 and E4, which precede E5. Cross-batch ordering is not enforced (and is not required — different batches don't share aggregate roots).
• Idempotency. The consumer uses natural-key idempotency: the composite key (ledger_id, batch_id, gift_transaction_number, detail_number) uniquely identifies every gift detail. The consumer's upsert is an INSERT ... ON CONFLICT DO UPDATE on that natural key; a replay of E3 finds the existing row and either no-ops or updates the same row with the same payload. LastGiftBatchNumber is never re-incremented by the consumer — the modern stack treats it as a read-only watermark sourced from legacy until Phase 4b's bake completes.

11.5 Proof-of-Concept Results

PoC to be validated in Phase 2 of execution. The classical strangler-fig bridge for Petra has not yet been implemented as a working proof-of-concept on this run. The v1 Concho code-and-test-generation workflow supports SAROC bridge generation end-to-end (reference: ACAS / Docker / ROSA); classical strangler-fig artifact generation — APIM policies, Debezium connector wiring, Service Bus topic/subscription provisioning, the consumer's natural-key idempotency upsert — is planned for the next workflow cycle. The Section 11 narrative, choreography, and operational thresholds in this section are complete and implementable manually following the structure above.

The Phase 2 PoC will validate, at minimum:

• APIM policy-based routing between a legacy .asmx endpoint and the modern .NET 10 Minimal API for a single read-only operation (gift-batch listing), including canary stepping and rollback.
• Debezium CDC from the legacy PostgreSQL WAL to Azure Service Bus, with sessionId = (ledger_id, batch_id).
• The background-thread consumer in Gift Processing API applying domain events to the modern PostgreSQL schema with natural-key idempotency — replay-safe and re-runnable.
• Round-trip latency from legacy commit to modern DB consistency: target p99 ≤ 2 s for single-row mutations during steady state.
• Reconciliation tooling that produces row-count, checksum, and sample-row-diff reports per gift table on demand.

11.6 Operational Considerations

Dead-letter behaviour

Azure Service Bus is configured with dead-lettering enabled (deadLetter: true in the persisted coexistencePattern declaration). Messages that fail processing after 5 delivery attempts move to the DLQ rather than head-of-line blocking the main queue. DLQ messages retain the original sessionId and sequence number, so manual replay after a fix is straightforward. A dedicated Azure Function monitors the DLQ depth and raises an Application Insights alert whenever depth exceeds zero — every DLQ message is treated as an incident, not a backlog.

Queue depth and consumer-lag thresholds

These thresholds are calibrated to Petra Gift Processing's transaction volume: Finance Ops at a typical non-profit handles tens to low hundreds of gift batches per day, not thousands. A queue depth of 1,000 represents a significant backlog. Organizations running year-end campaigns or disaster-relief drives should scale thresholds proportionally and re-baseline before each Phase 4 stage.

Consumer lag SLO

Target: during steady-state coexistence (Phases 3–5), modern PostgreSQL is no more than 30 seconds behind the legacy database for any committed transaction, measured as the difference between the legacy WAL commit timestamp and the consumer's ack timestamp, exported via OpenTelemetry custom metrics to Application Insights. During Phase 2's initial bulk ETL the SLO is suspended; it re-arms once the consumer drains the initial backlog to zero.

Cutover rollback plan

Every phase has an independent rollback lever. The APIM routing policy and the App Service slot-swap are independent and can be used together or separately.

App Service slot-swap provides an additional safety net: if the modern API exhibits errors after any write-stage migration, the staging slot (running the previous version) can be swapped back into production in seconds — independent of the APIM policy state. Combined, the two levers let Finance Ops respond to a surprise within minutes regardless of which side of the bridge it appeared on.

12. How Concho Enabled This Analysis

This analysis demonstrates three distinct approaches: (1) Concho-powered analysis where agents have deep insight into all subsystems via Concho MCP, (2) Claude Code alone — analyzing code with only Read/Grep/Glob, without Concho’s pre-computed knowledge — and (3) Traditional manual review by architects. Every comparison in this section includes all three so the value of Concho is clear relative to both AI-without-Concho and manual effort.

Section 12 sits at the end of the report deliberately. The earlier sections argued the modernization on its merits — the target architecture in Section 4, the platform unlocks in Section 5, the technical-debt classification in Section 6, the UI / code / data examples in Sections 7–8 and 10, the 14 behavioral rules in Section 9, and the classical strangler-fig 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 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 1,396 cataloged files, 27 business-function subsystems, and 32 technology subjects — a layered, n-tier .NET Framework 4.7 application with a jQuery + Bootstrap 4 web client, ASP.NET Web Services (.asmx) over Mono FastCGI, an XML-driven code-generated data access layer, and a multi-database abstraction over PostgreSQL, MySQL, and SQLite. Concho’s Context Graph transformed this heterogeneous C# / JavaScript / SQL / XML surface into structured, queryable intelligence — enabling the planning workflow to evaluate all 27 subsystems across 3 independent scoring runs, select Finance – Gift Processing as the modernization pilot through a 2-of-3 consensus, validate a 2-service Azure App Service target through 3-perspective consensus (composite score 7.8/10), reconcile 9 platform-affinity entries across 3 independent runs (8 ELIMINATE / 1 HYBRID), audit 28 dependencies across 2 manifests with 7 architectural concerns classified, and extract 14 behavioral rules with confidence scores 0.70–0.95 and 5 corroborated by legacy NUnit tests — 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 Modernization Complexity Estimation

12.2.6 Behavioral-Rule Catalog Construction

12.3 Why the Concho Context Graph Matters

Could Claude Code 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 Claude Code 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. A constraint might originate in a data structure, propagate through a print program, and manifest as a screen layout limitation — three different files, three different architectural layers. A tool analyzing one file at a time cannot see this full picture, and worse, it doesn’t know to look for it.

Consider the most architecturally significant discovery from this analysis: the non-idempotent write pattern that selected the classical strangler-fig coexistence strategy. The migration-execution agent needed to decide between symmetric dual-write and classical strangler-fig for the legacy/modern coexistence period. This decision required knowing three specific facts about write behavior across the gift-processing surface: (1) BR-GIFT-001 GiftBatchSequentialNumbering (confidence 0.95, in Gift.Batch.cs) atomically increments LastGiftBatchNumber on the ledger — a non-idempotent write that cannot be safely duplicated; (2) BR-GIFT-002 GiftBatchFinancialPeriodValidation (confidence 0.90, in Gift.Batch.cs) constrains batch dates to open accounting periods — a time-dependent validation that must be authoritative in exactly one system; (3) BR-GIFT-003 MultiCurrencyGiftProcessingRule (confidence 0.83, in Gift.Currency.cs) computes dual base + transaction amounts from an exchange-rate snapshot that is not stable across systems.

These three facts live in three different C# source files. No single file contains all the evidence. A file-at-a-time analysis would need to (a) know to look at batch creation, period validation, and currency conversion as a coordinated set, (b) find the specific lines in each file, and (c) synthesize the pattern: “these writes are non-idempotent across three independent enforcement points, ruling out symmetric dual-write.” Concho’s Context Graph had already classified all three rules with confidence scores and source locations. The planning agent assembled the evidence in two Concho queries (get_entities_by_subject for entry points + get_entities_by_subject for business rules) from pre-computed intelligence, not by hoping to read the right files in the right order.

The advantage of Concho’s Context Graph 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 Concho analysis has already made. 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 Three-Run Subsystem Consensus Across 27 Candidates

Concho’s candidate-selection step evaluated all 27 business-function subsystems across 3 independent runs, each applying a different emphasis lens: Run 1 (Standard Weighted Scoring), Run 2 (Technical Feasibility emphasis), and Run 3 (Business Value emphasis). Two of three runs converged on Finance – Gift Processing as the optimal pilot — a 2/3 consensus. Run 1 selected Finance – Banking on risk-aversion grounds; that result is documented as Plan B in Appendix A rather than overruled silently. The 3-run protocol consumed approximately 77 Concho queries collectively (~25 minutes of agent wall-clock), each run independently profiling subsystems through domain briefings, entity inventories, and architectural-insight queries.

12.4.2 Three-Perspective Service Architecture Validation

The service-architecture phase did not simply assert “2 services.” It submitted the Gift Processing slice to three independent analytical perspectives — Domain-Driven Design (bounded context analysis), Technical (load pattern and resource profile), and Business Capability (user roles and operational cadence) — then scored the options on a 4-dimension rubric. All three lenses unanimously proposed 2 services; the composite weighted score was 7.8/10, exceeding the 7.0 quality gate. This phase consumed only 2 Concho calls because it built on the already-profiled DonationManagement bounded context (confidence 0.84) from the candidate-assembly phase.

12.4.3 Platform Affinity Reconciliation from 3-Run Consensus

Section 5’s platform affinity analysis ran 3 independent passes and reconciled the results into 9 consensus entries (8 ELIMINATE, 1 HYBRID, 0 PRESERVE). Five of nine entries had full 3/3 inclusion-and-classification consensus; four of nine had 2/3 majority. Zero entries had a split decision requiring human review — 100% resolution rate. Five additional entries that appeared in only 1 of 3 runs were explicitly omitted with documented rationale. This consensus-then-reconcile pattern — the same approach used for candidate selection — ensures that the platform constraints surfaced for stakeholders are structurally stable, not artifacts of a single analytical perspective.

12.4.4 Evidence-Based Coexistence Pattern Selection

The migration-execution phase did not default to “strangler fig because everyone uses strangler fig.” It evaluated the pattern against specific evidence from just 2 Concho queries: (1) get_entities_by_subject(Finance - Gift Processing, entry_point) returned the 4 HTTP-routable entry points — confirming a request-routing surface exists, ruling out SAROC and selecting the middle branch of the decision tree; (2) get_entities_by_subject(Finance - Gift Processing, business_rule) returned the 7 rules including the three non-idempotent ones at 0.95 / 0.90 / 0.83 confidence — ruling out symmetric dual-write. The classical strangler-fig pattern was the only branch left, and the evidence chain is auditable.

12.4.5 Use Case Discovery from Entity Evidence

The use-case-discovery phase discovered 3 primary use cases (Gift Batch Entry through Posted GL; Annual Tax-Deductible Receipt Generation; Recurring Donation Cycle with SEPA Export) plus a documented secondary scenario (Posted Gift Adjustment, downgraded because its workflow confidence is 0.63 — below the 0.70 primary-use-case threshold). Each primary use case was selected on multi-criterion fit: cross-service span, business visibility, modernization delta, demo-ability, and rule density. All 14 catalog rules fire across these three primary use cases (Use Case 1 fires 8 of 14; Use Case 2 fires 6 of 14; Use Case 3 fires 7 of 14). This discovery consumed 13 Concho calls: 4 get_entities_by_subject queries for workflows / entry points / bounded context / integration boundaries, then 9 targeted entity lookups for workflow steps, bounded-context responsibilities, and entry-point operations.

12.4.6 Legacy-Test Discovery for High-Fidelity Rule Corroboration

A subtle but important capability of the Concho Context Graph is that it surfaces legacy test files alongside production source. The behavioral-rules phase ran a single search_files query against csharp/ICT/Testing/lib/MFinance/server/Gift/ and discovered 7 legacy NUnit test files covering the gift slice (PostGiftBatch.test.cs, RevertAdjustGiftBatch.test.cs, SingleGiftReceipt.test.cs, AnnualReceipts.test.cs, RecurringGiftBatch.test.cs, SetMotivationGroupAndDetail.test.cs, and one fixture). Cross-referencing these against the 14 catalog rules upgraded 5 rules from code-inferred to code-inferred-test-corroborated — raising their effective confidence and providing first-priority test-translation targets for the downstream code-and-test-generation workflow.

Critically, the legacy test suite for BR-GIFT-011 (Motivation Detail Assignment by Partner Class) captured a piece of original intent that code alone leaves implicit: for a non-UNIT partner the motivation is left unchanged — a "do nothing" branch that the production code expresses only as the absence of an overwrite. The original developers asserted that outcome explicitly in a test. Harvesting it gives a second, independent record of intent that nails down exactly these edge and do-nothing cases — which is precisely why Concho reads the surviving tests alongside the source.

12.5 Concho Query Snippets

For transparency, here are representative queries the planning agents executed against Concho’s Context Graph (project key petra, cycle 23). The Concho Context Graph exposes a small set of focused tools; the agents compose them to assemble evidence.

Project intelligence — one query returns the top-level shape:

get_project_metadata(project_key="petra", cycle=23)
→ { total_loc: 572757, file_count: 1396,
     primary_language: "C# / .NET Framework 4.7",
     business_function_subjects: 27,
     technology_subjects: 32,
     data_stores: ["PostgreSQL", "MySQL", "SQLite"] }

Subsystem profile — one query returns 31+ entities for a single slice:

get_subject_profile(project_key="petra", cycle=23,
                   subject="Finance - Gift Processing",
                   subject_kind="business_function")
→ { file_count: 279,
     bounded_contexts: [{ name: "DonationManagement", confidence: 0.84 }],
     business_rules: 7,
     implementation_constraints: 7,
     workflows: 3,
     entry_points: 4,
     integration_boundaries: 4,
     affinities: { "Donations Processing": 0.8,
                   "Finance - Accounting": 0.6 } }

Coexistence pattern evidence — two queries collapse weeks of file-reading:

get_entities_by_subject(subject="Finance - Gift Processing",
                       entity_type="entry_point")
→ 4 HTTP-routable entry points (TGiftTransactionWebConnector,
     AnnualReceiptGenerationInterface, GiftBatchManagementInterface,
     BankImportManagementInterface)
   ⇒ request-routing surface exists ⇒ SAROC ruled out

get_entities_by_subject(subject="Finance - Gift Processing",
                       entity_type="business_rule")
→ 7 rules including:
     BR-GIFT-001 GiftBatchSequentialNumbering (conf 0.95) - atomic ++
     BR-GIFT-002 GiftBatchFinancialPeriodValidation (conf 0.90) - period bind
     BR-GIFT-003 MultiCurrencyGiftProcessingRule (conf 0.83) - FX-snap
   ⇒ writes non-idempotent ⇒ symmetric dual-write ruled out

Result: classical-strangler-fig (middle branch of the decision tree)

Behavioral-rule extraction — one subject query returns the full catalog:

get_entities_by_subject(subject="Finance - Gift Processing",
                       entity_type="business_rule") +
get_entities_by_subject(subject="Finance - Gift Processing",
                       entity_type="implementation_constraint") +
get_entities_by_subject(subject="Donations Processing",
                       entity_type="business_rule")
→ 14 rules total (7 + 7 + 1 merged with GiftReceiptEligibility)
     confidence range 0.70-0.95, mean GWT confidence 0.78

search_files(file_name_regex=
    "csharp/ICT/Testing/lib/MFinance/server/Gift/.*\\.test\\.cs")
→ 7 legacy NUnit test files
   ⇒ 5 of 14 rules upgraded to code-inferred-test-corroborated

12.6 The Numbers

This run-004 analysis consumed approximately ~135 Concho Context Graph queries across all phases. Those queries provided structured intelligence covering 100% of the 572,757-line, 1,396-file codebase — every business function, every integration point, every behavioral rule, every architectural concern. The alternative would have been reading thousands of files and hoping to find what matters.

^(*) Platform-affinity runs consumed 0 direct Concho queries this cycle because they reused already-cataloged technology-subject and architectural-concern data from prior phases. This is a feature, not a gap: once a phase has surfaced the structural facts, downstream agents reason over them rather than re-query.

The estimated manual equivalent of 16–29 weeks represents the effort an experienced architect or modernization consultant would spend to produce an analysis of comparable depth and coverage — profiling all 27 subsystems, building the complete behavioral-rule catalog, mapping all integration points, auditing all dependencies, and designing the target architecture with evidence-based service decomposition. The Concho-assisted analysis achieved this in a fraction of the time, with higher coverage (100% vs sampling), quantified confidence scoring, and full auditability.

12.7 Conclusion: From Partial Analysis to Full Deep Insight

The Petra Finance – Gift Processing analysis demonstrates a fundamental transformation in legacy-modernization capability. Traditional approaches — whether manual or AI-assisted — are constrained to partial analysis: sampling representative files, inferring patterns from incomplete coverage, and accepting knowledge gaps as inevitable. Claude Code alone can accelerate this partial analysis but remains bound by context limits that force selective coverage (~5–15% of large codebases). When context windows are exceeded, LLMs tend to compensate by making things up and silently introducing hallucinations into the output.

Claude Code + Concho MCP eliminates partial analysis entirely. By providing pre-analyzed semantic intelligence across 100% of the codebase — business functions, architecture layers, behavioral rules, integration points, and confidence-scored relationships — Concho’s Context Graph transforms modernization from educated guesswork into systematic engineering. The difference isn’t just speed (~135 queries vs 16–29 weeks of architect time); it’s completeness, accuracy, and the discovery of critical patterns — like the three-file non-idempotent write evidence that selected the strangler-fig pattern — that partial analysis would miss entirely.

Every statistic in this report traces to a Concho query result. Every assertion about the legacy codebase is backed by structural evidence, not file sampling. Every comparison across subsystems covers all 27 candidates, not a convenient subset. This is what Concho’s Context Graph enables: not just faster analysis, but fundamentally more complete analysis — the kind that catches the non-idempotent write pattern before you commit to a coexistence strategy, finds all 14 behavioral rules before you start translating code, and evaluates all 27 subsystems before you pick the pilot.

Appendices

Advanced analysis and deployment artifacts

Appendix B: Target Service Architecture

B.1 Methodology

Service granularity for the Finance — Gift Processing subsystem was determined by running three independent architecture analyses in parallel, each applying a different lens to the same source-of-truth inputs (Section 4 fragment, the target-architecture handoff, and Concho codebase intelligence for cycle 23). Each lens produced a service-count recommendation, a service decomposition, and a self-assessed score against the four-dimension service-architecture rubric defined in the modernization-scoring skill (Operational Complexity 20%, Business Alignment 30%, Technical Soundness 30%, Change Velocity 20%).

B.2 Lens 1 — Domain-Driven Design Proposal

Concho cycle 23 confirms that the Gift Processing subsystem contains exactly one bounded context, DonationManagement, at confidence 0.84. A naive reading would conclude one bounded context implies one service. DDD as a discipline does not equate the two: within a single context there can be multiple aggregate clusters with different invariants, lifecycles, and consistency boundaries. The DDD analysis therefore looked one level deeper, at aggregate cohesion.

B.2.1 Aggregate Cluster Analysis

B.2.2 DDD Decision Rationale

• Different consistency boundaries. Gift posting is transactional ACID; receipt issuance is idempotent document generation. Mixing them inflates the transactional surface.
• Different change vectors. Receipt templates and tax-jurisdiction rules churn independently from the gift batch state machine.
• Different read/write characteristics. Gift Processing is mixed read/write under user-driven load; Receipt Generation is read-heavy bursty workload concentrated at year-end.
• Document artifact lifecycle. PDFs are external artifacts with retention obligations distinct from row-level gift data.

B.2.3 Rejected DDD Alternatives

DDD lens recommendation: 2 services. Self-assessed score 7.9 (OpComplexity 7, BusinessAlign 8, TechSoundness 9, ChangeVelocity 7).

B.3 Lens 2 — Technical Architecture Proposal

The Technical lens evaluated three dimensions in parallel: code coupling across the 279 source files, peak-load profiles for each capability, and deployment-independence requirements.

B.3.1 File-Clustering Analysis

B.3.2 Load-Profile Analysis

B.3.3 Deployment Independence

Gift Processing changes carry regression risk against the posting state machine and require slot-swap validation. Receipt Generation changes are template-driven (HTML, jurisdiction-specific tax rules) with low blast radius and ship more frequently. Coupling them forces every receipt-template tweak to redeploy the transactional core — an unnecessary operational tax.

Technical lens recommendation: 2 services. Self-assessed score 7.7 (OpComplexity 7, BusinessAlign 7, TechSoundness 9, ChangeVelocity 8).

B.4 Lens 3 — Business Capability Proposal

The Business lens scored capabilities by user workflow boundaries and the organizational owner. Non-profit finance teams have two distinct jobs-to-be-done in this subsystem.

B.4.1 Jobs-to-be-Done

B.4.2 Business Decision Rationale

• Different workflows, different cadences, different humans. Treating them as separate services aligns the technology to how the business actually operates.
• Brand surface. The receipt PDF is the one place in this subsystem where the non-profit's brand touches the donor directly. Coupling its release cycle to the transactional core is risky — a template hotfix during peak season should not require regression-testing the posting state machine.
• UI symmetry. The Angular UI naturally separates Annual Receipts into its own screen with its own information architecture. Backing it with its own service makes the UI/API symmetry clean and the audit story straightforward.

B.4.3 Rejected Business Alternatives

Business lens recommendation: 2 services. Self-assessed score 7.9 (OpComplexity 6, BusinessAlign 9, TechSoundness 8, ChangeVelocity 8).

B.5 Cross-Lens Scoring Matrix

All three lenses score above the 7.0 quality gate. The DDD and Business proposals tied at 7.9; the Technical proposal sat 0.2 below them. Per the modernization-scoring skill tiebreaker rule (scores within 0.5 points prefer business alignment), the Business proposal wins by procedure, but the practical result is moot — all three lenses propose the same two services with the same boundaries and the same answers to the four open questions. The convergence is genuine, not procedural.

B.6 Open-Question Resolutions

B.7 Target Service Specifications

B.7.1 Gift Processing API

B.7.1.1 REST Contract (representative endpoints)

# Gift batches
GET    /api/gift-processing/v1/batches?ledgerId=&status=&year=&period=
POST   /api/gift-processing/v1/batches
GET    /api/gift-processing/v1/batches/{batchId}
PATCH  /api/gift-processing/v1/batches/{batchId}
DELETE /api/gift-processing/v1/batches/{batchId}                    (only when Unposted)

# Gifts and details within a batch
POST   /api/gift-processing/v1/batches/{batchId}/gifts
PATCH  /api/gift-processing/v1/batches/{batchId}/gifts/{giftId}
POST   /api/gift-processing/v1/batches/{batchId}/gifts/{giftId}/details

# Posting state machine (the strangler routing key)
POST   /api/gift-processing/v1/batches/{batchId}/post
POST   /api/gift-processing/v1/batches/{batchId}/cancel

# Bank statement import (CAMT v053, MT940, CSV, ZIP)
POST   /api/gift-processing/v1/bank-imports        (multipart upload)
GET    /api/gift-processing/v1/bank-imports/{importId}

# Recurring gifts & SEPA mandates
GET    /api/gift-processing/v1/recurring-gifts?donorPartnerKey=
POST   /api/gift-processing/v1/recurring-gifts
PATCH  /api/gift-processing/v1/recurring-gifts/{recurringGiftId}

# Motivation administration
GET    /api/gift-processing/v1/motivations
POST   /api/gift-processing/v1/motivations
PATCH  /api/gift-processing/v1/motivations/{groupCode}/{detailCode}

# Read path consumed by Receipt Generation Service
GET    /api/gift-processing/v1/donors/{partnerKey}/posted-gifts?year=&ledgerId=
  

B.7.1.2 Sample C# Endpoint (Minimal API)

// Program.cs — Gift Processing API endpoint group
var batches = app.MapGroup("/api/gift-processing/v1/batches")
                 .RequireAuthorization()
                 .WithOpenApi();

batches.MapPost("/{batchId:int}/post", async (
    int batchId,
    IGiftBatchPostingService posting,
    ClaimsPrincipal user,
    CancellationToken ct) =>
{
    var result = await posting.PostBatchAsync(batchId, user.GetUserId(), ct);
    return result switch
    {
        PostingResult.Success s        => Results.Ok(s.PostedBatch),
        PostingResult.AlreadyPosted    => Results.Conflict(new ProblemDetails {
            Title = "Batch already posted",
            Status = StatusCodes.Status409Conflict
        }),
        PostingResult.PeriodClosed pc  => Results.Problem(
            title:  "Posting period closed",
            detail: $"Period {pc.Year}/{pc.Period} is closed for posting.",
            statusCode: StatusCodes.Status422UnprocessableEntity),
        PostingResult.PartnerInvalid p => Results.Problem(
            title: "Partner validation failed",
            detail: string.Join("; ", p.InvalidDonorKeys),
            statusCode: StatusCodes.Status422UnprocessableEntity),
        _                              => Results.Problem("Unknown posting result")
    };
})
.WithName("PostGiftBatch")
.Produces<GiftBatchDto>(200)
.Produces<ProblemDetails>(409)
.Produces<ProblemDetails>(422);
  

B.7.1.3 OpenAPI Excerpt — POST a Gift Batch

paths:
  /api/gift-processing/v1/batches:
    post:
      summary: Create a new (unposted) gift batch
      operationId: createGiftBatch
      tags: [GiftBatches]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGiftBatchRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GiftBatchDto'
        '422':
          description: Validation failure
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    CreateGiftBatchRequest:
      type: object
      required: [ledgerId, batchDescription, glEffectiveDate, currencyCode]
      properties:
        ledgerId:           { type: integer, example: 1 }
        batchDescription:   { type: string,  maxLength: 80 }
        glEffectiveDate:    { type: string,  format: date }
        currencyCode:       { type: string,  pattern: '^[A-Z]{3}$' }
        exchangeRateToBase: { type: number,  format: double }
  

B.7.2 Receipt Generation Service

B.7.2.1 REST Contract

# Single-donor receipt (synchronous)
POST /api/receipts/v1/receipts
  Body: { "donorPartnerKey": 12345, "taxYear": 2025, "ledgerId": 1, "jurisdictionCode": "DE" }
  201:  { "receiptId": "...", "sequenceNumber": "DE-2025-0042178",
          "blobUrl": "...", "issuedAt": "..." }

# Bulk annual run (asynchronous)
POST /api/receipts/v1/runs
  Body: { "ledgerId": 1, "taxYear": 2025, "jurisdictionCode": "DE" }
  202:  { "runId": "...", "statusUrl": "/api/receipts/v1/runs/{runId}" }

GET  /api/receipts/v1/runs/{runId}
  200:  { "runId": "...", "status": "InProgress|Completed|Failed",
          "totalDonors": 4821, "completed": 1840, "failed": 0,
          "startedAt": "...", "completedAt": null }

# Receipt retrieval
GET  /api/receipts/v1/receipts/{receiptId}
  200:  { "receiptId": "...", "donorPartnerKey": 12345,
          "taxYear": 2025, "sequenceNumber": "DE-2025-0042178",
          "blobUrl": "", "issuedAt": "...",
          "reissuedFrom": null }

# Reprint with audit trail
POST /api/receipts/v1/receipts/{receiptId}:reissue
  Body: { "reason": "Donor address corrected" }
  201:  { "receiptId": "", "sequenceNumber": "DE-2025-0042178-R1",
          "blobUrl": "...", "reissuedFrom": "" }

# Template registry
GET  /api/receipts/v1/templates?jurisdiction=&language=
PUT  /api/receipts/v1/templates/{templateId}
  

B.7.2.2 C# Interface for the Posted-Gifts Read Path

// Receipt Generation Service — outbound client to Gift Processing API
public interface IGiftProcessingClient
{
    Task<DonorPostedGifts> GetPostedGiftsAsync(
        long  partnerKey,
        int   taxYear,
        int   ledgerId,
        CancellationToken ct);
}

public sealed class GiftProcessingClient : IGiftProcessingClient
{
    private readonly HttpClient _http;        // Polly-decorated via AddHttpClient
    private readonly ILogger<GiftProcessingClient> _log;

    public GiftProcessingClient(HttpClient http, ILogger<GiftProcessingClient> log)
    {
        _http = http;
        _log  = log;
    }

    public async Task<DonorPostedGifts> GetPostedGiftsAsync(
        long partnerKey, int taxYear, int ledgerId, CancellationToken ct)
    {
        var url = $"/api/gift-processing/v1/donors/{partnerKey}/posted-gifts" +
                  $"?year={taxYear}&ledgerId={ledgerId}";

        var response = await _http.GetAsync(url, ct);
        response.EnsureSuccessStatusCode();

        var payload = await response.Content
            .ReadFromJsonAsync<DonorPostedGifts>(cancellationToken: ct);

        return payload
            ?? throw new InvalidOperationException("Empty posted-gifts payload");
    }
}

// DI registration with Polly resilience pipeline
builder.Services.AddHttpClient<IGiftProcessingClient, GiftProcessingClient>(client =>
    {
        client.BaseAddress = new Uri(builder.Configuration["GiftProcessing:BaseUrl"]!);
        client.DefaultRequestHeaders.Add("Accept", "application/json");
    })
    .AddPolicyHandler(GiftProcessingPolicies.RetryWithExponentialBackoff())
    .AddPolicyHandler(GiftProcessingPolicies.CircuitBreaker())
    .AddHttpMessageHandler<ManagedIdentityAuthHandler>();
  

B.7.2.3 Optional Async Envelope (Azure Service Bus, when provisioned)

# Azure Service Bus topic: receipts-bulk-run
# Subscription: receipt-generation-service
# Used only when bulk-run mode is > ~30 min synchronous or durable retry is required.

{
  "specversion": "1.0",
  "type":        "petra.receipts.donor-receipt-requested.v1",
  "source":      "/receipts/runs/r-2025-de-001",
  "id":          "msg-7c8b1a3e",
  "time":        "2026-01-15T03:42:11Z",
  "subject":     "donor/12345",
  "datacontenttype": "application/json",
  "data": {
    "runId":            "r-2025-de-001",
    "donorPartnerKey":  12345,
    "taxYear":          2025,
    "ledgerId":         1,
    "jurisdictionCode": "DE",
    "languageCode":     "de-DE"
  },
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}
  

B.8 Target Integration Architecture

graph LR
    SPA["Angular 20 SPA
(5 screens)"]
    FD["Azure Front Door
(WAF + TLS)"]
    APIM["Azure API Management
(strangler-fig routing)"]

    subgraph "Gift Processing (year-round, autoscale 2-4)"
        GIFT["Gift Processing API
(.NET 10 Minimal API)"]
    end

    subgraph "Receipt Generation (episodic, autoscale 1-6)"
        RCPT["Receipt Generation Service
(.NET 10)"]
    end

    PG[("Azure Database
for PostgreSQL")]
    REDIS["Azure Cache
for Redis"]
    BLOB["Azure Blob Storage
(bank files +
receipt PDFs)"]
    SB["Azure Service Bus
(optional, on-demand)"]

    LEGACY_PARTNER["Legacy Partner Service
(read-only)"]
    LEGACY_GL["Legacy GL Service
(one-way posting)"]

    SPA --> FD
    FD --> APIM
    APIM -->|"/api/gift-processing/*"| GIFT
    APIM -->|"/api/receipts/*"| RCPT

    GIFT --> PG
    GIFT --> REDIS
    GIFT --> BLOB
    GIFT -.->|"REST + Polly"| LEGACY_PARTNER
    GIFT -.->|"REST + Polly"| LEGACY_GL

    RCPT --> PG
    RCPT --> BLOB
    RCPT -->|"REST + Managed Identity
GET posted-gifts"| GIFT
    RCPT -.->|"optional, on-demand"| SB
    SB -.->|"optional"| RCPT

    classDef modern fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    classDef azure  fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef legacy fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dasharray:5
    classDef client fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px

    class SPA client
    class GIFT,RCPT modern
    class FD,APIM,PG,REDIS,BLOB,SB azure
    class LEGACY_PARTNER,LEGACY_GL legacy
  

Receipt Generation Service depends on Gift Processing API only via REST. Gift Processing API has zero awareness of receipt issuance — this is a strictly one-way dependency. Both services sit behind the same Azure API Management instance, share the same authentication surface (Microsoft Entra ID), and emit telemetry to the same Application Insights workspace. The optional Azure Service Bus path is dashed because it is provisioned only when bulk-run volume justifies it.

B.9 Implementation Roadmap

B.10 Quality Gate Result

Three lenses; three independent scores; all three above the 7.0 quality gate; convergent answers to all five open questions raised by the target-architecture phase. Composite score 7.8 / 10. Quality gate: PASS.

Appendix C: Deployment and Infrastructure

C.1 Deployment Overview

The runtime topology for Petra Finance — Gift Processing modernization is intentionally lean: two App Service plans, one Azure Database for PostgreSQL Flexible Server (shared across both services with separate schemas), one Azure Service Bus namespace (provisioned on demand), one Azure API Management instance (the strangler-fig surface), one Azure Cache for Redis, two Azure Blob Storage containers (SEPA exports + receipt PDFs), and one Application Insights workspace. Everything is provisioned through Bicep modules; nothing is created by hand.

The two App Services map 1:1 to the services defined in Appendix B: Gift Processing API hosts the .NET 10 Minimal API for batch entry, posting, recurring gifts, bank import, and motivation administration; Receipt Generation Service hosts the .NET 10 Minimal API plus QuestPDF rendering for annual tax receipts. Both services share the PostgreSQL server but own separate schemas (gift_processing, receipts) and connect via separate Managed Identities — the receipt service has no gift_processing schema permissions and reaches gift data only over REST.

Topology Diagram

flowchart TD
    SPA["Angular 20 SPA
(static in App Service)"]
    AFD["Azure Front Door
+ WAF policies"]
    APIM["Azure APIM
(strangler-fig surface)"]
    GIFT["Gift Processing API
App Service P1v3
slots: staging / prod"]
    RECEIPT["Receipt Generation API
App Service P1v3
autoscale 1-6 (Jan-Feb)"]
    LEGACY["Legacy Petra
.asmx (Mono)"]
    PG[("Azure PostgreSQL
Flexible Server
gift_proc + receipts schemas")]
    SB["Azure Service Bus
(on-demand, optional)"]
    BLOB[("Blob Storage
receipts + SEPA exports")]
    AI["Application Insights
+ Log Analytics workspace"]

    SPA --> AFD --> APIM
    APIM -->|"per-endpoint traffic shift"| GIFT
    APIM -->|"strangler routing"| LEGACY
    GIFT -->|"HTTP (Managed Identity)"| LEGACY
    GIFT --> PG
    GIFT -->|"HTTP (MI)"| RECEIPT
    RECEIPT --> BLOB
    RECEIPT --> SB
    SPA -. OTLP .-> AI
    GIFT -. OTLP .-> AI
    RECEIPT -. OTLP .-> AI

C.2 Infrastructure as Code (Bicep)

Infrastructure is declared in modular Bicep at infra/main.bicep with per-resource modules under infra/modules/. Below is the orchestrating main.bicep followed by the App Service module for Gift Processing API; the equivalent Receipt Generation module differs only in the resource names, autoscale window, and an extra Blob role assignment.

C.2.1 main.bicep

// infra/main.bicep
targetScope = 'subscription'

@description('Environment short name: dev, stg, prd')
param environment string = 'stg'

@description('Azure region')
param location string = 'westeurope'

@description('Project tag applied to every resource')
param project string = 'petra-gift'

var resourceGroupName = 'rg-${project}-${environment}'
var tags = {
  project:     project
  environment: environment
  owner:       'finance-modernization'
  costCenter:  'cc-modernization-2026'
}

resource rg 'Microsoft.Resources/resourceGroups@2024-03-01' = {
  name:     resourceGroupName
  location: location
  tags:     tags
}

module logAnalytics './modules/log-analytics.bicep' = {
  name:  'log-analytics'
  scope: rg
  params: {
    workspaceName: 'log-${project}-${environment}'
    location:      location
    tags:          tags
    retentionDays: 90
  }
}

module appInsights './modules/app-insights.bicep' = {
  name:  'app-insights'
  scope: rg
  params: {
    name:                'appi-${project}-${environment}'
    location:            location
    tags:                tags
    workspaceResourceId: logAnalytics.outputs.workspaceId
    samplingPercentage:  100
  }
}

module keyVault './modules/key-vault.bicep' = {
  name:  'key-vault'
  scope: rg
  params: {
    name:              'kv-${project}-${environment}'
    location:          location
    tags:              tags
    enableRbac:        true
    purgeProtection:   true
    softDeleteDays:    90
  }
}

module postgres './modules/postgres-flexible.bicep' = {
  name:  'postgres-flexible'
  scope: rg
  params: {
    name:                'psql-${project}-${environment}'
    location:            location
    tags:                tags
    sku:                 'Standard_D2ds_v5'
    storageGb:           32
    backupRetentionDays: 7
    aadAdminLogin:       'finance-mod-admins'
    aadAdminObjectId:    aadAdminGroupObjectId
  }
}

module serviceBus './modules/service-bus.bicep' = if (provisionServiceBus) {
  name:  'service-bus'
  scope: rg
  params: {
    namespaceName: 'sb-${project}-${environment}'
    location:      location
    tags:          tags
    sku:           'Standard'
    topicName:     'petra-receipts'
  }
}

module redis './modules/redis-cache.bicep' = {
  name:  'redis-cache'
  scope: rg
  params: {
    name:     'redis-${project}-${environment}'
    location: location
    tags:     tags
    sku:      'Standard'
    family:   'C'
    capacity: 1
  }
}

module storage './modules/storage-account.bicep' = {
  name:  'storage'
  scope: rg
  params: {
    name:     'st${replace(project, '-', '')}${environment}'
    location: location
    tags:     tags
    containers: [
      'receipts'
      'sepa-exports'
      'bank-statements'
    ]
    immutableRetentionDays: 2555  // 7-yr tax receipt retention
  }
}

module appSvcPlan './modules/app-service-plan.bicep' = {
  name:  'app-svc-plan'
  scope: rg
  params: {
    name:     'asp-${project}-${environment}'
    location: location
    tags:     tags
    sku:      'P1v3'
    capacity: 2
  }
}

module giftApi './modules/app-service-dotnet.bicep' = {
  name:  'gift-processing-api'
  scope: rg
  params: {
    appServiceName:      'app-gift-${environment}'
    planResourceId:      appSvcPlan.outputs.planId
    location:            location
    tags:                tags
    keyVaultName:        keyVault.outputs.name
    appInsightsKey:      appInsights.outputs.connectionString
    pgServerFqdn:        postgres.outputs.fqdn
    pgSchema:            'gift_processing'
    redisHost:           redis.outputs.host
    storageAccount:      storage.outputs.name
    storageContainers:   [ 'sepa-exports', 'bank-statements' ]
    autoscaleMin:        2
    autoscaleMax:        4
    healthCheckPath:     '/health/ready'
  }
}

module receiptsApi './modules/app-service-dotnet.bicep' = {
  name:  'receipts-api'
  scope: rg
  params: {
    appServiceName:      'app-receipts-${environment}'
    planResourceId:      appSvcPlan.outputs.planId
    location:            location
    tags:                tags
    keyVaultName:        keyVault.outputs.name
    appInsightsKey:      appInsights.outputs.connectionString
    pgServerFqdn:        postgres.outputs.fqdn
    pgSchema:            'receipts'
    redisHost:           redis.outputs.host
    storageAccount:      storage.outputs.name
    storageContainers:   [ 'receipts' ]
    autoscaleMin:        1
    autoscaleMax:        6
    healthCheckPath:     '/health/ready'
    extraAppSettings: {
      'GiftProcessing__BaseUrl':
        'https://app-gift-${environment}.azurewebsites.net'
      'GiftProcessing__Scope':
        'api://gift-${environment}/.default'
    }
  }
}

module apim './modules/api-management.bicep' = {
  name:  'apim'
  scope: rg
  params: {
    name:                'apim-${project}-${environment}'
    location:            location
    tags:                tags
    publisherEmail:      'modernization@example.org'
    publisherName:       'Finance Modernization'
    sku:                 'Developer'
    legacyBackendUrl:    'https://legacy-petra.example.org'
    modernBackendUrl:    giftApi.outputs.defaultHostname
    stranglerRoutingKey: 'posting-status'
  }
}

param aadAdminGroupObjectId string
param provisionServiceBus bool = false

C.2.2 app-service-dotnet.bicep (the reusable App Service module)

// infra/modules/app-service-dotnet.bicep
param appServiceName string
param planResourceId string
param location string
param tags object
param keyVaultName string
param appInsightsKey string
param pgServerFqdn string
param pgSchema string
param redisHost string
param storageAccount string
param storageContainers array
param autoscaleMin int
param autoscaleMax int
param healthCheckPath string
param extraAppSettings object = {}

var baseAppSettings = {
  'ASPNETCORE_ENVIRONMENT':         'Production'
  'ASPNETCORE_FORWARDEDHEADERS_ENABLED': 'true'

  // OpenTelemetry
  'OTEL_SERVICE_NAME':              appServiceName
  'OTEL_EXPORTER_OTLP_ENDPOINT':
    'https://${location}.applicationinsights.azure.com/v2/track'
  'APPLICATIONINSIGHTS_CONNECTION_STRING': appInsightsKey
  'OTEL_RESOURCE_ATTRIBUTES':
    'deployment.environment=${tags.environment}'
  'LOG_LEVEL':                      'Information'

  // PostgreSQL (Managed Identity, no password)
  'ConnectionStrings__GiftDb':
    'Host=${pgServerFqdn};Database=petra;Username=${appServiceName};SslMode=Require;Trust Server Certificate=true'
  'Postgres__Schema':               pgSchema
  'Postgres__UseManagedIdentity':   'true'

  // Redis
  'Redis__Host':                    redisHost
  'Redis__UseManagedIdentity':      'true'

  // Storage
  'Storage__AccountName':           storageAccount
  'Storage__Containers':            join(storageContainers, ',')

  // Key Vault references (resolved at runtime by App Service)
  'Entra__TenantId':
    '@Microsoft.KeyVault(VaultName=${keyVaultName};SecretName=EntraTenantId)'
  'Entra__ClientId':
    '@Microsoft.KeyVault(VaultName=${keyVaultName};SecretName=${appServiceName}-ClientId)'
}

resource app 'Microsoft.Web/sites@2024-04-01' = {
  name:     appServiceName
  location: location
  tags:     tags
  kind:     'app,linux'
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    serverFarmId:                planResourceId
    httpsOnly:                   true
    clientAffinityEnabled:       false
    publicNetworkAccess:         'Enabled'
    keyVaultReferenceIdentity:   'SystemAssigned'
    siteConfig: {
      linuxFxVersion:            'DOTNETCORE|8.0'
      alwaysOn:                  true
      http20Enabled:             true
      ftpsState:                 'Disabled'
      minTlsVersion:             '1.2'
      healthCheckPath:           healthCheckPath
      appSettings: [for setting in items(union(baseAppSettings, extraAppSettings)): {
        name:  setting.key
        value: setting.value
      }]
    }
  }
}

resource stagingSlot 'Microsoft.Web/sites/slots@2024-04-01' = {
  parent:   app
  name:     'staging'
  location: location
  tags:     tags
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    serverFarmId: planResourceId
    httpsOnly:    true
    siteConfig: {
      linuxFxVersion: 'DOTNETCORE|8.0'
      alwaysOn:       true
      healthCheckPath: healthCheckPath
      appSettings: [for setting in items(union(baseAppSettings, extraAppSettings)): {
        name:  setting.key
        value: setting.value
      }]
    }
  }
}

resource autoscale 'Microsoft.Insights/autoscalesettings@2022-10-01' = {
  name:     'autoscale-${appServiceName}'
  location: location
  tags:     tags
  properties: {
    enabled:          true
    targetResourceUri: planResourceId
    profiles: [
      {
        name: 'default'
        capacity: {
          minimum: string(autoscaleMin)
          maximum: string(autoscaleMax)
          default: string(autoscaleMin)
        }
        rules: [
          {
            metricTrigger: {
              metricName: 'CpuPercentage'
              metricResourceUri: planResourceId
              timeGrain: 'PT1M'
              statistic: 'Average'
              timeWindow: 'PT5M'
              timeAggregation: 'Average'
              operator: 'GreaterThan'
              threshold: 70
            }
            scaleAction: {
              direction: 'Increase'
              type: 'ChangeCount'
              value: '1'
              cooldown: 'PT5M'
            }
          }
          {
            metricTrigger: {
              metricName: 'CpuPercentage'
              metricResourceUri: planResourceId
              timeGrain: 'PT1M'
              statistic: 'Average'
              timeWindow: 'PT10M'
              timeAggregation: 'Average'
              operator: 'LessThan'
              threshold: 25
            }
            scaleAction: {
              direction: 'Decrease'
              type: 'ChangeCount'
              value: '1'
              cooldown: 'PT10M'
            }
          }
        ]
      }
    ]
  }
}

output principalId string = app.identity.principalId
output defaultHostname string = app.properties.defaultHostName

C.2.3 Key Vault references & Managed-Identity role assignments

// infra/modules/role-assignments.bicep
param keyVaultName string
param postgresServerName string
param storageAccountName string
param redisName string
param appPrincipalId string

// 1. Key Vault Secrets User
resource kvSecretsUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(keyVaultName, appPrincipalId, 'kv-secrets-user')
  scope: resourceId('Microsoft.KeyVault/vaults', keyVaultName)
  properties: {
    principalId:      appPrincipalId
    principalType:    'ServicePrincipal'
    roleDefinitionId: subscriptionResourceId(
      'Microsoft.Authorization/roleDefinitions',
      '4633458b-17de-408a-b874-0445c86b69e6')  // Key Vault Secrets User
  }
}

// 2. PostgreSQL: AAD-authenticated app login
//    (the actual SQL GRANT statements run as a post-deploy step via az cli)

// 3. Storage Blob Data Contributor
resource storageContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storageAccountName, appPrincipalId, 'storage-blob-contrib')
  scope: resourceId('Microsoft.Storage/storageAccounts', storageAccountName)
  properties: {
    principalId:      appPrincipalId
    principalType:    'ServicePrincipal'
    roleDefinitionId: subscriptionResourceId(
      'Microsoft.Authorization/roleDefinitions',
      'ba92f5b4-2d11-453d-a403-e96b0029c9fe')  // Storage Blob Data Contributor
  }
}

// 4. Redis Data Contributor
resource redisContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(redisName, appPrincipalId, 'redis-data-contrib')
  scope: resourceId('Microsoft.Cache/redis', redisName)
  properties: {
    principalId:      appPrincipalId
    principalType:    'ServicePrincipal'
    roleDefinitionId: subscriptionResourceId(
      'Microsoft.Authorization/roleDefinitions',
      'e0f68234-74aa-48ed-b826-c38b57376e17')  // Redis Cache Contributor
  }
}

C.3 CI/CD Pipeline (GitHub Actions)

The pipeline runs on every push to main and on PRs. Deploy steps use Azure OIDC federated credentials (no service-principal secrets); the production swap is gated by a deployment-environment approval.

# .github/workflows/deploy-gift-api.yml
name: Deploy Gift Processing API

on:
  push:
    branches: [ main ]
    paths:
      - 'src/Petra.GiftProcessing/**'
      - 'infra/**'
      - '.github/workflows/deploy-gift-api.yml'
  workflow_dispatch:

permissions:
  id-token: write   # OIDC federated credential
  contents: read

env:
  AZURE_RG:           rg-petra-gift-prd
  APP_NAME:           app-gift-prd
  DOTNET_VERSION:     '8.0.x'
  BICEP_FILE:         infra/main.bicep
  ARTIFACT_NAME:      petra-gift-api

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: ${{ env.DOTNET_VERSION }}
      - run: dotnet restore src/Petra.GiftProcessing.sln
      - run: dotnet build src/Petra.GiftProcessing.sln -c Release --no-restore
      - run: dotnet test  src/Petra.GiftProcessing.sln -c Release --no-build
                          --logger trx --collect:"XPlat Code Coverage"
      - run: dotnet publish src/Petra.GiftProcessing/Petra.GiftProcessing.csproj
                            -c Release -o ./publish --no-build
      - uses: actions/upload-artifact@v4
        with:
          name: ${{ env.ARTIFACT_NAME }}
          path: ./publish

  infra:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: azure/login@v2
        with:
          client-id:       ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id:       ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - name: What-if (preview)
        run: |
          az deployment sub what-if \
            --location westeurope \
            --template-file ${{ env.BICEP_FILE }} \
            --parameters environment=prd \
                         aadAdminGroupObjectId=${{ secrets.AAD_ADMIN_GROUP_ID }}
      - name: Deploy infra
        run: |
          az deployment sub create \
            --location westeurope \
            --template-file ${{ env.BICEP_FILE }} \
            --parameters environment=prd \
                         aadAdminGroupObjectId=${{ secrets.AAD_ADMIN_GROUP_ID }}

  deploy-staging:
    needs: [ build, infra ]
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: ${{ env.ARTIFACT_NAME }}
          path: ./publish
      - uses: azure/login@v2
        with:
          client-id:       ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id:       ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - name: Deploy to staging slot
        uses: azure/webapps-deploy@v3
        with:
          app-name: ${{ env.APP_NAME }}
          slot-name: staging
          package: ./publish

  smoke:
    needs: deploy-staging
    runs-on: ubuntu-latest
    steps:
      - name: Wait for health probe
        run: |
          for i in $(seq 1 30); do
            code=$(curl -s -o /dev/null -w "%{http_code}" \
              https://${{ env.APP_NAME }}-staging.azurewebsites.net/health/ready)
            if [ "$code" = "200" ]; then echo "ready"; exit 0; fi
            sleep 10
          done
          echo "health probe failed"; exit 1
      - name: API smoke
        run: |
          curl -fsS https://${{ env.APP_NAME }}-staging.azurewebsites.net/health/ready
          curl -fsS https://${{ env.APP_NAME }}-staging.azurewebsites.net/health/live
          curl -fsS https://${{ env.APP_NAME }}-staging.azurewebsites.net/api/gift-processing/v1/ledgers \
              -H "Authorization: Bearer ${{ secrets.SMOKE_TEST_TOKEN }}" \
              | jq '.items | length >= 1'

  swap-to-prod:
    needs: smoke
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: azure/login@v2
        with:
          client-id:       ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id:       ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - name: Slot swap
        run: |
          az webapp deployment slot swap \
            --resource-group ${{ env.AZURE_RG }} \
            --name ${{ env.APP_NAME }} \
            --slot staging --target-slot production

C.4 App Service Deployment Manifests

C.4.1 web.config (Linux In-Process / Kestrel front-loaded)

Even on Linux App Service the .NET 10 runtime expects a minimal web.config when long-running connections or custom forwarded-headers handling is needed. Kestrel runs in-process; nginx in front of it terminates TLS.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore"
             path="*" verb="*"
             modules="AspNetCoreModuleV2"
             resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\Petra.GiftProcessing.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess">
        <environmentVariables>
          <environmentVariable name="ASPNETCORE_ENVIRONMENT"
                               value="Production" />
          <environmentVariable name="ASPNETCORE_FORWARDEDHEADERS_ENABLED"
                               value="true" />
        </environmentVariables>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

C.4.2 Health probes (Minimal API)

// src/Petra.GiftProcessing/Program.cs (excerpt)
using Microsoft.Extensions.Diagnostics.HealthChecks;

builder.Services
  .AddHealthChecks()
  .AddNpgSql(
      builder.Configuration.GetConnectionString("GiftDb")!,
      name: "postgres",
      failureStatus: HealthStatus.Unhealthy,
      tags: new[] { "ready" })
  .AddRedis(
      builder.Configuration["Redis:Host"]!,
      name: "redis",
      failureStatus: HealthStatus.Degraded,
      tags: new[] { "ready" })
  .AddAzureBlobStorage(
      builder.Configuration["Storage:AccountName"]!,
      name: "blob",
      tags: new[] { "ready" })
  .AddCheck("self", () => HealthCheckResult.Healthy(),
      tags: new[] { "live" });

var app = builder.Build();

app.MapHealthChecks("/health/live", new HealthCheckOptions
{
  Predicate = c => c.Tags.Contains("live")
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
  Predicate = c => c.Tags.Contains("ready")
});

app.MapHealthChecks("/health/startup", new HealthCheckOptions
{
  Predicate = c => c.Tags.Contains("ready"),
  ResultStatusCodes = new Dictionary<HealthStatus, int>
  {
    [HealthStatus.Healthy]   = 200,
    [HealthStatus.Degraded]  = 200,
    [HealthStatus.Unhealthy] = 503
  }
});

C.5 Networking and Routing

Three layers in front of the App Services:

1. Azure Front Door — global TLS termination + WAF (OWASP Core Rule Set v3.2 + custom rule blocking known SOAP-injection patterns aimed at the legacy ASMX surface).
2. Azure API Management (Developer/Standard tier, depending on environment) — the strangler-fig surface. Per-endpoint routing policies live here: POST /api/gift-processing/v1/batches/{id}/post is the first endpoint shifted from legacy to modern; reads precede writes per Section 11. APIM policies inject the Managed Identity token into the upstream call and propagate the W3C traceparent header.
3. Private endpoints — PostgreSQL Flexible Server, Redis, Storage, Key Vault, and Service Bus all expose private endpoints into the App Service VNet integration subnet. No public network access on any data plane.

APIM policy fragment (strangler routing)

<policies>
  <inbound>
    <base />
    <!-- Strangler routing: send POST /batches/{id}/post
         to the modernized API; all other writes stay
         on legacy until their stage is reached -->
    <choose>
      <when condition="@(context.Request.Method == &quot;POST&quot; &amp;&amp;
                       context.Request.Url.Path.Contains(&quot;/post&quot;))">
        <set-backend-service base-url="https://app-gift-prd.azurewebsites.net" />
        <authentication-managed-identity resource="api://gift-prd" />
      </when>
      <otherwise>
        <set-backend-service base-url="https://legacy-petra.example.org" />
      </otherwise>
    </choose>
    <forward-request />
  </inbound>
  <outbound>
    <base />
    <set-header name="x-strangler-stage" exists-action="override">
      <value>posting-modernized</value>
    </set-header>
  </outbound>
</policies>

C.6 Observability

Observability runs on three concentric layers: in-process OpenTelemetry SDK, the App Service / platform metrics, and Application Insights as the unified backend. Logs, traces, and metrics all land in Application Insights via OTLP; Application Insights writes long-term storage to the shared Log Analytics workspace.

C.6.1 OpenTelemetry registration (Program.cs)

// src/Petra.GiftProcessing/Program.cs
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using OpenTelemetry.Metrics;
using OpenTelemetry.Logs;
using Azure.Monitor.OpenTelemetry.AspNetCore;

var otelResource = ResourceBuilder.CreateDefault()
  .AddService(
    serviceName:     builder.Configuration["OTEL_SERVICE_NAME"]!,
    serviceVersion:  ThisAssembly.AssemblyInformationalVersion)
  .AddAttributes(new Dictionary<string, object>
  {
    ["deployment.environment"] =
      builder.Configuration["ASPNETCORE_ENVIRONMENT"]!
  });

builder.Services
  .AddOpenTelemetry()
  .UseAzureMonitor(o =>
  {
    o.ConnectionString =
      builder.Configuration[
        "APPLICATIONINSIGHTS_CONNECTION_STRING"];
    o.SamplingRatio = 1.0f;
  })
  .ConfigureResource(r => r.AddService(
    builder.Configuration["OTEL_SERVICE_NAME"]!))
  .WithTracing(t => t
    .AddSource("Petra.*")
    .AddAspNetCoreInstrumentation()
    .AddHttpClientInstrumentation()
    .AddNpgsql())
  .WithMetrics(m => m
    .AddMeter("Petra.*")
    .AddAspNetCoreInstrumentation()
    .AddHttpClientInstrumentation()
    .AddRuntimeInstrumentation());

// Serilog -> structured JSON -> stdout -> App Insights
builder.Host.UseSerilog((ctx, lc) => lc
  .ReadFrom.Configuration(ctx.Configuration)
  .Enrich.FromLogContext()
  .Enrich.WithProperty("service",
    ctx.Configuration["OTEL_SERVICE_NAME"]!)
  .Enrich.WithCorrelationIdHeader("x-correlation-id")
  .WriteTo.Console(
    new Serilog.Formatting.Compact.RenderedCompactJsonFormatter()));

public static class Tracing
{
  public static readonly ActivitySource Source =
    new("Petra.GiftProcessing");
}

C.6.2 Application Insights queries (KQL)

// KQL — failed gift-batch posts last 24 hours, grouped by failure type
requests
| where timestamp > ago(24h)
| where name == "PostGiftBatch"
| where success == false
| extend problemType = tostring(customDimensions.["traceparent"])
| summarize count() by resultCode, problemType
| order by count_ desc

// KQL — receipt-generation throughput during year-end (Jan + Feb)
customEvents
| where name == "receipts.run.completed"
| extend year       = toint(customDimensions["taxYear"])
| extend donorCount = toint(customDimensions["donorCount"])
| extend durationMs = toint(customDimensions["durationMs"])
| project timestamp, year, donorCount, durationMs
| order by timestamp desc

// KQL — strangler-bridge end-to-end latency (P50/P95/P99)
dependencies
| where timestamp > ago(1h)
| where target == "legacy-petra.example.org"
| summarize
    p50 = percentile(duration, 50),
    p95 = percentile(duration, 95),
    p99 = percentile(duration, 99)
  by bin(timestamp, 5m)

C.6.3 OTEL Environment Variables (reference)

C.7 Secrets & Configuration (Key Vault references)

No secrets in appsettings.json, no secrets in environment variables, no secrets in pipeline output. Every secret is a Key Vault reference resolved by App Service at startup; rotation happens in Key Vault without redeploying the app.

All database connections (PostgreSQL, Redis) use Managed Identity — no passwords stored anywhere. The Bicep role-assignments module wires the System-Assigned Managed Identity of each App Service to the data services it needs.

C.8 Cost Estimates

Costs are illustrative for a single mid-size deployment in westeurope. Multi-region or sovereign-cloud deployments scale the App Service Plan and APIM lines proportionally; PostgreSQL replicas double the database cost. The bulk year-end receipt run scales the receipts App Service from 1 to 6 instances for ~6 weeks — ~€70 incremental.

C.9 Operational Runbook

Run-books live as Markdown in ops/runbooks/ alongside the code; each runbook ends with a "verify resolved" KQL snippet that confirms the metric returned to baseline.