Cognatix AI Modernization Stakeholder Review

1. Introduction

1.1 Purpose and Scope

This document presents a comprehensive modernization analysis for the Payment Processing subsystem within the Applewood Computers Accounting System (ACAS), examining the transformation path from legacy GnuCOBOL on Linux with dual ISAM/MySQL data storage and terminal-based UI architecture to AWS ECS Fargate infrastructure. The subsystem analyzed — Payment Processing — was selected by the customer, ensuring alignment with actual business modernization priorities.

The analysis addresses a critical business challenge facing organizations with decades-old COBOL systems: how to modernize proven financial logic while eliminating platform-imposed constraints that hinder productivity. ACAS represents a 48-year-old comprehensive business accounting platform serving small-to-medium businesses with terminal-based user interfaces and dual ISAM/MySQL data storage. The Payment Processing subsystem handles supplier payment entry and amendment, invoice appropriation with automatic discount calculation, payment proof sorting and reporting, cash posting with general ledger integration, payment generation with BACS and cheque support, and remittance advice production — critical financial operations requiring behavioral fidelity during migration while enabling modern user experience improvements and cloud-native scalability.

1.2 What Cognatix Provided

This report leverages two distinct Cognatix AI capabilities:

1. Pre-Built Legacy System Analysis: Before this migration report was generated, Cognatix performed deep analysis of the entire ACAS codebase — 1,358,687 lines across 623 files — discovering 36 business functions, 12 behavioral rules for Payment Processing, architectural layers, data dependencies, and platform constraints. This foundational analysis (conducted once for the entire codebase) provides the raw intelligence that makes rapid, accurate modernization planning possible.

2. Cognatix Migration Report Workflow: This document was generated in approximately two hours using Cognatix's modernization workflow, which leverages the pre-built analysis to produce customer-specific migration plans. The workflow combines Cognatix's pre-computed insights (business rules, constraints, dependencies) with AI-generated architecture designs, code translation examples, and deployment artifacts tailored to AWS ECS Fargate patterns. This two-stage approach — comprehensive upfront analysis followed by rapid report generation — explains why Cognatix can produce in hours what traditionally requires weeks of manual effort. A companion workflow leverages this migration plan to generate complete implementation artifacts including modernized source code, database schemas, UI components, Docker configurations, and deployment scripts, which can then be deployed directly to the target AWS environment.

The pre-built analysis achieved 100% code coverage (vs. 20-30% sampling in manual reviews), extracted 12 behavioral rules with source code traceability (e.g., PaymentAppropriationLogic in purchase/pl080.cbl:492), and discovered platform constraints like the 9-invoice allocation limit per supplier payment that modernization can eliminate. The migration workflow then used this intelligence to design a 3-microservice AWS architecture, generate PostgreSQL schemas, create Python code translations with behavioral rule cross-references, and document UI transformations from 80×24 terminal screens to responsive React web interfaces. All analysis outputs include confidence scores and evidence classification, enabling architects to understand the certainty behind each finding.

1.3 Report Organization

This report is organized to serve both strategic decision-makers and implementation teams:

• Section 1 — Introduction: Purpose, scope, and what Cognatix provided for this analysis.
• Section 2 — Migration Scope: Subsystem selection rationale and migration boundary definition.
• Section 3 — Legacy System Analysis: Comprehensive analysis of the current ACAS architecture, technology stack, business functions, and code organization as discovered by Cognatix.
• Section 4 — Target Architecture: Proposed AWS ECS Fargate microservice architecture with Python and PostgreSQL.
• Section 5 — Platform Affinity Analysis: Assessment of how ACAS COBOL patterns map to modern cloud-native equivalents.
• Section 6 — How Cognatix Helped This Migration Planning: Detailed account of Cognatix's role in accelerating and improving the analysis process.
• Section 7 — UI/UX Transformation Examples: Concrete examples of terminal-to-web interface modernization for Payment Processing screens.
• Section 8 — Code Translation Examples: Side-by-side COBOL-to-Python translations preserving behavioral fidelity.
• Section 9 — Data Mapping Strategy: ISAM/MySQL-to-PostgreSQL schema transformation with field-level mapping rules.
• Section 10 — Business Rules Analysis: Comprehensive catalog of Payment Processing behavioral rules with confidence scores and source traceability.
• Section 11 — Migration Strategy: Strangler-fig migration approach with phased cutover, dual-write implementation, and rollback procedures.
• Appendix A — Multi-Agent Subsystem Selection: Documentation of the consensus-based subsystem selection process.
• Appendix B — Service Architecture: Detailed microservice decomposition with API contracts and data ownership.
• Appendix C — Deployment: Docker containerization and AWS ECS Fargate deployment configurations.

2. Migration Scope

This report leverages Cognatix's deep insight into all 36 subsystems in the Applewood Computers Accounting System. 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 runs — each applying a different scoring emphasis (technology-driven, business-driven, and hybrid risk-mitigation) — unanimously selected the same candidate with near-identical scores, producing the strongest possible consensus signal.

Why Payment Processing is the right first migration:

• Right-sized for a pilot: 32 files with a well-bounded footprint — small enough to be tractable, yet complex enough to exercise the full transaction-processing pattern (data entry, validation, batch processing, GL posting, document generation).
• Clear integration boundaries: Only 4 integration points, all well-defined and unidirectional, making strangler-fig extraction straightforward.
• Data access already abstracted: The existing dual-storage Data Access Layer (ISAM/MySQL) separates business logic from storage, providing a significant head start for migration to PostgreSQL.
• High pattern reusability: Migration patterns established here apply directly to Sales Invoicing, Purchase Invoicing, Transaction Posting, and at least 3 other subsystems — accelerating the broader modernization program.
• Contained blast radius: If anything goes wrong, rollback is simple and no other subsystem is affected. Payment workflows are batch-oriented with natural reconciliation checkpoints.

See Appendix A for the complete three-run evaluation methodology, scoring tables for all 36 subsystems, and detailed rationale.

3. Legacy System Analysis

The following legacy system analysis was generated by Cognatix AI. This section presents findings from Cognatix's automated analysis of the Applewood Computers Accounting System (ACAS) codebase, providing the foundation for modernization planning. All findings were generated from Cognatix's Language-Agnostic Deep Scan — pre-analyzed semantic intelligence covering 100% of the 1,358,687 lines across 623 files.

3.1 System Overview

The Applewood Computers Accounting System (ACAS) is a comprehensive business accounting platform built in COBOL that has been in continuous development for over 48 years. The system handles the full spectrum of financial accounting operations including general ledger management, sales ledger, purchase ledger, stock control, and IRS tax compliance — serving small-to-medium businesses with a modular monolithic architecture that has evolved from traditional mainframe-era patterns to a modern GnuCOBOL implementation running on Linux.

ACAS implements a distinctive dual storage architecture, supporting both traditional ISAM (Indexed Sequential Access Method) files and MySQL/MariaDB relational databases through a runtime-configurable abstraction layer. This design allows operators to choose between file-based storage for simplicity and database storage for scalability, with transparent switching controlled by the FS-Cobol-Files-Used configuration flag. The system's terminal-based user interface operates through numbered menus, letter commands, and Escape key navigation across 80×24 character screens, providing access to all accounting modules.

The codebase spans 623 files totaling 1,358,687 lines of code, organized into a modular monolith with clear architectural layering. Cognatix identified 36 distinct business functions, 58 aggregate root entities, 46 bounded contexts, 205 business rules, and 131 integration points — revealing a rich domain model with well-defined business logic that has been refined over decades of operational use. The system's single-developer maintenance model and decades of continuous evolution have produced a codebase that, while architecturally sound, carries inherent modernization challenges including terminal UI constraints, COBOL skills scarcity, and platform-imposed data structure limitations.

3.2 Technical Architecture

Cognatix's architecture analysis reveals a well-structured modular monolith organized into nine top-level architectural layers. The Data Layer dominates with 332 files (53% of the codebase), reflecting the system's dual storage strategy that requires parallel implementations for ISAM file handlers and MySQL database access. The Application Layer contains 98 files implementing core business logic across ten functional domains, while the Cross-Cutting Concerns layer (33 files) provides shared utilities for error handling, authentication, date processing, and print configuration.

The architecture tree below shows the complete file distribution across all layers, as discovered by Cognatix:

The dominance of the Data Layer (53.3%) reflects the dual storage strategy — every data entity requires copybook definitions for ISAM file access, working storage definitions, database access modules (MT files), and often separate load (LD), unload (UNL), and restore (RES) utilities. This pattern means the data layer contains roughly 2× the file count of a single-storage system.

3.3 Technology Stack

The technology stack reveals several modernization-relevant characteristics. The dual storage architecture — supporting both ISAM files and MySQL/MariaDB through a runtime-configurable abstraction layer — demonstrates that ACAS has already partially evolved toward relational database patterns. This existing RDBMS support significantly reduces data migration risk, as many record structures already have MySQL table equivalents defined in ACASDB.sql. However, the C-based COBOL-to-MySQL bridge (cobmysqlapi) represents a fragile integration point that modern ORM patterns would replace entirely.

The terminal-based UI constraint (80×24 characters, 8 colors, numbered menu navigation) imposes significant limitations on data entry workflows. Payment Processing screens, for example, must limit invoice allocation displays to fit within these dimensions — a constraint directly reflected in the 9-invoice allocation limit per supplier payment. Modernization to responsive web interfaces removes these physical constraints while preserving the efficient keyboard-driven workflows that experienced operators depend on.

The copybook-based modularization pattern (fd*.cob for file definitions, ws*.cob for working storage, sel*.cob for file selection) provides clean data structure separation that maps well to modern class/model definitions. The consistent naming convention across 137 COBOL file definitions creates a predictable pattern for automated code translation.

3.4 Business Functions

Cognatix identified 36 distinct business functions within the ACAS codebase, each mapped to specific source files with confidence scores:

The business function distribution reveals a system organized around four major accounting domains — General Ledger, Sales, Purchase, and Stock — with Payment Processing as a critical cross-cutting capability that integrates with both the Sales and Purchase ledgers. Database Operations is the largest function by file count (86 files), reflecting the dual storage architecture's requirement for parallel data access implementations. The Payment Processing subsystem selected for this analysis encompasses 31 strongly-associated files spanning data entry (pl080, sl080), amendment (pl085, sl085), proof sorting (pl090, sl090), cash posting (pl100, sl100), payment generation (pl910-pl960), and supporting copybooks and data access layers.

Cognatix identified 58 aggregate root entities across the system, with the following key entities and their relationships forming the core domain model:

The entity relationship diagram above shows the top aggregate roots as discovered by Cognatix, with relationship counts and confidence scores. The Payment entity (highlighted as the focus of this analysis) connects to Suppliers, Purchase Invoices, and Batches, while integrating with the General Ledger through cash posting transactions. The average confidence across all 58 aggregate roots is 0.82, with 98% backed by STRUCTURAL evidence — indicating high reliability in the domain model.

3.5 Code Organization

ACAS follows a consistent file naming convention that Cognatix identified across the codebase, enabling automated discovery of component responsibilities:

The directory structure mirrors the module organization: general/ for GL, sales/ for Sales Ledger, purchase/ for Purchase Ledger, stock/ for Stock Control, irs/ for Tax Processing, common/ for shared data access and file handler modules, and copybooks/ for all shared data structure definitions. Each module directory includes its own compilation scripts (comp-*.sh) supporting multiple build modes: standard MySQL-enabled, non-RDBMS (file-only), and diagnostic variants.

3.6 Current Challenges

Cognatix's analysis of the ACAS codebase identified several technical challenges that drive the modernization imperative:

• Terminal UI Constraints: The 80×24 character terminal interface limits data density and user experience. Payment Processing screens must compress complex allocation workflows into fixed-width displays, leading to structural limitations like the 9-invoice allocation limit per supplier payment (defined in copybooks/fdpay.cob:21 as a repeating group of 9 payment line items). Modern web interfaces remove these physical constraints entirely.
• Dual Storage Complexity: Supporting both ISAM and MySQL backends doubles the data access code footprint. Every data entity requires parallel file handler (acas*.cbl), database access (*MT.cbl), load (*LD.cbl), unload (*UNL.cbl), and restore (*RES.cbl) implementations — contributing to the Data Layer comprising 53.3% of all files. Consolidating to a single modern database eliminates this duplication.
• COBOL Skills Scarcity: The system's single-developer maintenance model and reliance on COBOL expertise creates business continuity risk. With 449 COBOL files and 48+ years of accumulated domain knowledge, attracting and retaining qualified maintainers becomes increasingly difficult. Migration to Python opens the talent pool significantly.
• Fixed Record Structure Limitations: COBOL's fixed-length record definitions (e.g., 118-byte payment sort records, 645-byte cheque records, 113-byte open item records) impose rigid data models. Adding fields or extending capacities requires careful byte-level coordination across file definitions, working storage, and database schemas. Modern schema-based storage eliminates these constraints.
• Authentication Weakness: The custom cipher-based authentication system uses 4-character passwords with predictable quadratic encoding and a 26-character substitution cipher. Modern authentication frameworks (OAuth2, JWT) provide vastly superior security without custom cryptographic implementations.
• Limited Integration Capability: While the system supports 131 integration points, the dominant patterns are file-based (48 points, 37%) and internal RPC (38 points, 29%). Modern API-first architecture would expose business capabilities through RESTful interfaces, enabling ecosystem integration that terminal-based systems cannot support.
• Batch Processing Dependencies: Critical operations like batch status lifecycle (open → closed → cleared), end-of-cycle processing, and year-end backup sequences follow rigid sequential workflows. Cloud-native patterns can parallelize many of these operations while maintaining transactional integrity.
• Testing Infrastructure Gap: Only 5 files (0.8% of the codebase) are dedicated to testing. The dual storage architecture and terminal-based UI make automated testing particularly challenging. Modernization enables comprehensive test automation from the ground up.

3.7 Business Rules Summary

Cognatix's Language-Agnostic Deep Scan identified 7 behavioral rules specific to the Payment Processing subsystem, extracted from 6 source files spanning payment entry, proof validation, cash posting, payment generation, and remittance advice output. Three rules carry high confidence scores (≥ 0.75), reflecting strong structural and convergence evidence from multiple analysis clusters. The remaining four supporting rules provide additional coverage of payment method routing, unapplied balance handling, aging calculations, and remittance formatting.

Rule Distribution

Platform Behavior Changes

Full business rule specifications with COBOL source, Python translations, and Given-When-Then analysis are documented in Section 10: Business Rules Analysis.

For detailed data mapping from legacy structures to the target data model, see Section 9: Data Mapping Strategy.

4. Target Architecture

This section defines the target AWS ECS Fargate architecture for the modernized Payment Processing subsystem (32 files, ~14,000 LOC), including technology stack, code-level architecture decisions, data model, and migration strategy. A multi-agent service architecture analysis determined the optimal architecture: 3 microservices (Payment API, Payment Batch, and Reporting) for this migration.

The 3-service architecture was selected through consensus of Domain-Driven Design, Technical Architecture, and Business Architecture analyses, achieving a decision score of 7.65/10 (threshold: 7.0). The Technical proposal was selected as the tiebreaker winner over the Business proposal based on superior technical soundness. The workload-based decomposition separates interactive payment operations, batch processing, and read-only reporting into independently deployable and scalable services. The architecture was designed using Cognatix AI's deep structural analysis of the 32 Payment Processing files, 24 entities, 6 business rules, and 4 integration boundaries identified during subsystem selection.

4.1 Architecture Overview

The modernized Payment Processing subsystem replaces the existing COBOL programs (pl080–pl100, sl080–sl100, pl900–pl960) with a containerized Python application deployed on AWS ECS Fargate. The architecture preserves the single bounded context identified by Cognatix — PaymentProcessing (confidence 0.77) — while decomposing monolithic COBOL programs into well-defined API endpoints organized around the existing workflow stages: data entry, validation, appropriation, proof generation, cash posting, and amendment.

The target design leverages the natural migration seam already present in the legacy system: the acas032 dual-mode file handler (650 LOC), which abstracts ISAM and MySQL access behind a common interface using standardized file function codes (1=open, 2=close, 3=read-next, 4=read-indexed, 5=write, 7=rewrite, 8=delete, 9=start). This abstraction maps directly to a modern repository pattern backed by PostgreSQL, enabling a clean strangler-fig migration without disrupting the existing data access contract.

Key Architecture Principles

• API-First Design: All payment operations are exposed through versioned RESTful APIs with OpenAPI documentation auto-generated from Pydantic models, replacing terminal-based menu navigation (pl900's 6-option menu) with structured HTTP endpoints.
• Domain-Driven Boundaries: The single aggregate root (Payment, confidence 0.90) and single bounded context (PaymentProcessing) inform service boundaries. The 6 business rules (PaymentAppropriationLogic, PaymentPostingValidation, PaymentBatchControlLimits, RemittanceAdviceProcessingRules, UnappliedBalanceAllocation, PaymentAgeCalculation) and 4 integration boundaries are preserved as explicit domain logic rather than embedded in procedural COBOL paragraphs.
• Event-Driven Integration: General Ledger posting and remittance advice generation — currently implemented as synchronous COBOL CALL statements — become asynchronous event-driven integrations via Amazon EventBridge, decoupling payment processing from downstream consumers.
• Observability by Default: Every service includes OpenTelemetry distributed tracing, structured JSON logging via structlog with correlation IDs, and health check endpoints (readiness, liveness, startup) for container orchestration — capabilities entirely absent from the legacy terminal-based system.
• Infrastructure as Code: All infrastructure — ECS task definitions, RDS instances, EventBridge rules, ALB configuration — is defined declaratively, enabling repeatable deployments across environments.
• Progressive Migration: The strangler-fig pattern ensures zero-disruption migration with legacy remaining authoritative during transition, dual-write synchronization, and per-phase rollback capability.

4.2 Target Architecture Diagram

graph TB
    subgraph Client["Client Layer"]
        WebUI["Payment Processing UI
(React SPA)"]
    end

    subgraph AWS["AWS Cloud"]
        ALB["Application Load Balancer"]

        subgraph ECS["ECS Fargate Cluster"]
            SVC1["Payment API Service
(FastAPI)"]
            SVC2["Payment Batch Service
(FastAPI)"]
            SVC3["Reporting Service
(FastAPI)"]
        end

        subgraph Data["Data Layer"]
            RDS[("PostgreSQL RDS
payments, open_items,
batch_control")]
        end

        subgraph Integration["Integration Layer"]
            EB["Amazon EventBridge"]
            SM["AWS Secrets Manager"]
        end

        subgraph Observability["Observability"]
            CW["CloudWatch Logs"]
            OTEL["OpenTelemetry
Collector"]
        end
    end

    subgraph Legacy["Legacy System (Interim)"]
        COBOL["COBOL Payment Programs
(pl080-pl960, sl080-sl100)"]
        LegacyDB[("MySQL / ISAM
Legacy Storage")]
    end

    subgraph External["External Integration"]
        GL["General Ledger
Subsystem"]
        RA["Remittance Advice
Generation"]
    end

    WebUI --> ALB
    ALB --> SVC1
    ALB --> SVC2
    ALB --> SVC3

    SVC1 --> RDS
    SVC2 --> RDS
    SVC3 --> RDS

    SVC1 --> EB
    SVC2 --> EB
    SVC1 --> SM
    SVC2 --> SM
    SVC3 --> SM

    EB --> GL
    EB --> RA

    SVC1 -.->|"Dual-Write
(Phase 2)"| LegacyDB
    COBOL -.->|"Read-Only
(Phase 1)"| RDS

    SVC1 --> OTEL
    SVC2 --> OTEL
    SVC3 --> OTEL
    OTEL --> CW

    style Client fill:#f5efe4,stroke:#1a4442,color:#1a4442
    style AWS fill:#ffffff,stroke:#1a4442,color:#1a4442
    style ECS fill:#c4dad2,stroke:#1a4442,color:#1a4442
    style Data fill:#89c5b8,stroke:#1a4442,color:#1a4442
    style Integration fill:#f4c4b8,stroke:#1a4442,color:#1a4442
    style Observability fill:#e8a598,stroke:#1a4442,color:#1a4442
    style Legacy fill:#f5efe4,stroke:#999,color:#666,stroke-dasharray: 5 5
    style External fill:#f5efe4,stroke:#1a4442,color:#1a4442
        

4.3 Technology Stack

The technology stack was selected to maximize developer productivity and operational reliability while minimizing migration risk. Python and FastAPI were chosen for their strong typing support (via Pydantic), which directly maps to COBOL's strict data typing — every PIC X(N) and PIC S9(N)V9(M) field has a corresponding Pydantic model with equivalent validation constraints.

PostgreSQL replaces the dual-mode ISAM/MySQL storage currently abstracted by the acas032 file handler. The legacy system's COBOL file definitions (copybooks such as fdpay.cob, wspay.cob, plwspay.cob) and 2 database access modules (paymentsMT.cbl at 2,021 LOC and paymentsMT.scb at 1,471 LOC) consolidate into SQLAlchemy models with Alembic-managed migrations. This eliminates the dual-storage complexity while preserving the data access abstraction that already exists as a natural architectural seam.

Amazon EventBridge replaces the synchronous inter-program CALL mechanism used for General Ledger posting and IRS compliance. This decoupling means payment processing no longer blocks on GL batch record creation, improving throughput while maintaining eventual consistency through event replay and dead-letter queues.

4.3.1 Code-Level Architecture Decisions

The following table documents the code-level conventions that all Payment Processing services must follow. These decisions are derived from the resolved target patterns (skill defaults for the ECS Fargate platform with no plan-level overrides) and govern all code examples in subsequent sections.

4.4 Data Model

The target data model consolidates the legacy dual-mode storage (ISAM files + MySQL tables) into a single PostgreSQL schema. The model preserves the Payment aggregate root (confidence 0.90) and its relationships to open items, batch control records, and ledger accounts as identified by Cognatix's entity analysis. The 24 entities discovered by Cognatix in the Payment Processing subsystem are mapped to 5 core PostgreSQL tables that capture the full payment lifecycle.

erDiagram
    PAYMENT {
        uuid id PK
        varchar payment_reference
        int transaction_type
        date payment_date
        varchar supplier_code FK
        varchar customer_code FK
        decimal gross_amount
        decimal discount_amount
        decimal net_amount
        int batch_number FK
        int payment_flag
        varchar payment_method
        varchar cheque_number
        varchar bank_reference
        timestamp created_at
        timestamp updated_at
    }

    OPEN_ITEM {
        uuid id PK
        uuid payment_id FK
        varchar invoice_reference
        int folio_number
        date invoice_date
        decimal invoice_amount
        decimal applied_amount
        decimal discount_taken
        decimal deduction_amount
        int age_days
        varchar age_bucket
        varchar transaction_type
        timestamp created_at
    }

    BATCH_CONTROL {
        int batch_number PK
        date batch_date
        int item_count
        decimal batch_total
        varchar batch_status
        varchar created_by
        timestamp created_at
        timestamp closed_at
    }

    GL_POSTING {
        uuid id PK
        uuid payment_id FK
        int batch_number FK
        varchar debit_account
        varchar credit_account
        decimal amount
        varchar posting_reference
        boolean posted
        timestamp posted_at
    }

    PAYMENT_AUDIT {
        uuid id PK
        uuid payment_id FK
        varchar action
        jsonb old_values
        jsonb new_values
        varchar performed_by
        timestamp performed_at
    }

    PAYMENT ||--o{ OPEN_ITEM : "appropriates"
    PAYMENT }o--|| BATCH_CONTROL : "belongs to"
    PAYMENT ||--o{ GL_POSTING : "generates"
    PAYMENT ||--o{ PAYMENT_AUDIT : "tracks"
    BATCH_CONTROL ||--o{ GL_POSTING : "groups"
        

For detailed schema mappings from legacy COBOL copybooks to this target data model, see Section 9: Data Mapping Strategy.

5. Platform Affinity Analysis

Platform affinity analysis is a critical step in any legacy modernization. The goal is to classify each constraint discovered in the legacy codebase as either platform-driven (an artifact of the GnuCOBOL/Linux/ISAM environment that serves no business purpose) or business-driven (a genuine requirement that must be preserved). Getting this distinction wrong leads to one of two failure modes: replicating unnecessary limitations in the modern system, or accidentally breaking business rules that were disguised as platform constraints.

Cognatix's Language-Agnostic Deep Scan identified 188 implementation constraints across the entire ACAS codebase and 3 high-confidence constraints specific to the Payment Processing subsystem. This section examines each constraint category, classifies its driver, and recommends a disposition for the target Python/PostgreSQL architecture on AWS ECS Fargate.

5.1 Capacity Constraints

5.1.1 Invoice Allocation Limit (OCCURS 9 TIMES)

03  filler           occurs 9.
    05  Pay-Folio    pic 9(8)  comp.
    05  Pay-Period   pic 99    comp.
    05  Pay-Value    pic s9(7)v99  comp-3.
    05  Pay-Deduct   pic s999v99   comp-3.
    05  Pay-Invoice  pic x(10).

03  filler           occurs 9.
    05  c-inv        pic x(10).
    05  c-inv-filler pic x.
    05  c-folio      pic x(8).
    05  c-folio-fil  pic x.
    05  c-value      pic x(10).
    05  c-last       pic x.

5.1.2 Batch Size Limit (99 Items per Batch)

if       items = 99
         perform  bl-close
         perform  bl-open.

5.1.3 Cheque Number Field Limit (9 Characters)

5.1.4 Supplier Address Limit (5 Lines × 32 Characters)

5.2 Processing Model Constraints

5.2.1 Record Structural Integrity Validation (Byte-Length Matching)

move function length (Open-Item-Record-5)
                              to ws-ITM5-Length.
move function length (Sort-Record)
                              to ws-ITMS-Length.
if   ws-ITM5-Length NOT = ws-ITMS-Length
     display PL143 at 1201
     exit program
end-if

5.2.2 Transaction Type Filtering (Hard-Coded Exclusion List)

if       oi-type = 1 or 3
         go to process-input.
if       zero = oi-b-nos and oi-b-item
         go to process-input.

5.2.3 Dual-Storage Architecture Abstraction (ISAM/MySQL)

5.2.4 Sequential File-Mode Sorting (COBOL SORT Verb)

Platform vs Business Driver Analysis

5.3 User Interface Constraints

5.3.1 Terminal Color Palette (8 Colors)

78  COB-COLOR-BLACK    VALUE 0.
78  COB-COLOR-BLUE     VALUE 1.
78  COB-COLOR-GREEN    VALUE 2.
78  COB-COLOR-CYAN     VALUE 3.
78  COB-COLOR-RED      VALUE 4.
78  COB-COLOR-MAGENTA  VALUE 5.
78  COB-COLOR-YELLOW   VALUE 6.
78  COB-COLOR-WHITE    VALUE 7.

5.3.2 Fixed Screen Position Error Display

5.4 Data Type Constraints

5.4.1 Implicit Decimal Precision (PIC 9(7)V99 COMP-3)

5.4.2 Numeric Date Fields (PIC 9(8) COMP)

5.4.3 Fixed-Length Record Structures (645-byte Cheque Record)

← Back to Table of Contents

6. How Cognatix Helped This Migration Planning

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

6.1 Analysis at a Glance

The Applewood Computers Accounting System (ACAS) comprises 623 files totaling 1,358,687 lines of code across 36 business functions and 34 technology subjects. Cognatix's Language-Agnostic Deep Scan transformed this raw COBOL codebase into structured, queryable intelligence — enabling the multi-agent planning workflow to evaluate all 36 subsystems, select Payment Processing through 3-run consensus, design a 3-service target architecture, and extract 7 behavioral rules with source-verified confidence scores, all within a single automated session.

6.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.

6.2.1 Architecture Mapping

6.2.2 Subsystem Classification

6.2.3 Integration Analysis

6.2.4 Code Quality Assessment

6.2.5 Migration Complexity Estimation

6.2.6 Behavioral Rules Extraction

6.3 Why Language-Agnostic Deep Scan 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.

Consider the most compelling discovery from this analysis: the OCCURS 9 constraint. The 9-invoice allocation limit starts in a COBOL copybook (fdpay.cob:22) as a record structure definition. It propagates into the remittance advice output program (pl960.cbl:130) as a cheque record format. It manifests in the file handler (acas032.cbl:569) as a byte-length validation. And it constrains every payment entry program (pl080.cbl, sl080.cbl) that references the payment record. That is four different files across three different architectural layers (Data, Application, Cross-Cutting) — all enforcing the same constraint.

A tool analyzing one file at a time cannot see this full picture, and worse, it does not know to look for it. If Claude Code reads pl960.cbl and sees OCCURS 9, it correctly identifies a 9-item limit in the remittance advice. But without Cognatix's pre-computed intelligence, it has no way to know that this same limit also exists in the payment record copybook, the file handler, and every program that references the payment structure. It might recommend fixing the remittance advice format while leaving the underlying data structure constraint in place — a migration that looks correct in isolation but fails in integration.

The advantage of Cognatix's Language-Agnostic Deep Scan is that the planning agent instantly has access to the full gamut of business flows, behavioral rules, architecture layers, and integration points — at both business and technology levels — across 100% of the codebase. It does not start by reading files; it starts by knowing what exists. It retrieves actual source code if and only if needed to verify an assertion the Cognatix 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.”

6.4 Specific Examples from This Analysis

6.4.1 Subsystem Selection: 3-Run Consensus Across 36 Subsystems

The multi-agent candidate selection process evaluated all 36 business functions across three independent scoring runs — technology-driven, business-driven, and hybrid risk-mitigation. Each run queried Cognatix for subsystem profiles, entity counts, integration boundaries, and business rules. The result was a unanimous 3/3 consensus selecting Payment Processing with scores of 3.50, 3.50, and 3.49 respectively.

6.4.2 Behavioral Rules: 7 Rules with Source-Verified Confidence

Cognatix's entity analysis identified 205 business rules across the full ACAS codebase and 12 specific to Payment Processing. The behavioral rules agent extracted 7 rules for the migration plan, each verified against actual COBOL source code. The highest-confidence rule — PaymentRecordStructuralIntegrity at 0.93 — was confirmed through convergence of 2 independent entity analyses with a combined convergence confidence of 0.95.

6.4.3 Service Architecture: Multi-Agent Consensus with Entity-Level Data

The service architecture phase used Cognatix's entity-level data to evaluate three decomposition proposals: DDD-based (2 services), Technical workload-based (3 services), and Business ownership-based (3 services). The Technical and Business proposals tied at 7.65, with the Technical proposal selected for superior technical soundness (8.5 vs 6.5). This data-driven decision was possible because Cognatix provided precise entity inventories: 24 entities, 6 business rules, 4 integration boundaries, and 2 workflows — enabling the agents to reason about service boundaries at the entity level rather than guessing from file names.

6.4.4 Platform Constraint Discovery: Cross-Layer Constraint Propagation

Cognatix's Language-Agnostic Deep Scan identified 188 implementation constraints across the ACAS codebase — 3 high-confidence constraints specific to Payment Processing. The platform affinity analysis (Section 5) classified 13 constraints into ELIMINATE, HYBRID, and PRESERVE categories. The OCCURS 9 constraint exemplifies the value of pre-computed codebase intelligence: it was discovered as a single entity (RemittanceAdviceFormatLimitations, confidence 0.88) that Cognatix had already traced across multiple files and layers. Without this pre-analysis, discovering that the same 9-invoice limit appears in the copybook, the print program, and the file handler would require reading and correlating those files independently.

6.5 The Cumulative Advantage

Each phase of this analysis built on the intelligence gathered by previous phases — a cumulative advantage that compounds with project complexity. The project intelligence phase profiled all 36 subsystems; the candidate selection phase used those profiles to score and rank every subsystem; the target architecture phase used the selected subsystem's entity inventory to design the data model and migration strategy; the service architecture phase used integration boundaries and business rules to determine optimal service decomposition; the behavioral rules phase used entity-level business rules to generate Given-When-Then specifications; and the platform affinity analysis used implementation constraints to classify every legacy limitation.

This chain of dependent analyses was possible because Cognatix's Language-Agnostic Deep Scan provides a stable, comprehensive, queryable foundation that every phase can build upon. Without it, each phase would need to start from scratch — re-reading files, re-discovering patterns, re-building context — with no guarantee of consistency between phases.

6.6 What This Means for Your Migration

The depth and breadth of this analysis — 36 subsystems evaluated, 7 business rules with source-verified confidence scores, 13 platform constraints classified, 3 service architecture proposals compared — would be impractical to produce manually for a 1.36 million-line COBOL codebase. Even with Claude Code's AI-powered code analysis, the absence of pre-computed codebase intelligence would reduce coverage from 100% to approximately 10–15%, with corresponding gaps in integration mapping, constraint discovery, and behavioral rule extraction.

Cognatix's Language-Agnostic Deep Scan does not replace human judgment — it replaces the weeks of manual code reading required to inform human judgment. Every decision in this report — from subsystem selection to service boundary design to platform constraint classification — is backed by quantified evidence from the full codebase, not sampled approximations.

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

← Back to Table of Contents

7. UI/UX Transformation Examples

This section demonstrates the user interface transformation from legacy 80×24 COBOL terminal screens to modern web-based interfaces. Each example shows the actual legacy screen layout (verified against COBOL source code via Cognatix), the equivalent modern React component, and the platform affinity improvements that the new interface delivers. The Payment Processing subsystem provides particularly compelling transformation examples because the legacy workflow requires navigating between six separate programs through a numbered menu (PL900), while the modern system consolidates the entire payment lifecycle into a single unified view.

7.1 UI Affinity Analysis

Before examining individual screen transformations, the following analysis maps legacy UI constraints to modernization opportunities. Every element traces to actual COBOL source code discovered by Cognatix.

7.2 PL900 — Payment Processing Menu

The Payment Processing Menu (PL900) is the entry point for all payment operations. It presents a numbered menu with 6 options plus an exit command. In the modern system, this menu is replaced entirely by URL-based routing through the React SPA sidebar navigation.

PL900 (3.02.05)     Payment Menu   07/03/2026


Select one of the following by number :- [ ]


(1)  Generate Payments to be made

(2)  Amend Payments

(3)  Proof Payments

(4)  Generate Payments

(5)  Print Payment Register

(6)  Print remittance advices


(X)  Return to system menu

7.3 PL080 — Payment Data Entry

Payment Data Entry (PL080) is the most complex interactive screen in the Payment Processing subsystem. It handles supplier lookup, payment amount entry, batch assignment, and the invoice appropriation workflow. The screen layout is constrained to the 80×24 terminal grid with a fixed header area and a scrolling invoice list that begins at row 12.

PL080 (3.02.06)   Payment Data Entry  07/03/26


ACME Corporation Ltd
****************************************
*Date  [07/03/2026]*A/C Nos   [ACME001]*
***                                  ***
*Value [15847.50   ]*Batch   [    1/  1]*
****************************************

Current Balance -   15,847.50
-------------------------------------------
Folio No  --Date--  --Amount-- Deductable
   48271  07/01/26   3,250.00    00.00
   48356  15/01/26   2,890.00    00.00
   48412  28/01/26   4,125.50    00.00
   48503  10/02/26   2,340.00    46.80
   48621  22/02/26   1,895.00    37.90
   48744  03/03/26   2,347.00    00.00



Enter further payments? (Y/N)  [Y]

7.4 PL015 — Purchase Ledger Enquiry

The Purchase Ledger Enquiry (PL015) provides a read-only view of supplier account details, transaction history, and aging analysis. In the legacy system, this is a separate program accessed from the purchase ledger main menu — not from the payment menu (PL900). Operators who need to check a supplier's position during payment entry must exit PL080, navigate back through the menu hierarchy, and launch PL015 separately.

PL015 (3.02.11) Purchase Ledger Enquiry 07/03/26
Supplier: ACME Corporation Ltd
****************************************
*A/C Nos [ACME001]*Balance [ 16,847.50]*
*Ytd    [  67390 ]*Unapplied[     0.00]*
*Credit [ 25000  ]*Unposted[     0.00]*
****************************************
 Number   Date     Description    Invoiced
   48271  07/01/26 Goods - ORD41  3,250.00
   48356  15/01/26 Goods - ORD42  2,890.00
   48412  28/01/26 Goods - ORD43  4,125.50
   48503  10/02/26 Goods - ORD44  2,340.00
   48621  22/02/26 Goods - ORD45  1,895.00
   48744  03/03/26 Goods - ORD46  2,347.00





Total Outstanding     Current       30
      16,847.50    10,265.50   4,235.00
                      60            90+
Select: 'P'rint, 'N'ext, 'T'oggle or 'E'nd [ ]

7.5 PL100 — Cash Posting

Cash Posting (PL100) is the critical batch operation that finalizes payment transactions, updates supplier balances, and creates General Ledger entries. The legacy screen is minimal — a simple YES/NO confirmation prompt (verified from pl100.cbl line 304: accept wx-reply) followed by batch processing output. The business rule BR-PAY-001 (Payment Posting Validation) enforces that p-flag-p equals 2 before posting is allowed.

PL100 (3.02.06)  Purchase Cash Posting 07/03/26









 OK to post payment transactions (YES/NO) ?
                                      <YES>

 ACME001  Batch 1/1  07/01/26   3,250.00
 ACME001  Batch 1/2  15/01/26   2,890.00
 ACME001  Batch 1/3  28/01/26   4,125.50
 ACME001  Batch 1/4  10/02/26   2,293.20
 ACME001  Batch 1/5  22/02/26   1,857.10
 ACME001  Batch 1/6  03/03/26   1,431.70

7.6 GL051 — General Ledger Batch Amendment/Reporting

GL051 provides batch transaction viewing and amendment for General Ledger entries. In the payment workflow, operators use this program to verify that cash posting created the correct debit/credit journal entries. It is accessed from an entirely separate module (General Ledger) — the operator must exit the Purchase Ledger menu hierarchy and navigate to the General Ledger menu to reach it.

gl051 (3.02.06)                        07/03/26
Batch Amendment / Reporting Functions
admin




Select one of the following by number :- [ ]

(1)  Amend existing Batch
(2)  Print Proof Reports - All Batches
(3)  Print Proof Reports - One Batch
(4)  Print all Transactions


(9)  Exit to system menu

Enter Batch Number :- [     ]

7.7 Beyond 1:1 — Unified Payment View

Legacy applications are typically constrained by the limitations of green-screen terminals — fixed 80×24 grids, single-screen contexts, and menu-driven navigation between isolated programs. A faithful 1:1 migration would carry these constraints forward into the modern UI. Instead, the user journey needs to be reimagined with the capabilities of modern interfaces, often resulting in multiple legacy screens combining into one continuous experience. This section presents exactly that transformation.

What Is a Use-Case Storyboard?

A storyboard is a sequence of scenes that together depict one complete end-to-end user journey through the modernized system. Unlike the 1:1 screen comparisons above, a storyboard captures what happens when platform constraints are removed entirely and several legacy programs merge into a single, continuous workflow. Each scene represents a discrete state of the same screen — the layout remains constant while data, colors, labels, and available actions change to reflect workflow progression. A user does not navigate between scenes; the screen transitions from one scene to the next in response to their actions.

How the Workflow Derives a Storyboard

The storyboard below was generated automatically by the use-case discovery agent as part of the modernization workflow. The agent follows a four-step derivation:

1. Query Cognatix MCP for the payment flow. The agent retrieves the PaymentProcessing and RemittanceAdviceGeneration workflows, their state machines, and the full business rule catalog (BR-PAY-001 through BR-PAY-008) from the Cognatix knowledge graph.
2. Identify legacy screens. Each workflow state is traced back to the COBOL programs that implement it — PL900, PL080, PL090/PL095, PL100, PL960, and GL051 — along with their terminal-level UI constraints (80×24 grid, numbered menu, sequential confirmation prompts, 9-invoice OCCURS limit).
3. Map state transitions. The agent identifies which workflow states the user actually experiences as distinct visual moments (e.g., “allocation preview with amber rows” vs. “confirmed allocation with green rows”) and sequences them into scenes.
4. Apply modern UI patterns. Each scene is rendered using modern interaction patterns — autocomplete search, real-time calculation, amber/green state transitions, inline GL postings — informed by the user-provided UI storyboard and the platform affinity analysis from Section 5.

The result is a scene-by-scene walkthrough that shows how six separate legacy programs (PL900, PL080, PL090/PL095, PL100, PL960, and GL051) consolidate into a single unified payment screen. The storyboard also serves as the primary input to the artifact generation workflow, which produces the runnable demo UI and backing services.

ENTRY → VALIDATION → APPROPRIATION → BATCH_CONTROL → PROOF_GENERATION → POSTING → AUDIT_COMPLETE

FILE_READ → HEADER_FORMAT → ADDRESS_PROCESS → INVOICE_LIST → PAYMENT_DISPLAY → TOTAL_CALC → PRINT_GENERATE → DOCUMENT_OUTPUT

Scene 1: Three Screens Become One

The unified payment screen replaces three separate legacy programs. The comparison below shows the three green-screen terminals that the modern single page replaces.

PL080 (3.02.06)   Payment Data Entry  07/03/26

ACME Corporation Ltd
*Date  [07/03/2026]*A/C Nos   [ACME001]*
*Value [15847.50   ]*Batch   [    1/  1]*

Current Balance -   15,847.50
------------------------------------------------
Folio No --Date--  --Amount-- Deductable
   48271  07/01/26   3,250.00    65.00
   48356  15/01/26   2,890.00    57.80
   48412  28/01/26   4,125.50    82.51

Enter further payments? (Y/N)  [Y]

PL015 (3.02.11) Purchase Ledger Enq  07/03/26
Supplier: ACME Corporation Ltd
*A/C Nos [ACME001]*Balance [ 16,847.50]*
*Ytd    [  67390 ]*Unapplied[     0.00]*
*Credit [ 25000  ]*Unposted[     0.00]*

Number   Date     Description    Invoiced
  48271  07/01/26 Goods - ORD41  3,250.00
  48356  15/01/26 Goods - ORD42  2,890.00
  48412  28/01/26 Goods - ORD43  4,125.50

Current    30d      60d      90+
10,265.50 4,235.00  0.00    0.00
Select: P'rint N'ext M'ore E'nd [ ]

GL051 (3.04.02)  Batch Amend/Report  07/03/26

(1) Amend existing Batch
(2) Print Proof - All Batches
(3) Print Proof - One Batch
(4) Print all Transactions
(9) Exit to system menu

Enter Batch Number :- [     ]

Number  Code  Date    Debit    Credit

 Net Amount         VAT Amount

Three separate programs. Three separate terminal sessions. A numbered menu to navigate between them. In the legacy system, an operator who needs to enter a payment, check the supplier's account, and verify the GL entries must navigate between all three. The modern unified screen presents all of this information on a single page — the operator never leaves the view.

Scene 2: Supplier Autocomplete

The operator types "ACM" in the supplier search field. An autocomplete dropdown appears showing matching suppliers with their account codes, outstanding balances, and open invoice counts — financial context that was invisible in the legacy system until after the supplier was selected. In the legacy PL080, the operator typed the exact 7-character account code (accept pay-customer at 0572) at a blank prompt with no search capability and no financial preview.

The autocomplete reveals the second platform affinity win: the same business need (find and select a supplier) with a completely modernized interaction model. Fuzzy search, financial preview, and immediate visual feedback replace the legacy's exact-code-or-nothing approach.

Scene 3: Allocation Preview — Pending State

After selecting ACME Corporation and entering a payment amount, the allocation preview table populates automatically. This is the pending state — nothing has been committed. The table shows how the payment will be applied to outstanding invoices, with BR-PAY-002 (Payment Appropriation Logic) calculating discount eligibility in real time. Invoices are sorted oldest-first, with estimated discount amounts prefixed by a tilde (~) to signal they are projections, not final values.

The allocation preview shows BR-PAY-002 in action: invoices are allocated oldest-first, with discount eligibility calculated per the legacy algorithm (add 1 to oi-deduct-days, compare against payment date). Invoice 48503 has an early payment discount — it falls within the deduction terms window relative to the payment date. The first three invoices are too old for discount eligibility. The operator has exercised BR-PAY-008 (Selective Invoice Exclusion) by unchecking invoices 48621 and 48744 — these are greyed out with an "Excluded" badge and carry no allocation. The remaining four checked invoices are fully funded at $11,625.50, with an estimated discount of ~$46.80 on invoice 48503. In the legacy system, the only way to skip an invoice was to enter zero during line-by-line terminal interaction in the accept-money2 loop — there was no pre-selection mechanism.

Scene 4: Post Payment — Confirmed State

The operator clicks "Post Payment." The Payment API Service validates the batch (BR-PAY-001), the Payment Batch Service executes cash posting with GL integration, and the allocation table transitions from amber (pending) to green (confirmed). The same table structure is preserved — only colors, labels, and values change, making the state transition unmistakable.

The state transition is visible in every element: amber rows become green, "Will Pay" becomes "Paid," tilde-prefixed discount estimates become final amounts, column headers change from "Pending Allocation" to "Allocated" and from "Est. Discount" to "Discount," the amber summary bar becomes green, and the "Post Payment" button disappears because the action is complete. The two excluded invoices (48621 and 48744) do not appear in the confirmed state — they were filtered out before posting. The "View GL Postings" link on the success banner leads directly to Scene 5.

Scene 5: View GL Postings — Double-Entry Accounting

Clicking "View GL Postings" on the success banner navigates directly to the GL journal entries for this payment. No manual lookup, no switching programs, no re-entering the batch number. Three balanced journal entries are displayed with account names and descriptions alongside the codes — information that required memorization or a separate lookup in the legacy GL051 screen.

What took six separate program invocations, a numbered menu, and overnight batch latency for GL updates now happens on a single page with real-time feedback and full business rule transparency. The entire flow — from supplier search through allocation preview through posting through GL verification — completes in approximately 2 seconds of processing time, compared to the legacy's 12-hour gap between payment entry and GL visibility.

8. Code Translation Examples

This section demonstrates the translation of actual COBOL business logic from the Payment Processing subsystem into Python using the resolved target patterns: FastAPI, Pydantic, SQLAlchemy, structlog, and OpenTelemetry. Each example shows the legacy source code (read directly from the ACAS codebase via Cognatix), the target Python implementation, and translation notes explaining the mapping decisions. Business rule references (BR-PAY-XXX) appear only in the Translation Notes column, never in the legacy code itself.

8.1 Payment Appropriation Logic (BR-PAY-002)

The payment appropriation algorithm is the most complex business rule in the Payment Processing subsystem. It iterates through outstanding invoices, calculates discount eligibility by adding 1 to oi-deduct-days and comparing against the payment date, applies discounts for timely payments, and tracks the running appropriation amount. This example shows the core appropriation loop from pl080.cbl.

*> purchase/pl080.cbl lines 560-610
*> payment-appropriate section

 add      oi-net oi-carriage oi-vat
          oi-c-vat giving work-net.
 move     oi-deduct-amt to work-ded.
 move     work-net to test-amount.

 if       test-amount = oi-paid
    and   oi-status = zero
          move pay-date to oi-date-cleared
          move 1 to oi-status
          perform OTM5-Rewrite
          go to pay-loop.

 add      1  oi-deduct-days  to  u-bin.
 if       u-bin  >  pay-date
          subtract  work-2  from  work-1
          move work-2 to display-5
 else
          move zero to display-5.

 subtract oi-paid  from  work-1.
 move     work-1 to pay-paid.

 add      pay-paid to approp-amount.
 if       approp-amount  >  pay-value
          go to  payment-2-high.

from decimal import Decimal
from datetime import date

import structlog
from opentelemetry import trace

from app.exceptions import ValidationError

logger = structlog.get_logger()
tracer = trace.get_tracer(__name__)


def calculate_allocation(
    invoices: list[OpenItem],
    payment_amount: Decimal,
    payment_date: date,
) -> list[AllocationLine]:
    """Allocate payment to invoices oldest-first
    with discount eligibility calculation."""
    with tracer.start_as_current_span(
        "calculate_allocation",
        attributes={
            "payment.amount": float(payment_amount),
            "invoice.count": len(invoices),
        },
    ) as span:
        remaining = payment_amount
        allocations: list[AllocationLine] = []

        for inv in sorted(invoices, key=lambda i: i.date):
            if remaining <= 0:
                break

            net = inv.net + inv.carriage + inv.vat + inv.c_vat
            outstanding = net - inv.paid

            if outstanding <= 0:
                continue

            # Discount eligibility: add 1 to deduct_days
            # then compare against payment date
            discount = Decimal(0)
            if inv.deduct_amount > 0:
                cutoff = inv.date + timedelta(
                    days=inv.deduct_days + 1
                )
                if cutoff > payment_date:
                    discount = inv.deduct_amount
                    outstanding -= discount

            applied = min(remaining, outstanding)
            remaining -= applied

            allocations.append(AllocationLine(
                invoice_ref=inv.invoice,
                amount=applied,
                discount=discount,
                fully_paid=(applied == outstanding),
            ))

        span.set_attribute(
            "allocation.count", len(allocations)
        )
        logger.info(
            "payment.allocated",
            allocated=float(payment_amount - remaining),
            discount_total=float(
                sum(a.discount for a in allocations)
            ),
        )
        return allocations

8.2 Payment Posting Validation (BR-PAY-001)

The cash posting guard is the simplest but most critical business rule: before any payment can be posted to the General Ledger, the batch must have been proofed (flag value 2). This gate enforces the two-stage approval process: entry (flag=1) then proof (flag=2) then post.

*> purchase/pl100.cbl lines 294-302

     if       p-flag-p not = 2
              display PL137   at 2301
              display PL002   at 2401
              accept ws-reply at 2433
              go to menu-exit
     end-if.

*> Continues to YES/NO confirmation:

 acpt-xrply.
     display  "OK to post payment
      transactions (YES/NO) ?
      <   > enter {CR}"
                  at 1212.
     move     spaces to wx-reply.
     accept   wx-reply at 1256.
     move     function upper-case
              (wx-reply) to wx-reply.
     if       wx-reply = "NO"
              go to menu-exit.
     if       wx-reply not = "YES"
              go to acpt-xrply.

from enum import IntEnum

import structlog
from opentelemetry import trace

from app.exceptions import ConflictError

logger = structlog.get_logger()


class PaymentFlag(IntEnum):
    ENTERED = 1
    PROOFED = 2


async def validate_posting(
    batch_number: int,
    db: AsyncSession,
) -> BatchControl:
    """Validate batch is proofed before
    allowing cash posting."""
    batch = await db.get(
        BatchControl, batch_number
    )
    if not batch:
        raise NotFoundError(
            "Batch", str(batch_number)
        )

    if batch.payment_flag != PaymentFlag.PROOFED:
        logger.warning(
            "posting.rejected",
            batch=batch_number,
            flag=batch.payment_flag,
            reason="not_proofed",
        )
        raise ConflictError(
            message=(
                f"Batch {batch_number} has not "
                "been proofed. Current status: "
                f"{batch.payment_flag.name}"
            ),
            details={
                "batch_number": batch_number,
                "current_flag": batch.payment_flag,
                "required_flag": PaymentFlag.PROOFED,
            },
        )

    logger.info(
        "posting.validated",
        batch=batch_number,
    )
    return batch

8.3 Payment Method Determination (BR-PAY-004)

Payment method routing determines whether a supplier payment is issued as a cheque (with sequential numbering) or as a BACS electronic transfer. The legacy implementation uses a simple sort-code presence check in pl940.cbl.

*> purchase/pl940.cbl lines 517-530

 perform  varying z from 1 by 1
          until z > 9
          move pay-folio (z) to c-folio (z)
          move pay-invoice (z) to c-inv (z)
          move pay-value (z) to c-value (z)
          if   z  <  9
               move "," to c-last (z)
          else
               move " " to c-last (z)
          end-if
 end-perform

 if       pay-sortcode = zero
          move cheque-nos to c-cheque
                             pay-cheque
          add 1 to cheque-nos
 else
          move zero   to pay-cheque
          move "BACS" to c-cheque-x
 end-if

from enum import StrEnum

import structlog
from pydantic import BaseModel

logger = structlog.get_logger()


class PaymentMethod(StrEnum):
    CHEQUE = "CHEQUE"
    BACS = "BACS"


class PaymentOutput(BaseModel):
    method: PaymentMethod
    cheque_number: int | None = None
    bank_reference: str | None = None


async def determine_payment_method(
    supplier_sort_code: int,
    cheque_sequence: AsyncSequence,
) -> PaymentOutput:
    """Route payment to cheque or BACS
    based on supplier sort code."""

    if supplier_sort_code == 0:
        # No sort code: issue cheque
        cheque_no = await cheque_sequence.next()
        logger.info(
            "payment.method.cheque",
            cheque_number=cheque_no,
        )
        return PaymentOutput(
            method=PaymentMethod.CHEQUE,
            cheque_number=cheque_no,
        )
    else:
        # Sort code present: BACS transfer
        logger.info(
            "payment.method.bacs",
            sort_code=supplier_sort_code,
        )
        return PaymentOutput(
            method=PaymentMethod.BACS,
            bank_reference="BACS",
        )

9. Data Mapping Strategy

This section details the schema transformation from legacy COBOL copybook-defined data structures to the target PostgreSQL schema. The ACAS Payment Processing subsystem uses a dual-storage architecture: ISAM indexed files and MySQL tables, both accessed through the acas032 file handler abstraction (650 LOC). The target consolidates all storage into a single PostgreSQL RDS instance with 5 normalized tables. Each transformation example shows the legacy COBOL copybook definition (read from the ACAS codebase via Cognatix AI), the target PostgreSQL DDL, and the SQLAlchemy ORM model derived from that DDL.

9.1 Legacy Data Architecture

The legacy data architecture uses COBOL copybooks to define fixed-length record structures that are shared between ISAM file access and MySQL table storage. The acas032 file handler routes operations between the two storage backends using standardized function codes (1=open, 2=close, 3=read-next, 4=read-indexed, 5=write, 7=rewrite, 8=delete, 9=start). A runtime configuration flag (FS-Cobol-Files-Used) selects which backend is active.

erDiagram
    PAY_RECORD {
        char_7 Pay_Supl_Key "Supplier code (PIC X(7))"
        num_2 Pay_Nos "Sequence number (PIC 99)"
        char_1 Pay_Cont "Continuation flag"
        comp_8 Pay_Date "Payment date (PIC 9(8) COMP)"
        comp_8 Pay_Cheque "Cheque number (PIC 9(8) COMP)"
        comp_6 Pay_SortCode "Bank sort code (PIC 9(6) COMP)"
        comp_8 Pay_Account "Bank account (PIC 9(8) COMP)"
        comp3_s7v2 Pay_Gross "Gross amount (PIC S9(7)V99 COMP-3)"
    }

    PAY_LINE_ITEM {
        comp_8 Pay_Folio "Folio reference (PIC 9(8) COMP)"
        comp_2 Pay_Period "Period code (PIC 99 COMP)"
        comp3_s7v2 Pay_Value "Line value (PIC S9(7)V99 COMP-3)"
        comp3_s3v2 Pay_Deduct "Discount (PIC S999V99 COMP-3)"
        char_10 Pay_Invoice "Invoice number (PIC X(10))"
    }

    OI_HEADER {
        char_7 OI_Supplier "Supplier code (PIC X(7))"
        num_8 OI_Invoice "Invoice number (PIC 9(8))"
        bin_long OI_Date "Invoice date (BINARY-LONG)"
        comp_5 OI_B_Nos "Batch number (PIC 9(5) COMP)"
        comp_3 OI_B_Item "Item in batch (PIC 999 COMP)"
        num_1 OI_Type "Transaction type (PIC 9)"
        comp3_s7v2 OI_Net "Net amount"
        comp3_s7v2 OI_Paid "Amount paid"
        num_1 OI_Status "0=Open 1=Closed"
    }

    PAY_RECORD ||--o{ PAY_LINE_ITEM : "OCCURS 9"
    PAY_RECORD }o--o{ OI_HEADER : "references"
        

9.2 Target Data Architecture

The target data model consolidates all legacy storage into 5 normalized PostgreSQL tables: payment, open_item, batch_control, gl_posting, and payment_audit. The fixed OCCURS 9 constraint is eliminated; each payment can have unlimited open item rows.

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

9.3 Payment Record Transformation (fdpay.cob → payment table)

The legacy Pay-Record structure (defined in fdpay.cob and mirrored in wspay.cob / plwspay.cob) is a 237-byte fixed-length record combining payment header fields with an embedded OCCURS 9 array of invoice line items. The target splits this into two tables: payment (header) and open_item (line items), normalizing the repeating group into individual rows.

*> File Definition For The Payments File
*> For Purchase Ledger.
*> 237 bytes

 fd  Pay-File.

 01  Pay-Record.
     03  Pay-Key.
         05  Pay-Supl-Key  pic x(7).
         05  Pay-Nos       pic 99.
     03  Pay-Cont          pic x.
     03  Pay-Date          pic 9(8)  comp.
     03  Pay-Cheque        pic 9(8)  comp.
     03  Pay-SortCode      pic 9(6)  comp.
     03  Pay-Account       pic 9(8)  comp.
     03  Pay-Gross         pic s9(7)v99
                                     comp-3.
     03  filler            occurs 9.
         05  Pay-Folio     pic 9(8)  comp.
         05  Pay-Period    pic 99    comp.
         05  Pay-Value     pic s9(7)v99
                                     comp-3.
         05  Pay-Deduct    pic s999v99
                                     comp-3.
         05  Pay-Invoice   pic x(10).

CREATE TABLE payment (
    id              UUID PRIMARY KEY
                    DEFAULT uuid_generate_v4(),
    payment_reference
                    VARCHAR(20) UNIQUE,
    transaction_type
                    INTEGER,
    payment_date    DATE NOT NULL,
    supplier_code   VARCHAR(8) NOT NULL,
    gross_amount    NUMERIC(11,2) NOT NULL,
    discount_amount NUMERIC(11,2)
                    DEFAULT 0,
    net_amount      NUMERIC(11,2) NOT NULL,
    batch_number    INTEGER
        REFERENCES batch_control(batch_number),
    payment_flag    INTEGER DEFAULT 1,
    payment_method  VARCHAR(10),
    cheque_number   VARCHAR(10),
    bank_reference  VARCHAR(20),
    created_at      TIMESTAMPTZ
                    DEFAULT now(),
    updated_at      TIMESTAMPTZ
);

CREATE INDEX ix_payment_supplier
    ON payment (supplier_code);
CREATE INDEX ix_payment_batch
    ON payment (batch_number);
CREATE INDEX ix_payment_date
    ON payment (payment_date);

from sqlalchemy import (
    Column, Date, DateTime, Index,
    Integer, Numeric, String, Uuid,
    func,
)
from sqlalchemy.orm import (
    DeclarativeBase, relationship,
)


class Base(DeclarativeBase):
    pass


class Payment(Base):
    __tablename__ = "payment"

    id = Column(Uuid, primary_key=True)
    payment_reference = Column(
        String(20), unique=True)
    transaction_type = Column(Integer)
    payment_date = Column(
        Date, nullable=False)
    supplier_code = Column(
        String(8), nullable=False)
    gross_amount = Column(
        Numeric(11, 2), nullable=False)
    discount_amount = Column(
        Numeric(11, 2), default=0)
    net_amount = Column(
        Numeric(11, 2), nullable=False)
    batch_number = Column(Integer)
    payment_flag = Column(
        Integer, default=1)
    payment_method = Column(String(10))
    cheque_number = Column(String(10))
    bank_reference = Column(String(20))
    created_at = Column(DateTime,
        server_default=func.now())
    updated_at = Column(DateTime,
        onupdate=func.now())

    # Relationships
    open_items = relationship(
        "OpenItem",
        back_populates="payment")

    __table_args__ = (
        Index("ix_payment_supplier",
              "supplier_code"),
        Index("ix_payment_batch",
              "batch_number"),
        Index("ix_payment_date",
              "payment_date"),
    )

9.4 Open Item Transformation (plwsoi.cob → open_item table)

The legacy OI-Header structure (defined in plwsoi.cob, stored via fdoi4.cob as a 113-byte record) contains invoice details, batch tracking fields, financial amounts, discount eligibility, and status flags. The target open_item table normalizes this structure, adds aging calculation support, and uses a foreign key to the payment table instead of embedded composite keys.

*> Working Storage For The Open Item Header
*> record size 113 bytes

 01  OI-Header.
     03  OI-Key.
         05  OI-Customer.
             07  OI-Supplier.
                 09  OI-Nos   Pic X(6).
                 09  OI-Check Pic 9.
         05  OI-Invoice   Pic 9(8).
     03  OI-Date         Binary-long.
     03  OI-Batch                    Comp.
         05  OI-B-Nos    Pic 9(5).
         05  OI-B-Item   Pic 999.
     03  OI-Type         pic 9.
     03  OI-ref          pic x(10).
     03  OI-order        pic x(10).
     03  OI-hold-flag    pic x.
     03  OI-unapl        pic x.
     03  filler                      comp-3.
         05  OI-P-C      pic s9(7)v99.
         05  OI-Net      pic s9(7)v99.
         05  OI-Approp redefines OI-Net
                         pic s9(7)v99.
         05  OI-Extra    pic s9(7)v99.
         05  OI-Carriage pic s9(7)v99.
         05  OI-Vat      pic s9(7)v99.
         05  OI-Discount pic s9(7)v99.
         05  OI-E-Vat    pic s9(7)v99.
         05  OI-C-Vat    pic s9(7)v99.
         05  OI-Paid     pic s9(7)v99.
     03  OI-Status       pic 9.
     03  OI-Deduct-Days  binary-char.
     03  OI-Deduct-Amt   pic s999v99 comp.
     03  OI-Deduct-Vat   pic s999v99 comp.
     03  OI-Days         binary-char.
     03  OI-CR           binary-long.
     03  OI-Applied      pic x.
     03  OI-Date-Cleared binary-long.

CREATE TABLE open_item (
    id              UUID PRIMARY KEY
                    DEFAULT uuid_generate_v4(),
    payment_id      UUID
        REFERENCES payment(id),
    supplier_code   VARCHAR(8) NOT NULL,
    invoice_reference
                    VARCHAR(20) NOT NULL,
    folio_number    INTEGER,
    invoice_date    DATE NOT NULL,
    invoice_amount  NUMERIC(11,2) NOT NULL,
    applied_amount  NUMERIC(11,2)
                    DEFAULT 0,
    discount_taken  NUMERIC(7,2)
                    DEFAULT 0,
    deduction_amount
                    NUMERIC(7,2) DEFAULT 0,
    deduction_days  INTEGER,
    transaction_type
                    VARCHAR(20),
    hold_flag       VARCHAR(1),
    status          INTEGER DEFAULT 0,
    date_cleared    DATE,
    created_at      TIMESTAMPTZ
                    DEFAULT now(),
    updated_at      TIMESTAMPTZ
);

CREATE INDEX ix_oi_payment
    ON open_item (payment_id);
CREATE INDEX ix_oi_invoice
    ON open_item (invoice_reference);
CREATE INDEX ix_oi_supplier
    ON open_item (supplier_code);

-- Aging: volatile expressions use
-- views, not stored computed columns
CREATE VIEW v_open_item_aged AS
SELECT *,
    CURRENT_DATE - invoice_date
        AS age_days,
    CASE
      WHEN CURRENT_DATE - invoice_date
           < 30 THEN 'current'
      WHEN CURRENT_DATE - invoice_date
           < 60 THEN '30_days'
      WHEN CURRENT_DATE - invoice_date
           < 90 THEN '60_days'
      ELSE '90_plus'
    END AS age_bucket
FROM open_item
WHERE status = 0;

from sqlalchemy import (
    Column, Date, DateTime,
    ForeignKey, Index, Integer,
    Numeric, String, Uuid, func,
)


class OpenItem(Base):
    __tablename__ = "open_item"

    id = Column(Uuid, primary_key=True)
    payment_id = Column(
        Uuid, ForeignKey("payment.id"))
    supplier_code = Column(
        String(8), nullable=False)
    invoice_reference = Column(
        String(20), nullable=False)
    folio_number = Column(Integer)
    invoice_date = Column(
        Date, nullable=False)
    invoice_amount = Column(
        Numeric(11, 2), nullable=False)
    applied_amount = Column(
        Numeric(11, 2), default=0)
    discount_taken = Column(
        Numeric(7, 2), default=0)
    deduction_amount = Column(
        Numeric(7, 2), default=0)
    deduction_days = Column(Integer)
    transaction_type = Column(String(20))
    hold_flag = Column(String(1))
    status = Column(Integer, default=0)
    date_cleared = Column(Date)
    created_at = Column(DateTime,
        server_default=func.now())
    updated_at = Column(DateTime,
        onupdate=func.now())

    # Relationships
    payment = relationship(
        "Payment",
        back_populates="open_items")

    # age_days, age_bucket: computed
    # via database views (volatile)

    __table_args__ = (
        Index("ix_oi_payment",
              "payment_id"),
        Index("ix_oi_invoice",
              "invoice_reference"),
        Index("ix_oi_supplier",
              "supplier_code"),
    )

9.5 Batch Control Extraction (embedded fields → batch_control table)

The legacy system embeds batch control information within the payment and open item records: OI-B-Nos (batch number), OI-B-Item (item within batch), and the composite invoice number derived as OI-B-Nos * 1000 + OI-B-Item (see pl080.cbl line 730). The batch limit of 99 items and bl-next-batch assignment (line 480) are managed through working storage variables rather than a dedicated entity. The target promotes batch control to a first-class table with explicit lifecycle tracking.

*> Batch fields embedded across records

*> In plwsoi.cob (open item):
 03  OI-Batch                    Comp.
     05  OI-B-Nos     Pic 9(5).
     05  OI-B-Item    Pic 999.

*> In pl080.cbl (payment entry):
*> line ~480:
 if bl-next-batch = zero
    move 1 to bl-next-batch.

*> line ~630:
 move bl-next-batch to oi-b-nos.
 add  1 to k.
 move k to oi-b-item.

*> line ~730 (composite key):
 multiply oi-b-nos by 1000
    giving oi-invoice.
 add oi-b-item to oi-invoice.

*> Working storage batch limit:
 01  k            pic 999.
*> (implicit 99-item limit from
*>  PIC 999 and business practice)

CREATE TABLE batch_control (
    batch_number    INTEGER
        GENERATED ALWAYS AS IDENTITY
        PRIMARY KEY,
    batch_date      DATE NOT NULL,
    item_count      INTEGER DEFAULT 0,
    batch_total     NUMERIC(13,2)
                    DEFAULT 0,
    batch_status    VARCHAR(10)
                    DEFAULT 'OPEN',
    created_by      VARCHAR(50),
    created_at      TIMESTAMPTZ
                    DEFAULT now(),
    closed_at       TIMESTAMPTZ,

    CONSTRAINT ck_batch_limit
        CHECK (item_count <= 99)
);

CREATE INDEX ix_batch_status
    ON batch_control (batch_status);
CREATE INDEX ix_batch_date
    ON batch_control (batch_date);

from sqlalchemy import (
    CheckConstraint, Column, Date,
    DateTime, Index, Integer,
    Numeric, String, func,
)


class BatchControl(Base):
    __tablename__ = "batch_control"

    batch_number = Column(
        Integer, primary_key=True,
        autoincrement=True)
    batch_date = Column(
        Date, nullable=False)
    item_count = Column(
        Integer, default=0)
    batch_total = Column(
        Numeric(13, 2), default=0)
    batch_status = Column(
        String(10), default="OPEN")
    created_by = Column(String(50))
    created_at = Column(DateTime,
        server_default=func.now())
    closed_at = Column(DateTime)

    # Relationships
    payments = relationship(
        "Payment",
        back_populates="batch")
    gl_postings = relationship(
        "GLPosting",
        back_populates="batch")

    __table_args__ = (
        CheckConstraint(
            "item_count <= 99",
            name="ck_batch_limit"),
        Index("ix_batch_status",
              "batch_status"),
        Index("ix_batch_date",
              "batch_date"),
    )

9.6 Sample Data Transformation

The following example shows how a single legacy payment record with 3 invoice appropriations is transformed during ETL migration. The ETL process is modeled on the existing paymentsLD.cbl (515 LOC) data loader, which already handles reading payment and open item records from ISAM files.

Legacy Record (fdpay.cob format)

Pay-Record:
  Pay-Supl-Key  = "SMIT001"       -- Supplier: Smith & Co
  Pay-Nos       = 07              -- 7th payment for this supplier
  Pay-Cont      = " "             -- No continuation
  Pay-Date      = 20260215        -- 15 Feb 2026 (integer YYYYMMDD)
  Pay-Cheque    = 00000000        -- Zero = BACS payment
  Pay-SortCode  = 401234          -- Non-zero = BACS
  Pay-Account   = 12345678        -- Bank account
  Pay-Gross     = +16052.81       -- $16,052.81 gross

  -- OCCURS 1:
  Pay-Folio(1)   = 00045201       Pay-Period(1) = 03
  Pay-Value(1)   = +08500.00      Pay-Deduct(1) = +170.00
  Pay-Invoice(1) = "INV-045201"

  -- OCCURS 2:
  Pay-Folio(2)   = 00045215       Pay-Period(2) = 03
  Pay-Value(2)   = +05200.00      Pay-Deduct(2) = +035.31
  Pay-Invoice(2) = "INV-045215"

  -- OCCURS 3:
  Pay-Folio(3)   = 00045230       Pay-Period(3) = 03
  Pay-Value(3)   = +02352.81      Pay-Deduct(3) = +000.00
  Pay-Invoice(3) = "INV-045230"

  -- OCCURS 4-9: empty (Pay-Invoice = spaces, Pay-Value = 0)

Migrated Records (PostgreSQL)

-- payment table (1 row)
INSERT INTO payment (
    id, payment_reference, transaction_type, payment_date,
    supplier_code, gross_amount, discount_amount, net_amount,
    batch_number, payment_flag, payment_method,
    cheque_number, bank_reference
) VALUES (
    'a1b2c3d4-...',    -- UUID generated during migration
    'SMIT001-07',      -- Pay-Supl-Key + "-" + Pay-Nos
    5,                    -- Transaction type: Payment
    '2026-02-15',      -- Pay-Date 20260215 -> DATE
    'SMIT001',         -- Pay-Supl-Key trimmed
    16052.81,            -- Pay-Gross
    205.31,              -- Sum of Pay-Deduct (170.00 + 35.31)
    15847.50,            -- gross - discount
    42,                   -- Batch from OI-B-Nos
    3,                    -- POSTED (migrated historical data)
    'BACS',            -- Pay-SortCode non-zero = BACS
    NULL,                -- No cheque (BACS payment)
    '40-12-34 12345678' -- Sort + Account combined
);

-- open_item table (3 rows; empty OCCURS 4-9 filtered out)
INSERT INTO open_item (
    id, payment_id, invoice_reference, folio_number,
    invoice_date, invoice_amount, applied_amount,
    discount_taken, transaction_type
) VALUES
    ('e5f6...', 'a1b2c3d4-...', 'INV-045201', 45201,
     '2026-01-10', 8500.00, 8330.00, 170.00, 'PAYMENT'),

    ('f7g8...', 'a1b2c3d4-...', 'INV-045215', 45215,
     '2026-01-18', 5200.00, 5164.69, 35.31, 'PAYMENT'),

    ('h9i0...', 'a1b2c3d4-...', 'INV-045230', 45230,
     '2026-02-01', 2352.81, 2352.81, 0.00, 'PAYMENT');

-- Verification: SUM(applied_amount) + SUM(discount_taken)
--   = (8330.00 + 5164.69 + 2352.81) + (170.00 + 35.31 + 0.00)
--   = 15847.50 + 205.31 = $16,052.81 = gross_amount

9.7 ETL Migration Pipeline

The migration pipeline reads records from both ISAM files and MySQL tables using existing data access patterns, transforms them into the target schema, and loads them into PostgreSQL. The pipeline is implemented as a Python script using SQLAlchemy for the target database and direct ISAM/MySQL readers for the source.

# Modeled on paymentsLD.cbl (515 LOC)
# and paymentsUNL.cbl (219 LOC)

import structlog
from datetime import datetime

logger = structlog.get_logger()

def extract_payment(
    row: dict,
) -> dict:
    """Parse legacy payment record."""
    pay_date = datetime.strptime(
        str(row["pay_date"]), "%Y%m%d"
    ).date()

    # Determine method from sort code
    method = (
        "BACS" if row["pay_sortcode"] != 0
        else "CHEQUE"
    )

    # Extract non-empty line items
    items = []
    for i in range(1, 10):
        inv = row.get(f"pay_invoice_{i}", "")
        val = row.get(f"pay_value_{i}", 0)
        if inv.strip() and val != 0:
            items.append({
                "invoice": inv.strip(),
                "folio": row[f"pay_folio_{i}"],
                "value": val,
                "deduct": row[f"pay_deduct_{i}"],
            })

    logger.info(
        "migration.payment_extracted",
        supplier=row["pay_supl_key"].strip(),
        items=len(items),
    )

    return {
        "supplier": row["pay_supl_key"].strip(),
        "nos": row["pay_nos"],
        "date": pay_date,
        "gross": row["pay_gross"],
        "method": method,
        "cheque": row["pay_cheque"],
        "items": items,
    }

from decimal import Decimal
from uuid import uuid4

from opentelemetry import trace
from sqlalchemy.ext.asyncio import (
    AsyncSession,
)

from app.models import Payment, OpenItem

tracer = trace.get_tracer(__name__)

async def transform_and_load(
    session: AsyncSession,
    extracted: dict,
) -> Payment:
    """Transform legacy record to target
    schema and persist."""
    with tracer.start_as_current_span(
        "migrate_payment",
        attributes={
            "supplier": extracted["supplier"],
        },
    ):
        discount = sum(
            Decimal(str(i["deduct"]))
            for i in extracted["items"]
        )
        gross = Decimal(str(
            extracted["gross"]))

        payment = Payment(
            id=uuid4(),
            payment_reference=(
                f"{extracted['supplier']}"
                f"-{extracted['nos']:02d}"),
            transaction_type=5,
            payment_date=extracted["date"],
            supplier_code=extracted["supplier"],
            gross_amount=gross,
            discount_amount=discount,
            net_amount=gross - discount,
            payment_method=extracted["method"],
            payment_flag=3,
        )
        session.add(payment)

        for item in extracted["items"]:
            oi = OpenItem(
                id=uuid4(),
                payment_id=payment.id,
                invoice_reference=item["invoice"],
                folio_number=item["folio"],
                applied_amount=Decimal(
                    str(item["value"])),
                discount_taken=Decimal(
                    str(item["deduct"])),
            )
            session.add(oi)

        await session.flush()
        logger.info(
            "migration.payment_loaded",
            payment_id=str(payment.id),
            items=len(extracted["items"]),
        )
        return payment

9.8 Performance Considerations

9.9 Schema Migration Design Rules

These rules govern all design decisions when translating legacy data structures to the target data model. They are split into two layers: universal rules that apply regardless of target database engine, and engine-specific rules that implement the universal decisions for the selected target. Together they ensure consistency between the schema artifact, ORM/document models, and seed data — all must be derivable from the same rules applied to the same source structures.

Universal Rules (all target engines)

Engine-Specific Rules

The universal rules above define what to do. The table below defines how to implement each decision for the target database engine. The database-schema agent reads databaseEngine from migration-plan.json and applies the corresponding column.

9.10 Alembic Migration Script

Schema migrations are managed by Alembic, the companion migration tool for SQLAlchemy. The initial migration creates all 5 tables, indexes, constraints, and views defined above. Subsequent migrations handle schema evolution during the migration phases.

"""Initial payment processing schema.

Revision ID: 001_initial
Create Date: 2026-03-07
"""

from alembic import op
import sqlalchemy as sa
from sqlalchemy.dialects import postgresql


def upgrade() -> None:
    # batch_control: first-class entity from embedded batch fields
    op.create_table(
        "batch_control",
        sa.Column("batch_number", sa.Integer, primary_key=True, autoincrement=True),
        sa.Column("batch_date", sa.Date, nullable=False),
        sa.Column("item_count", sa.Integer, server_default="0"),
        sa.Column("batch_total", sa.Numeric(13, 2), server_default="0"),
        sa.Column("batch_status", sa.String(10), server_default="'OPEN'"),
        sa.Column("created_by", sa.String(50)),
        sa.Column("created_at", sa.DateTime, server_default=sa.func.now()),
        sa.Column("closed_at", sa.DateTime),
        sa.CheckConstraint("item_count <= 99", name="ck_batch_limit"),
    )
    op.create_index("ix_batch_status", "batch_control", ["batch_status"])
    op.create_index("ix_batch_date", "batch_control", ["batch_date"])

    # payment: aggregate root from fdpay.cob Pay-Record
    op.create_table(
        "payment",
        sa.Column("id", postgresql.UUID, primary_key=True),
        sa.Column("payment_reference", sa.String(20), unique=True),
        sa.Column("transaction_type", sa.Integer),
        sa.Column("payment_date", sa.Date, nullable=False),
        sa.Column("supplier_code", sa.String(8), nullable=False),
        sa.Column("gross_amount", sa.Numeric(11, 2), nullable=False),
        sa.Column("discount_amount", sa.Numeric(11, 2), server_default="0"),
        sa.Column("net_amount", sa.Numeric(11, 2), nullable=False),
        sa.Column("batch_number", sa.Integer, sa.ForeignKey("batch_control.batch_number")),
        sa.Column("payment_flag", sa.Integer, server_default="1"),
        sa.Column("payment_method", sa.String(10)),
        sa.Column("cheque_number", sa.String(10)),
        sa.Column("bank_reference", sa.String(20)),
        sa.Column("created_at", sa.DateTime, server_default=sa.func.now()),
        sa.Column("updated_at", sa.DateTime, onupdate=sa.func.now()),
    )
    op.create_index("ix_payment_supplier", "payment", ["supplier_code"])
    op.create_index("ix_payment_batch", "payment", ["batch_number"])
    op.create_index("ix_payment_date", "payment", ["payment_date"])

    # open_item: normalized from plwsoi.cob OI-Header
    op.create_table(
        "open_item",
        sa.Column("id", postgresql.UUID, primary_key=True),
        sa.Column("payment_id", postgresql.UUID, sa.ForeignKey("payment.id")),
        sa.Column("supplier_code", sa.String(8), nullable=False),
        sa.Column("invoice_reference", sa.String(20), nullable=False),
        sa.Column("folio_number", sa.Integer),
        sa.Column("invoice_date", sa.Date, nullable=False),
        sa.Column("invoice_amount", sa.Numeric(11, 2), nullable=False),
        sa.Column("applied_amount", sa.Numeric(11, 2), server_default="0"),
        sa.Column("discount_taken", sa.Numeric(7, 2), server_default="0"),
        sa.Column("deduction_amount", sa.Numeric(7, 2), server_default="0"),
        sa.Column("deduction_days", sa.Integer),
        sa.Column("transaction_type", sa.String(20)),
        sa.Column("hold_flag", sa.String(1)),
        sa.Column("status", sa.Integer, server_default="0"),
        sa.Column("date_cleared", sa.Date),
        sa.Column("created_at", sa.DateTime, server_default=sa.func.now()),
        sa.Column("updated_at", sa.DateTime, onupdate=sa.func.now()),
    )
    op.create_index("ix_oi_payment", "open_item", ["payment_id"])
    op.create_index("ix_oi_invoice", "open_item", ["invoice_reference"])
    op.create_index("ix_oi_supplier", "open_item", ["supplier_code"])

    # v_open_item_aged: aging view (volatile — not stored computed)
    op.execute("""
        CREATE VIEW v_open_item_aged AS
        SELECT *,
            CURRENT_DATE - invoice_date AS age_days,
            CASE
              WHEN CURRENT_DATE - invoice_date < 30 THEN 'current'
              WHEN CURRENT_DATE - invoice_date < 60 THEN '30_days'
              WHEN CURRENT_DATE - invoice_date < 90 THEN '60_days'
              ELSE '90_plus'
            END AS age_bucket
        FROM open_item
        WHERE status = 0
    """)

    # gl_posting: decoupled GL integration via EventBridge
    op.create_table(
        "gl_posting",
        sa.Column("id", postgresql.UUID, primary_key=True),
        sa.Column("payment_id", postgresql.UUID, sa.ForeignKey("payment.id")),
        sa.Column("batch_number", sa.Integer, sa.ForeignKey("batch_control.batch_number")),
        sa.Column("debit_account", sa.String(8), nullable=False),
        sa.Column("credit_account", sa.String(8), nullable=False),
        sa.Column("amount", sa.Numeric(11, 2), nullable=False),
        sa.Column("posting_reference", sa.String(20)),
        sa.Column("posted", sa.Boolean, server_default="false"),
        sa.Column("posted_at", sa.DateTime),
    )
    op.create_index("ix_gl_payment", "gl_posting", ["payment_id"])
    op.create_index("ix_gl_batch", "gl_posting", ["batch_number"])
    op.create_index("ix_gl_posted", "gl_posting", ["posted"])

    # payment_audit: JSONB change tracking for amendments
    op.create_table(
        "payment_audit",
        sa.Column("id", postgresql.UUID, primary_key=True),
        sa.Column("payment_id", postgresql.UUID, sa.ForeignKey("payment.id")),
        sa.Column("action", sa.String(20), nullable=False),
        sa.Column("old_values", postgresql.JSONB),
        sa.Column("new_values", postgresql.JSONB),
        sa.Column("performed_by", sa.String(50)),
        sa.Column("performed_at", sa.DateTime, server_default=sa.func.now()),
    )
    op.create_index("ix_audit_payment", "payment_audit", ["payment_id"])
    op.create_index("ix_audit_date", "payment_audit", ["performed_at"])


def downgrade() -> None:
    op.execute("DROP VIEW IF EXISTS v_open_item_aged")
    op.drop_table("payment_audit")
    op.drop_table("gl_posting")
    op.drop_table("open_item")
    op.drop_table("payment")
    op.drop_table("batch_control")

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

↑ Back to Table of Contents

10. Business Rules Analysis

This section documents the behavioral rules extracted from the ACAS Payment Processing subsystem, showing COBOL source implementation alongside Python translations with formal Given-When-Then specifications. All 8 rules (7 extracted + 1 modernization enhancement) were discovered through Cognatix's Language-Agnostic Deep Scan analysis and verified against source code.

10.1 Business Rules Overview

Cognatix's entity analysis identified 8 business rules governing the Payment Processing subsystem: 7 extracted from legacy source code spanning payment entry validation, appropriation calculation, batch control, payment method routing, balance allocation, aging analysis, and remittance advice generation, plus 1 modernization enhancement (selective invoice exclusion) identified during planning. Three extracted rules carry high confidence scores (≥ 0.75) based on convergence from multiple analysis clusters, while four supporting rules provide additional behavioral coverage. Together with the net-new enhancement rule, these rules define the complete behavioral contract that the modernized Python services must preserve.

The rules were extracted from 6 COBOL source files: pl080.cbl (payment entry and appropriation), pl085.cbl (payment amendment), pl100.cbl (cash posting), pl910.cbl (payment analysis), pl940.cbl (payment generation), and pl960.cbl (remittance advice printing). The heaviest concentration of business logic resides in pl080.cbl, which implements the core payment appropriation algorithm with discount calculation, batch control, and unapplied balance handling.

Rule Distribution by Category

Rule Discovery Methodology

Business rules were discovered through Cognatix's Language-Agnostic Deep Scan, which performs multi-pass entity analysis across the entire ACAS codebase. The entity analysis pipeline identified business rule candidates through structural analysis (control flow patterns, validation gates) and categorical inference (domain-specific patterns like discount calculations and batch controls). Rules from overlapping analysis clusters were merged through convergence analysis — for example, PaymentAppropriationLogic was synthesized from two cluster perspectives with 0.92 convergence confidence. BR identifiers (BR-PAY-NNN) were assigned by this workflow for traceability; they do not exist in the legacy source code.

Each rule's Given-When-Then specification was derived from the Cognatix entity descriptions and verified against actual source code retrieved via Cognatix MCP file content queries. Source file references and line numbers come directly from Cognatix's entity metadata, ensuring full traceability from rule specification to implementation.

10.2 Validation Rules

BR-PAY-001: Payment Posting Validation

     perform  zz070-Convert-Date.
     move     ws-date to l2-date.
*>
     if       p-flag-p not = 2
              display PL137   at 2301
              display PL002   at 2401
              accept ws-reply at 2433
              go to menu-exit
     end-if.
*>
 menu-return.
*>
     display  prog-name at 0101
              with erase eos foreground-color 2.
     display  "Purchase Cash Posting" at 0132
              with foreground-color 2.

from enum import IntEnum
from payment_service.exceptions import (
    PaymentValidationError,
)
import structlog

logger = structlog.get_logger()

class PaymentFlag(IntEnum):
    ENTERED = 1
    PROOFED = 2
    POSTED = 3

def post_payment_batch(
    batch_id: int,
    db: Session,
) -> PostingResult:
    """Post a proofed payment batch to GL.

    Enforces two-stage approval: payments
    must be proofed (flag=2) before posting.
    """
    batch = get_batch(db, batch_id)

    if batch.payment_flag != PaymentFlag.PROOFED:
        raise PaymentValidationError(
            detail=(
                "Batch must be proofed before "
                "posting. Current status: "
                f"{batch.payment_flag.name}"
            ),
        )

    return execute_cash_posting(batch, db)

Test Cases

10.3 Calculation Rules

BR-PAY-002: Payment Appropriation Logic

     add      oi-net oi-carriage oi-vat oi-c-vat
              giving work-net.
     move     oi-deduct-amt to work-ded.
     move     work-net to test-amount.
     if       test-amount = oi-paid
        and   oi-status = zero
              move pay-date to oi-date-cleared
              move 1 to oi-status
              perform OTM5-Rewrite
              go to pay-loop.
*>
     if       test-amount not > oi-paid
              go to  pay-loop.
*>
*>   ... pay-details section ...
*>
     add      1  oi-deduct-days  to  u-bin.
     if       u-bin  >  pay-date
              subtract  work-2  from  work-1
              move work-2 to display-5
     else
              move zero   to display-5.
*>
     subtract oi-paid  from  work-1.
     move     work-1 to pay-paid.

from dataclasses import dataclass
from datetime import date
from decimal import Decimal

@dataclass
class AllocationLine:
    invoice_id: int
    amount_paid: Decimal
    discount_taken: Decimal

def calculate_appropriation(
    invoices: list[OpenItem],
    payment_date: date,
    payment_amount: Decimal,
) -> list[AllocationLine]:
    """Allocate payment across invoices
    with discount eligibility check."""
    allocations = []
    remaining = payment_amount

    for inv in invoices:
        net = (inv.net + inv.carriage
               + inv.vat + inv.c_vat)
        outstanding = net - inv.paid

        if outstanding <= Decimal(0):
            continue

        # Discount eligibility: compare
        # invoice date + deduct_days + 1
        # against payment date
        discount = Decimal(0)
        cutoff = inv.invoice_date + timedelta(
            days=inv.deduct_days + 1)
        if cutoff > payment_date:
            discount = inv.deduct_amt
            outstanding -= discount

        to_pay = min(outstanding, remaining)
        remaining -= to_pay

        allocations.append(AllocationLine(
            invoice_id=inv.invoice_id,
            amount_paid=to_pay,
            discount_taken=discount
                if to_pay == outstanding
                else Decimal(0),
        ))

        if remaining <= Decimal(0):
            break

    return allocations

BR-PAY-005: Unapplied Balance Allocation

     if       purch-unapplied = zero
              go to value-input.
*>
     move     purch-unapplied to display-8 amt-ok.
     display  "Unapplied Balance - " at 0645
              with foreground-color 2.
     display  display-8 at 0665
              with foreground-color 3.
     display  "Do you wish to allocate the "
              "unapplied Balance to this "
              "account?  [Y]" at 1601
              with foreground-color 2.
     move     "Y" to ws-reply.
*>
 accept-unappl-reqst.
*>
     accept   ws-reply at 1666
              with foreground-color 6 update.
     if       cob-crt-status = cob-scr-esc
              go to new-payment-Main.
     move     function upper-case (ws-reply)
              to ws-reply.
     if       ws-reply not = "Y"
         and  not = "N"
              go to accept-unappl-reqst.
     if       ws-reply = "N"
              go to value-input.
*>
     move     6 to transaction-type.
*>
 accept-unappl-money.
*>
     perform  accept-money2.
     if       amt-ok = zero
              go to new-payment-Main.
     if       amt-ok > purch-unapplied
              go to accept-unappl-money.
*>
     subtract amt-ok from purch-unapplied.
     move     amt-ok to pay-value.

from decimal import Decimal
from pydantic import BaseModel, validator

class UnappliedAllocationRequest(BaseModel):
    supplier_id: int
    allocation_amount: Decimal

    @validator("allocation_amount")
    def validate_amount(cls, v):
        if v <= Decimal(0):
            raise ValueError(
                "Allocation amount must be "
                "positive"
            )
        return v

def allocate_unapplied_balance(
    request: UnappliedAllocationRequest,
    db: Session,
) -> AllocationResult:
    """Allocate unapplied supplier balance.

    Validates that amount does not exceed
    the current unapplied balance.
    """
    supplier = get_supplier(
        db, request.supplier_id)

    if supplier.unapplied_balance == Decimal(0):
        raise PaymentValidationError(
            detail="No unapplied balance",
        )

    if (request.allocation_amount
            > supplier.unapplied_balance):
        raise PaymentValidationError(
            detail=(
                "Amount exceeds unapplied "
                f"balance of "
                f"{supplier.unapplied_balance}"
            ),
        )

    supplier.unapplied_balance -= (
        request.allocation_amount)
    db.commit()

    return AllocationResult(
        amount=request.allocation_amount,
        remaining=supplier.unapplied_balance,
        transaction_type=6,
    )

BR-PAY-006: Payment Age Calculation

     subtract oi-date  from  run-date
              giving  work-1.
*>
*>  Are we in time to take prompt pay
*>  discount ?
*>
     if       oi-deduct-days not < work-1
              subtract oi-deduct-amt
                  from amount-out
              move oi-deduct-amt
                  to pay-deduct (a)
              if   amount-out = zero
                   go to read-open-item
              else
               if   amount-out < zero
                    display PL901 at 2301
                    accept ws-reply at 2346
                    go to read-open-item.
*>
*> now work out ageing
*>
     move     amount-out  to  pay-value (a).
     if       work-1  <  30
              add  amount-out  to  bal-0
              move  0  to  pay-period (a)
     else
      if      work-1  <  60
              add  amount-out  to  bal-30
              move  30  to  pay-period (a)
      else
       if     work-1  <  90
              move  60  to  pay-period (a)
              add  amount-out  to  bal-60
       else
              move  90  to  pay-period (a)
              add  amount-out  to  bal-90.

from dataclasses import dataclass, field
from datetime import date
from decimal import Decimal

AGING_BUCKETS = [
    (30, "current"),
    (60, "30_days"),
    (90, "60_days"),
    (None, "90_plus"),
]

@dataclass
class AgingResult:
    current: Decimal = field(
        default_factory=Decimal)
    days_30: Decimal = field(
        default_factory=Decimal)
    days_60: Decimal = field(
        default_factory=Decimal)
    days_90_plus: Decimal = field(
        default_factory=Decimal)

def calculate_aging(
    invoices: list[OpenItem],
    run_date: date,
) -> AgingResult:
    """Categorize outstanding amounts
    into 30/60/90+ day aging buckets."""
    result = AgingResult()

    for inv in invoices:
        outstanding = inv.outstanding_amount
        if outstanding <= Decimal(0):
            continue

        days = (run_date - inv.invoice_date).days

        # Apply prompt payment discount
        if inv.deduct_days >= days:
            outstanding -= inv.deduct_amt

        if days < 30:
            result.current += outstanding
        elif days < 60:
            result.days_30 += outstanding
        elif days < 90:
            result.days_60 += outstanding
        else:
            result.days_90_plus += outstanding

    return result

Test Cases — Calculation Rules

10.4 Workflow Rules

BR-PAY-003: Payment Batch Control Limits

 set-batch-item.
*>
     if       bl-next-batch = zero
              move 1 to bl-next-batch.
     move     bl-next-batch  to  display-n.
     add      1  to  k.
     display  display-n at 0770
              with foreground-color 2.
     display  k at 0776
              with foreground-color 2.

*>   ... later in main-end ...

     move     pay-customer  to  oi-supplier.
     move     pay-date  to  oi-date.
     move     transaction-type to  oi-type.
     move     pay-value to  oi-paid.
     move     approp-amount  to  oi-approp.
     move     deduct-taken   to  oi-deduct-amt.
     move     bl-next-batch  to  oi-b-nos.
     move     k           to  oi-b-item.
     multiply oi-b-nos by 1000
              giving oi-invoice.
     add      oi-b-item to oi-invoice.
*>
     perform  OTM5-Write.

from sqlalchemy import Sequence

batch_seq = Sequence("payment_batch_seq")

class PaymentBatch(Base):
    __tablename__ = "payment_batches"

    batch_id: int = Column(
        Integer,
        batch_seq,
        primary_key=True,
    )
    created_at: datetime = Column(
        DateTime, default=func.now())

class PaymentBatchItem(Base):
    __tablename__ = "payment_batch_items"

    id: int = Column(
        Integer, primary_key=True,
        autoincrement=True)
    batch_id: int = Column(
        Integer,
        ForeignKey("payment_batches.batch_id"),
        nullable=False)
    item_sequence: int = Column(
        Integer, nullable=False)
    supplier_id: int = Column(Integer)
    payment_date: date = Column(Date)
    transaction_type: int = Column(Integer)
    paid_amount: Decimal = Column(
        Numeric(12, 2))
    appropriated_amount: Decimal = Column(
        Numeric(12, 2))
    deduction_taken: Decimal = Column(
        Numeric(12, 2))

    # Composite reference preserves
    # legacy batch/item audit trail
    @property
    def legacy_invoice_ref(self) -> int:
        return (self.batch_id * 1000
                + self.item_sequence)

BR-PAY-004: Payment Method Determination

     if       pay-sortcode = zero
              move cheque-nos to c-cheque
                                 pay-cheque
              add 1 to cheque-nos
     else
              move zero     to pay-cheque
              move "BACS"   to c-cheque-x
     end-if
     write cheque-record from cheque.

from enum import Enum

class PaymentMethod(str, Enum):
    CHEQUE = "CHEQUE"
    BACS = "BACS"

def determine_payment_method(
    supplier: Supplier,
    db: Session,
) -> PaymentInstrument:
    """Determine payment method based on
    supplier sort code presence."""

    if not supplier.sort_code:
        # No sort code: issue cheque
        cheque_number = next_cheque_number(db)
        return PaymentInstrument(
            method=PaymentMethod.CHEQUE,
            reference=str(cheque_number),
        )
    else:
        # Valid sort code: BACS transfer
        return PaymentInstrument(
            method=PaymentMethod.BACS,
            reference="BACS",
        )

Test Cases — Workflow Rules

10.5 State Transition Rules

BR-PAY-007: Remittance Advice Processing Rules

     perform  varying z from 1 by 1
              until z > 9
              move  c-inv (z)    to  l4-inv
              move  c-folio (z)  to  l4-folio
              move  c-value (z)  to  l4-amount
              if    l4-amount  not equal  spaces
                    write  print-record
                           from  line-4 after 1
     end-perform.
*>
     write     print-record
               from  line-5 after 3  lines.
*>
     if       C-Cheque not = "BACS"
              move "Cheque"  to  l6-chq-bacs
              move C-Cheque  to  l6-cheque
     else
              move "BACS" to l6-chq-bacs
              move "to your Bank" to l6-cheque.
     move     c-gross   to  l6-total.
*>
     write    print-record
              from  line-6 after 1.

from dataclasses import dataclass
from decimal import Decimal

@dataclass
class RemittanceLine:
    invoice: str
    folio: str
    amount: Decimal

def build_remittance_advice(
    payment: PaymentRecord,
) -> RemittanceAdvice:
    """Generate remittance advice content.

    Skips invoice lines with zero amounts.
    Formats payment method display based
    on cheque/BACS status.
    """
    lines = [
        RemittanceLine(
            invoice=item.invoice,
            folio=item.folio,
            amount=item.value,
        )
        for item in payment.line_items
        if item.value  # skip zero amounts
    ]

    if payment.cheque_ref != "BACS":
        method_label = "Cheque"
        method_ref = payment.cheque_ref
    else:
        method_label = "BACS"
        method_ref = "to your Bank"

    return RemittanceAdvice(
        supplier=payment.supplier,
        lines=lines,
        method_label=method_label,
        method_reference=method_ref,
        total=payment.gross_amount,
    )

Test Cases — State Transition Rules

10.6 Modernization Enhancement Rules

BR-PAY-008: Selective Invoice Exclusion

*> payment-appropriate section (pl080.cbl:540)
*> ============================================
*> Invoices are processed ONE AT A TIME in a
*> sequential loop. There is NO pre-selection
*> mechanism. The only way to "skip" an invoice
*> is to enter zero during interactive input.
*>
 pay-loop.
*>*******
     perform  OTM5-Read-Next.
     if       fs-reply = 10
              go to  main-end.
     move     open-item-record-5  to  oi-header.
*>
     if       oi-type not = 2
              go to  pay-loop.
     if       oi-supplier not = pay-customer
              go to main-end.
     if       oi-b-nos not = zero
              go to pay-loop.
*>
*>   [... display invoice, accept payment amount]
*>
     move     pay-paid to amt-ok.
     perform  accept-money2.
     move     amt-ok to pay-paid.
*>
     if       pay-paid = zero
              move  zero  to  pay-paid display-s
*>            ^^^ ONLY skip mechanism: enter zero
*>            No batch pre-selection exists
              go to  end-line-2.

from decimal import Decimal
from pydantic import BaseModel

class AllocationRequest(BaseModel):
    supplier_code: str
    payment_amount: Decimal
    excluded_invoices: list[str] = []

def allocate_payment(
    request: AllocationRequest,
    open_items: list[OpenItem],
) -> AllocationResult:
    """Allocate payment oldest-first, honoring
    operator exclusions (BR-PAY-008).

    Excluded invoices are skipped during
    allocation but remain in the open items
    list for future payment runs.

    BR-PAY-002 governs allocation order for
    the remaining included invoices.
    """
    eligible = [
        oi for oi in open_items
        if oi.invoice_number
            not in request.excluded_invoices
        and oi.status == "OPEN"
    ]
    # Sort oldest-first (BR-PAY-002)
    eligible.sort(key=lambda oi: oi.invoice_date)

    remaining = request.payment_amount
    allocations = []
    for item in eligible:
        if remaining <= Decimal("0"):
            break
        amount = min(remaining, item.outstanding)
        discount = calculate_discount(
            item, pay_date=date.today()
        )
        allocations.append(Allocation(
            invoice=item.invoice_number,
            amount=amount,
            discount=discount,
        ))
        remaining -= amount

    return AllocationResult(
        allocations=allocations,
        excluded=request.excluded_invoices,
        unapplied=remaining,
    )

Test Cases — Modernization Enhancement Rules

10.7 Business Rule Traceability

10.8 Rule Validation Strategy

Unit Testing Approach

Each business rule maps to a focused unit test suite. Calculation rules (BR-PAY-002, BR-PAY-005, BR-PAY-006) are tested with pure functions that accept domain objects and return results, enabling comprehensive boundary testing without database or API dependencies. The discount eligibility check in BR-PAY-002 is particularly critical: test cases must verify the "add 1 to deduct_days" boundary condition that determines whether a payment qualifies for prompt payment discount. Validation rules (BR-PAY-001) are tested by asserting pre-condition failures produce the correct rejection behavior.

Integration Testing Approach

Integration tests verify rule interactions across the payment lifecycle: entry (BR-PAY-005 unapplied allocation) → appropriation (BR-PAY-002 discount calculation) → batch tracking (BR-PAY-003 composite keys) → proof validation (BR-PAY-001 flag check) → cash posting → generation (BR-PAY-004 method routing) → remittance (BR-PAY-007 output formatting). These tests run against a PostgreSQL test database and verify that the full payment cycle produces the same financial outcomes as the legacy system for a reference set of supplier accounts with known payment histories.

Regression Testing Approach

Behavioral equivalence is validated by running the legacy COBOL system and the modernized Python services in parallel against identical input data, then comparing outputs at three checkpoints: (1) payment batch totals after entry, (2) GL posting amounts after cash posting, and (3) remittance advice content after generation. Any divergence triggers investigation to determine whether it represents a genuine behavioral difference or a precision improvement (e.g., Python Decimal vs COBOL fixed-point rounding). The aging report (BR-PAY-006) serves as a particularly useful regression baseline because it aggregates multiple rule interactions into a single comparable output.

11. Migration Strategy

The migration follows a strangler-fig pattern — progressively routing functionality from the legacy COBOL system to the new Python services while maintaining full business continuity. The legacy system remains authoritative throughout the transition until explicit cutover criteria are met at each phase.

The strangler-fig approach is particularly well-suited to ACAS Payment Processing because the existing acas032 file handler abstraction (confidence 0.80 as an integration boundary) already separates payment business logic from data access. This dual-mode abstraction — which routes operations between ISAM files and MySQL based on a runtime configuration flag (FS-Cobol-Files-Used) — becomes the natural interception point where traffic can be redirected from legacy to modern services without modifying the upstream COBOL programs.

11.1 Migration Phase Details

11.2 Dual-Write Implementation Pattern

During Phase 2, the dual-write mechanism ensures data consistency between PostgreSQL (new) and MySQL (legacy). Legacy MySQL remains the authoritative system throughout Phase 2 — in any conflict, the legacy value takes precedence.

sequenceDiagram
    participant Client
    participant ALB as Application Load Balancer
    participant New as Payment API Service
(FastAPI / PostgreSQL)
    participant Sync as Sync Worker
    participant Legacy as Legacy MySQL

    Client->>ALB: POST /payments
    ALB->>New: Route (weighted target group)
    New->>New: Validate + process payment
    New->>New: Write to PostgreSQL (primary)
    New->>Sync: Emit sync event
    Sync->>Legacy: Write to MySQL (secondary)
    Sync->>Sync: Verify write success
    alt Sync failure
        Sync->>Sync: Queue for retry (exponential backoff)
        Sync->>New: Flag payment for reconciliation
    end
    New->>Client: 201 Created (payment_id)
        

The sync worker operates asynchronously after the primary write succeeds, ensuring that write latency is not doubled. Failed syncs are retried with exponential backoff and dead-letter queuing. A nightly reconciliation job compares transaction counts, batch totals, and account balances between the two databases, flagging any discrepancies for manual review.

11.3 Rollback Strategy

11.4 Traffic Routing Mechanism

Traffic routing leverages ALB weighted target groups to progressively shift requests between legacy and modern services. The ALB routes based on path prefixes: /api/v1/payments/* routes to the new ECS services, while legacy terminal sessions continue to connect directly to the COBOL programs via the existing menu system (pl900).

During Phase 2, the ALB weight distribution is controlled through infrastructure-as-code parameters, enabling precise traffic percentages (10%, 25%, 50%, 75%, 100%) with the ability to instantly revert to 0% for new services in case of issues. CloudWatch alarms on error rate and latency metrics automatically trigger weight reduction if thresholds are breached.

11.5 Monitoring & Success Criteria

A dedicated CloudWatch dashboard tracks all metrics in real time. Composite alarms combine error rate, latency, and transaction parity signals to provide a single "migration health" indicator. PagerDuty integration ensures on-call engineers are notified within 2 minutes of any threshold breach.

11.6 Historical Data Access Pattern

Historical payment data from the legacy system is migrated to PostgreSQL during Phase 1 using a batch ETL process modeled on the existing paymentsLD.cbl data loader (515 LOC) and paymentsUNL.cbl data export utility (219 LOC). The migration transforms legacy COBOL record formats — fixed-length PIC X(N) fields, PIC S9(N)V9(M) packed decimals, and YYYYMMDD date strings — into PostgreSQL native types with ISO 8601 timestamps.

After cutover (Phase 3), the legacy MySQL database is retained as a read-only archive for 12 months, accessible through a dedicated read-only replica. This ensures that any payment history queries referencing legacy record formats or batch numbering schemes can be satisfied during the transition period. After 12 months, the archive is exported to S3 in Parquet format for long-term retention and the MySQL instance is decommissioned.

Appendices

Advanced analysis and deployment artifacts

Appendix B: Service Architecture Analysis

This appendix documents the complete multi-agent service architecture analysis for the Payment Processing subsystem. Three independent analyses — Domain-Driven Design, Technical Architecture, and Business Architecture — each proposed a service decomposition based on Cognatix AI's deep structural analysis of 32 files, 24 entities, 6 business rules, and 4 integration boundaries. A weighted tiebreaker evaluation selected the winning architecture.

B.1 Analysis Methodology

Each perspective analyzed the same codebase intelligence independently, applying its own decomposition principles. The evaluation used four weighted criteria: Operational Complexity (20%), Business Alignment (30%), Technical Soundness (30%), and Change Velocity (20%). A minimum weighted score of 7.0 was required for acceptance.

B.2 DDD Perspective: 2-Service Architecture

The Domain-Driven Design analysis identified a single bounded context (PaymentProcessing, confidence 0.77) with a single aggregate root (Payment, confidence 0.90). The Payment aggregate owns OpenItemPaymentRecords and PaymentBatchControl, with all 6 business rules applying to this aggregate. DDD principles dictate that splitting the aggregate across services would create distributed transaction complexity without domain justification.

The DDD proposal separated only the RemittanceAdviceGeneration workflow (confidence 0.70, MEDIUM complexity) into its own service, since it has an independent state machine and reads payment data without modifying it.

graph LR
    subgraph SVC1["Payment Processing Service"]
        PE["Payment Entry
(pl080, sl080)"]
        PA["Payment Amendment
(pl085, sl085)"]
        PP["Proof & Posting
(pl090-pl100, sl090-sl100)"]
        PG["Payment Generation
(pl910-pl950)"]
    end

    subgraph SVC2["Remittance Advice Service"]
        RA["Remittance Advice
(pl960)"]
    end

    SVC1 -->|"PaymentCompleted
(EventBridge)"| SVC2
    SVC1 -->|"PaymentPosted
(EventBridge)"| GL["General Ledger"]

    style SVC1 fill:#c4dad2,stroke:#1a4442,color:#1a4442
    style SVC2 fill:#f4c4b8,stroke:#1a4442,color:#1a4442
    style GL fill:#f5efe4,stroke:#1a4442,color:#1a4442
        

B.3 Technical Perspective: 3-Service Architecture (Winner)

The Technical Architecture analysis focused on workload profiles, code coupling, scalability requirements, and deployment independence. Analysis of the 32 Payment Processing files revealed three distinct workload clusters with different resource requirements and scaling patterns.

Workload Analysis

graph TB
    subgraph Client["Client Layer"]
        UI["React SPA"]
    end

    subgraph ALB["Application Load Balancer"]
        Routes["Path-Based Routing"]
    end

    subgraph ECS["ECS Fargate Cluster"]
        subgraph SVC1["Payment API Service
3,742 LOC | 0.5 vCPU | 1 GB"]
            API1["Payment Entry"]
            API2["Payment Amendment"]
            API3["Payment Due Mgmt"]
        end

        subgraph SVC2["Payment Batch Service
5,176 LOC | 1.0 vCPU | 2 GB"]
            BAT1["Proof Sort & Report"]
            BAT2["Cash Posting"]
            BAT3["Payment Generation"]
            BAT4["Remittance Advice"]
        end

        subgraph SVC3["Reporting Service
1,133 LOC | 0.25 vCPU | 0.5 GB"]
            RPT1["Aging Analysis"]
            RPT2["Payment Due Reports"]
        end
    end

    subgraph Data["Data Layer"]
        PG[("PostgreSQL RDS")]
        PGRR[("Read Replica")]
    end

    subgraph Events["Event Layer"]
        EB["Amazon EventBridge"]
    end

    UI --> Routes
    Routes -->|"/api/v1/payments/*"| SVC1
    Routes -->|"/api/v1/batch/*"| SVC2
    Routes -->|"/api/v1/reports/*"| SVC3

    SVC1 --> PG
    SVC2 --> PG
    SVC3 --> PGRR

    SVC1 -->|"PaymentCreated
PaymentAmended"| EB
    EB -->|"Trigger batch"| SVC2
    SVC2 -->|"PaymentPosted"| EB
    EB -->|"GL Integration"| GL["General Ledger"]

    style Client fill:#f5efe4,stroke:#1a4442,color:#1a4442
    style ALB fill:#f5efe4,stroke:#1a4442,color:#1a4442
    style ECS fill:#ffffff,stroke:#1a4442,color:#1a4442
    style SVC1 fill:#c4dad2,stroke:#1a4442,color:#1a4442
    style SVC2 fill:#89c5b8,stroke:#1a4442,color:#1a4442
    style SVC3 fill:#f4c4b8,stroke:#1a4442,color:#1a4442
    style Data fill:#e8a598,stroke:#1a4442,color:#1a4442
    style Events fill:#f5efe4,stroke:#1a4442,color:#1a4442
        

Code Coupling Evidence

B.4 Business Perspective: 3-Service Architecture

The Business Architecture analysis identified three value streams within Payment Processing, each with distinct business owners, operational frequencies, and regulatory impacts. The analysis mapped the 6 entry points and 6 business rules to organizational team boundaries.

The Business proposal's primary strength was mapping services directly to organizational teams and value streams, enabling independent feature evolution per business function. Its weakness was combining reporting and document generation (different resource profiles) into one service.

B.5 Tiebreaker Evaluation Matrix

Technical and Business proposals tied at 7.65. The tiebreaker rule (prefer business alignment when within 0.5 points) was considered, but the Technical proposal's significantly higher Technical Soundness score (8.5 vs 6.5) justified selecting it as the foundation. The winning hybrid architecture adopts the Technical proposal's workload-based decomposition with the Business proposal's team ownership model.

B.6 Winning Architecture: Service Specifications

Service 1: Payment API Service

Key API Endpoints:

Service 2: Payment Batch Service

Key API Endpoints:

Service 3: Reporting Service

Key API Endpoints:

B.7 Inter-Service Integration Pattern

Services communicate through two channels, mirroring the legacy split between direct COBOL CALL statements (synchronous) and batch-deferred operations (asynchronous):

sequenceDiagram
    participant UI as React SPA
    participant API as Payment API Service
    participant Batch as Payment Batch Service
    participant Report as Reporting Service
    participant EB as Amazon EventBridge
    participant GL as General Ledger

    UI->>API: POST /payments (create payment)
    API->>API: Validate, appropriate, assign batch
    API->>EB: Emit PaymentCreated event
    API->>UI: 201 Created

    EB->>Batch: PaymentCreated (async trigger)
    Note over Batch: Queues for proof processing

    UI->>Batch: POST /batch/proof (trigger proof)
    Batch->>Batch: Sort, validate, generate proof report
    Batch->>EB: Emit PaymentProofed event

    UI->>Batch: POST /batch/post (trigger cash posting)
    Batch->>Batch: Validate p-flag-p=2, post to GL
    Batch->>EB: Emit PaymentPosted event
    EB->>GL: GL batch record creation

    Batch->>EB: Emit PaymentCompleted event
    EB->>Batch: Trigger remittance advice generation

    UI->>Report: GET /reports/aging-summary
    Report->>Report: Query read replica
    Report->>UI: Aging report data
        

B.8 Data Sharing Strategy

All three services share a single PostgreSQL RDS instance with role-based access controls. This shared-database approach is appropriate for a single bounded context (PaymentProcessing, confidence 0.77) and avoids the operational complexity of database-per-service for a 32-file subsystem:

B.9 Implementation Roadmap

Appendix C: Deployment and Infrastructure

This appendix provides complete, deployable AWS CDK infrastructure-as-code for the Payment Processing microservices on AWS ECS Fargate. The stack provisions all three services (Payment API, Payment Batch, Reporting), the shared PostgreSQL RDS instance, Amazon EventBridge event bus, Application Load Balancer with path-based routing, OpenTelemetry Collector sidecar, and all supporting resources. All environment variables, health probe paths, and observability dependencies follow the resolved target patterns from Section 4.

C.1 Project Dependencies

requirements.txt (application)

# API Framework
fastapi>=0.110.0
uvicorn[standard]>=0.27.0
pydantic>=2.5.0

# Database
sqlalchemy[asyncio]>=2.0.25
asyncpg>=0.29.0
alembic>=1.13.0

# Observability - structlog + OpenTelemetry
structlog>=23.1.0
opentelemetry-api>=1.20.0
opentelemetry-sdk>=1.20.0
opentelemetry-exporter-otlp-proto-grpc>=1.20.0
opentelemetry-instrumentation-fastapi>=0.41b0
opentelemetry-instrumentation-sqlalchemy>=0.41b0
opentelemetry-instrumentation-botocore>=0.41b0

# AWS SDK
boto3>=1.34.0

# Testing
pytest>=7.4.0
pytest-asyncio>=0.23.0
httpx>=0.26.0

requirements-cdk.txt (infrastructure)

aws-cdk-lib>=2.120.0
constructs>=10.3.0

C.2 CDK Stack: Payment Processing Infrastructure

"""
AWS CDK Stack: Payment Processing on ECS Fargate

Provisions:
  - VPC with public/private subnets
  - PostgreSQL RDS instance (shared across services)
  - ECS Fargate cluster with 3 services
  - ALB with path-based routing
  - EventBridge event bus for async integration
  - OpenTelemetry Collector sidecar for distributed tracing
  - Secrets Manager for database credentials
  - CloudWatch log groups for each service

Target patterns applied:
  - FastAPI on ECS Fargate (container platform)
  - PostgreSQL 16+ (Amazon RDS)
  - OpenTelemetry + structlog (observability)
  - Health checks: readiness + liveness + startup
  - EventBridge (async inter-service communication)
"""

from aws_cdk import (
    Duration,
    RemovalPolicy,
    Stack,
    aws_ec2 as ec2,
    aws_ecs as ecs,
    aws_ecs_patterns as ecs_patterns,
    aws_elasticloadbalancingv2 as elbv2,
    aws_events as events,
    aws_logs as logs,
    aws_rds as rds,
    aws_secretsmanager as sm,
)
from constructs import Construct


class PaymentProcessingStack(Stack):
    """Complete ECS Fargate infrastructure for
    the Payment Processing microservices."""

    def __init__(
        self,
        scope: Construct,
        construct_id: str,
        *,
        environment: str = "production",
        **kwargs,
    ) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # -------------------------------------------------------
        # VPC: 2 AZs, public + private subnets, NAT gateway
        # -------------------------------------------------------
        vpc = ec2.Vpc(
            self, "PaymentVpc",
            max_azs=2,
            nat_gateways=1,
            subnet_configuration=[
                ec2.SubnetConfiguration(
                    name="Public",
                    subnet_type=ec2.SubnetType.PUBLIC,
                    cidr_mask=24,
                ),
                ec2.SubnetConfiguration(
                    name="Private",
                    subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
                    cidr_mask=24,
                ),
            ],
        )

        # -------------------------------------------------------
        # Secrets Manager: database credentials
        # Replaces hardcoded connection strings in legacy config
        # -------------------------------------------------------
        db_secret = sm.Secret(
            self, "DbSecret",
            secret_name="payment-processing/db-credentials",
            generate_secret_string=sm.SecretStringGenerator(
                secret_string_template='{"username": "payment_app"}',
                generate_string_key="password",
                exclude_punctuation=True,
                password_length=32,
            ),
        )

        # -------------------------------------------------------
        # PostgreSQL RDS: replaces dual ISAM/MySQL storage
        # Shared by all 3 services (single bounded context)
        # -------------------------------------------------------
        db_security_group = ec2.SecurityGroup(
            self, "DbSecurityGroup",
            vpc=vpc,
            description="Payment Processing PostgreSQL access",
        )

        database = rds.DatabaseInstance(
            self, "PaymentDb",
            engine=rds.DatabaseInstanceEngine.postgres(
                version=rds.PostgresEngineVersion.VER_16_1,
            ),
            instance_type=ec2.InstanceType.of(
                ec2.InstanceClass.BURSTABLE3,
                ec2.InstanceSize.MEDIUM,
            ),
            vpc=vpc,
            vpc_subnets=ec2.SubnetSelection(
                subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
            ),
            security_groups=[db_security_group],
            credentials=rds.Credentials.from_secret(db_secret),
            database_name="payment_processing",
            multi_az=True,
            allocated_storage=50,
            max_allocated_storage=200,
            backup_retention=Duration.days(14),
            deletion_protection=True,
            removal_policy=RemovalPolicy.RETAIN,
        )

        # Read replica for Reporting Service (read-only access)
        read_replica = rds.DatabaseInstanceReadReplica(
            self, "PaymentDbReplica",
            source_database_instance=database,
            instance_type=ec2.InstanceType.of(
                ec2.InstanceClass.BURSTABLE3,
                ec2.InstanceSize.SMALL,
            ),
            vpc=vpc,
            vpc_subnets=ec2.SubnetSelection(
                subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
            ),
            security_groups=[db_security_group],
        )

        # -------------------------------------------------------
        # EventBridge: async inter-service communication
        # Replaces synchronous COBOL CALL mechanism for GL
        # posting and remittance advice generation
        # -------------------------------------------------------
        event_bus = events.EventBus(
            self, "PaymentEventBus",
            event_bus_name="payment-processing",
        )

        # Archive all events for 30 days (rollback window)
        events.Archive(
            self, "PaymentEventArchive",
            source_event_bus=event_bus,
            event_pattern=events.EventPattern(source=["payment-processing"]),
            retention=Duration.days(30),
        )

        # -------------------------------------------------------
        # ECS Fargate Cluster
        # -------------------------------------------------------
        cluster = ecs.Cluster(
            self, "PaymentCluster",
            vpc=vpc,
            container_insights=True,  # CloudWatch Container Insights
        )

        # -------------------------------------------------------
        # ALB: path-based routing to 3 services
        # Replaces pl900's terminal menu navigation
        # -------------------------------------------------------
        alb = elbv2.ApplicationLoadBalancer(
            self, "PaymentAlb",
            vpc=vpc,
            internet_facing=True,
        )

        listener = alb.add_listener(
            "HttpsListener",
            port=443,
            protocol=elbv2.ApplicationProtocol.HTTPS,
            certificates=[],  # Add ACM certificate ARN
        )

        # Default action returns 404 for unmatched paths
        listener.add_action(
            "DefaultAction",
            action=elbv2.ListenerAction.fixed_response(
                status_code=404,
                content_type="application/json",
                message_body='{"error": "not_found"}',
            ),
        )

        # -------------------------------------------------------
        # Shared OTEL Collector container definition
        # Sidecar pattern: each task runs a collector
        # that receives OTLP from the app container and
        # exports to CloudWatch
        # -------------------------------------------------------
        def add_otel_sidecar(
            task_def: ecs.FargateTaskDefinition,
            service_name: str,
        ) -> None:
            """Add OTEL Collector sidecar to a task definition."""
            task_def.add_container(
                "otel-collector",
                image=ecs.ContainerImage.from_registry(
                    "public.ecr.aws/aws-observability/"
                    "aws-otel-collector:v0.36.0"
                ),
                cpu=64,
                memory_limit_mib=128,
                essential=False,
                logging=ecs.LogDrivers.aws_logs(
                    stream_prefix=f"{service_name}-otel",
                    log_retention=logs.RetentionDays.TWO_WEEKS,
                ),
                environment={
                    "AOT_CONFIG_CONTENT": "",  # Uses default OTLP config
                },
                port_mappings=[
                    ecs.PortMapping(container_port=4317),  # gRPC
                    ecs.PortMapping(container_port=4318),  # HTTP
                ],
            )

        # -------------------------------------------------------
        # Shared environment variables for all services
        # Per observability-instrumentation skill
        # -------------------------------------------------------
        def service_environment(
            service_name: str,
            db_endpoint: str,
        ) -> dict[str, str]:
            """Standard environment variables for a payment service."""
            return {
                # Observability (per skill requirements)
                "OTEL_SERVICE_NAME": service_name,
                "OTEL_SERVICE_VERSION": "1.0.0",
                "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
                "ENVIRONMENT": environment,
                "LOG_LEVEL": "INFO",

                # Database
                "DATABASE_HOST": db_endpoint,
                "DATABASE_PORT": "5432",
                "DATABASE_NAME": "payment_processing",

                # EventBridge
                "EVENT_BUS_NAME": "payment-processing",

                # Application
                "APP_PORT": "8080",
            }

        # -------------------------------------------------------
        # Service 1: Payment API Service
        # Interactive payment operations (pl080, pl085, sl080,
        # sl085, pl900, pl920) - 3,742 LOC legacy
        # -------------------------------------------------------
        payment_api_task = ecs.FargateTaskDefinition(
            self, "PaymentApiTask",
            cpu=512,       # 0.5 vCPU per service spec
            memory_limit_mib=1024,  # 1 GB per service spec
        )

        payment_api_container = payment_api_task.add_container(
            "payment-api",
            image=ecs.ContainerImage.from_asset("./services/payment-api"),
            cpu=448,  # Reserve 64 for OTEL sidecar
            memory_limit_mib=896,
            essential=True,
            environment=service_environment(
                "payment-api-service",
                database.db_instance_endpoint_address,
            ),
            secrets={
                "DATABASE_USER": ecs.Secret.from_secrets_manager(
                    db_secret, field="username"),
                "DATABASE_PASSWORD": ecs.Secret.from_secrets_manager(
                    db_secret, field="password"),
            },
            logging=ecs.LogDrivers.aws_logs(
                stream_prefix="payment-api",
                log_retention=logs.RetentionDays.ONE_MONTH,
            ),
            port_mappings=[
                ecs.PortMapping(container_port=8080),
            ],
            # Health checks per observability skill
            health_check=ecs.HealthCheck(
                command=[
                    "CMD-SHELL",
                    "curl -f http://localhost:8080/api/v1/health/live || exit 1",
                ],
                interval=Duration.seconds(30),
                timeout=Duration.seconds(5),
                retries=3,
                start_period=Duration.seconds(60),
            ),
        )

        add_otel_sidecar(payment_api_task, "payment-api")

        payment_api_service = ecs.FargateService(
            self, "PaymentApiService",
            cluster=cluster,
            task_definition=payment_api_task,
            desired_count=2,  # Min 2 for HA per service spec
            assign_public_ip=False,
            vpc_subnets=ec2.SubnetSelection(
                subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
            ),
        )

        # Auto-scaling: 2-8 tasks on CPU > 70%
        payment_api_scaling = payment_api_service.auto_scale_task_count(
            min_capacity=2,
            max_capacity=8,
        )
        payment_api_scaling.scale_on_cpu_utilization(
            "PaymentApiCpuScaling",
            target_utilization_percent=70,
            scale_in_cooldown=Duration.seconds(300),
            scale_out_cooldown=Duration.seconds(60),
        )

        # ALB target group with health check on readiness probe
        payment_api_target = listener.add_targets(
            "PaymentApiTarget",
            port=8080,
            targets=[payment_api_service],
            priority=10,
            conditions=[
                elbv2.ListenerCondition.path_patterns(
                    ["/api/v1/payments*"]
                ),
            ],
            health_check=elbv2.HealthCheck(
                path="/api/v1/health/ready",
                interval=Duration.seconds(15),
                healthy_threshold_count=2,
                unhealthy_threshold_count=3,
                timeout=Duration.seconds(5),
            ),
            deregistration_delay=Duration.seconds(30),
        )

        # -------------------------------------------------------
        # Service 2: Payment Batch Service
        # Batch processing (pl090-pl100, sl090-sl100,
        # pl940-pl960) - 5,176 LOC legacy
        # -------------------------------------------------------
        batch_task = ecs.FargateTaskDefinition(
            self, "BatchTask",
            cpu=1024,      # 1.0 vCPU per service spec
            memory_limit_mib=2048,  # 2 GB per service spec
        )

        batch_container = batch_task.add_container(
            "payment-batch",
            image=ecs.ContainerImage.from_asset("./services/payment-batch"),
            cpu=960,
            memory_limit_mib=1920,
            essential=True,
            environment=service_environment(
                "payment-batch-service",
                database.db_instance_endpoint_address,
            ),
            secrets={
                "DATABASE_USER": ecs.Secret.from_secrets_manager(
                    db_secret, field="username"),
                "DATABASE_PASSWORD": ecs.Secret.from_secrets_manager(
                    db_secret, field="password"),
            },
            logging=ecs.LogDrivers.aws_logs(
                stream_prefix="payment-batch",
                log_retention=logs.RetentionDays.ONE_MONTH,
            ),
            port_mappings=[
                ecs.PortMapping(container_port=8080),
            ],
            health_check=ecs.HealthCheck(
                command=[
                    "CMD-SHELL",
                    "curl -f http://localhost:8080/api/v1/health/live || exit 1",
                ],
                interval=Duration.seconds(30),
                timeout=Duration.seconds(5),
                retries=3,
                start_period=Duration.seconds(90),  # Longer for batch init
            ),
        )

        add_otel_sidecar(batch_task, "payment-batch")

        batch_service = ecs.FargateService(
            self, "BatchService",
            cluster=cluster,
            task_definition=batch_task,
            desired_count=1,  # Min 1 per service spec
            assign_public_ip=False,
            vpc_subnets=ec2.SubnetSelection(
                subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
            ),
        )

        # Auto-scaling: 1-4 tasks on CPU > 70%
        batch_scaling = batch_service.auto_scale_task_count(
            min_capacity=1,
            max_capacity=4,
        )
        batch_scaling.scale_on_cpu_utilization(
            "BatchCpuScaling",
            target_utilization_percent=70,
            scale_in_cooldown=Duration.seconds(300),
            scale_out_cooldown=Duration.seconds(60),
        )

        batch_target = listener.add_targets(
            "BatchTarget",
            port=8080,
            targets=[batch_service],
            priority=20,
            conditions=[
                elbv2.ListenerCondition.path_patterns(
                    ["/api/v1/batch*"]
                ),
            ],
            health_check=elbv2.HealthCheck(
                path="/api/v1/health/ready",
                interval=Duration.seconds(15),
                healthy_threshold_count=2,
                unhealthy_threshold_count=3,
                timeout=Duration.seconds(5),
            ),
            deregistration_delay=Duration.seconds(30),
        )

        # -------------------------------------------------------
        # Service 3: Reporting Service
        # Read-only reports (pl910, pl930) - 1,133 LOC legacy
        # -------------------------------------------------------
        reporting_task = ecs.FargateTaskDefinition(
            self, "ReportingTask",
            cpu=256,       # 0.25 vCPU per service spec
            memory_limit_mib=512,   # 0.5 GB per service spec
        )

        reporting_container = reporting_task.add_container(
            "reporting",
            image=ecs.ContainerImage.from_asset("./services/reporting"),
            cpu=192,
            memory_limit_mib=384,
            essential=True,
            environment=service_environment(
                "reporting-service",
                # Reporting uses read replica
                read_replica.db_instance_endpoint_address,
            ),
            secrets={
                "DATABASE_USER": ecs.Secret.from_secrets_manager(
                    db_secret, field="username"),
                "DATABASE_PASSWORD": ecs.Secret.from_secrets_manager(
                    db_secret, field="password"),
            },
            logging=ecs.LogDrivers.aws_logs(
                stream_prefix="reporting",
                log_retention=logs.RetentionDays.ONE_MONTH,
            ),
            port_mappings=[
                ecs.PortMapping(container_port=8080),
            ],
            health_check=ecs.HealthCheck(
                command=[
                    "CMD-SHELL",
                    "curl -f http://localhost:8080/api/v1/health/live || exit 1",
                ],
                interval=Duration.seconds(30),
                timeout=Duration.seconds(5),
                retries=3,
                start_period=Duration.seconds(30),
            ),
        )

        add_otel_sidecar(reporting_task, "reporting")

        reporting_service = ecs.FargateService(
            self, "ReportingService",
            cluster=cluster,
            task_definition=reporting_task,
            desired_count=1,  # Min 1 per service spec
            assign_public_ip=False,
            vpc_subnets=ec2.SubnetSelection(
                subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS,
            ),
        )

        # Auto-scaling: 1-4 tasks on request count
        reporting_scaling = reporting_service.auto_scale_task_count(
            min_capacity=1,
            max_capacity=4,
        )
        reporting_scaling.scale_on_cpu_utilization(
            "ReportingCpuScaling",
            target_utilization_percent=70,
            scale_in_cooldown=Duration.seconds(300),
            scale_out_cooldown=Duration.seconds(60),
        )

        reporting_target = listener.add_targets(
            "ReportingTarget",
            port=8080,
            targets=[reporting_service],
            priority=30,
            conditions=[
                elbv2.ListenerCondition.path_patterns(
                    ["/api/v1/reports*"]
                ),
            ],
            health_check=elbv2.HealthCheck(
                path="/api/v1/health/ready",
                interval=Duration.seconds(15),
                healthy_threshold_count=2,
                unhealthy_threshold_count=3,
                timeout=Duration.seconds(5),
            ),
            deregistration_delay=Duration.seconds(30),
        )

        # -------------------------------------------------------
        # Security Group Rules
        # -------------------------------------------------------
        # Allow ECS services to access PostgreSQL
        db_security_group.add_ingress_rule(
            peer=ec2.Peer.ipv4(vpc.vpc_cidr_block),
            connection=ec2.Port.tcp(5432),
            description="ECS services to PostgreSQL",
        )

        # Grant database access to all services
        database.connections.allow_from(
            payment_api_service,
            ec2.Port.tcp(5432),
            "Payment API to primary DB",
        )
        database.connections.allow_from(
            batch_service,
            ec2.Port.tcp(5432),
            "Batch Service to primary DB",
        )
        read_replica.connections.allow_from(
            reporting_service,
            ec2.Port.tcp(5432),
            "Reporting to read replica",
        )

        # Grant EventBridge publish permissions
        event_bus.grant_put_events_to(
            payment_api_task.task_role)
        event_bus.grant_put_events_to(
            batch_task.task_role)

        # Grant Secrets Manager read access
        db_secret.grant_read(payment_api_task.task_role)
        db_secret.grant_read(batch_task.task_role)
        db_secret.grant_read(reporting_task.task_role)

C.3 CDK App Entry Point

"""
CDK App entry point for Payment Processing infrastructure.

Deploy with:
  cdk deploy --context environment=production
  cdk deploy --context environment=staging
"""

import aws_cdk as cdk

from stacks.payment_processing import PaymentProcessingStack

app = cdk.App()

environment = app.node.try_get_context("environment") or "staging"

PaymentProcessingStack(
    app,
    f"PaymentProcessing-{environment.title()}",
    environment=environment,
    env=cdk.Environment(
        account="123456789012",  # Replace with target account
        region="eu-west-1",
    ),
)

app.synth()

C.4 Dockerfile (shared template)

# Multi-stage build for Payment Processing services
# Each service uses this template with a different build context

# Stage 1: Dependencies
FROM python:3.12-slim AS builder

WORKDIR /build
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

# Stage 2: Application
FROM python:3.12-slim

# Install curl for health check probes
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Copy installed dependencies from builder stage
COPY --from=builder /install /usr/local

# Non-root user for security
RUN useradd --create-home appuser
USER appuser
WORKDIR /home/appuser/app

# Copy application code
COPY --chown=appuser:appuser . .

# Expose application port
EXPOSE 8080

# Health check using liveness probe endpoint
HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:8080/api/v1/health/live || exit 1

# Run with uvicorn (async ASGI server for FastAPI)
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080", \
     "--workers", "2", "--loop", "uvloop", "--http", "httptools"]

C.5 Deployment Verification

After deployment, verify the infrastructure using the following checks. These validate that all three services, the database, EventBridge, and observability components are operational.

↑ Back to Table of Contents