Autonomous software engineer for legacy systems.

1# CreditCard Payment System Co. — High Level Design (HLD)
2 
3> Source: `docs/CreditCard Payment System Co - HLD.pdf` (7 pages, C4-style: Context Diagram,
4> Container Diagram, Features/Tasks backlog). This file is the project's readable rendering of
5> that document. The two diagram pages in the PDF are embedded images; the content below is
6> taken from the document's prose, which is the authoritative text.
7 
8## Context Diagram — the two layers
9 
10The platform splits into two layers sitting side by side.
11 
12### Abstraction Infrastructure Layer (left side)
13 
14This layer serves as the gatekeeper and translation pipeline for the platform. It sits outside
15the core logic to simulate network traffic and normalize data before it hits the main systems.
16 
17- **Simulation and Mocking (Yellow):** It hosts virtual environments like the **Mastercard MIPs
18  Simulator** and **VISA VEAs Simulator**. This allows the platform to mimic real-world financial
19  traffic (authorizations and clearing files) safely without needing a live connection to payment
20  card networks.
21- **Message Normalization:** It functions as an interface layer. It accepts complex,
22  network-specific messages (like **ISO 8583** streams), unpacks them, and converts them into a
23  unified **"Common Format"** that the core system understands.
24- **Bidirectional Formatting:** It works in reverse as well. When the system needs to talk back
25  to the networks, this layer translates the internal format back into the strict ISO rules
26  required by Mastercard and VISA.
27 
28### Core Mainframe Layer (right side)
29 
30This layer is the central nervous system of the application. It acts as the secure domain-driven
31engine where the actual business rules, transactional records, and data mutations are processed
32and stored.
33 
34- **Domain-Driven Isolation:** It segments critical financial features into clear boundaries
35  (**Authorization, Financial, Chargeback, Customer, Policies, Fraud, and Rewards**) so components
36  stay modular.
37- **Hybrid Execution Model:** It manages the split-second lifecycle of a transaction by running
38  two distinct operations side-by-side:
39  - **The Real-Time Engine (Pink/Red):** Handles immediate, sub-second responses required to
40    validate credit status, check fraud policies, and safely approve or decline active checkouts.
41  - **The Asynchronous Engine (Green):** Handles the heavy background heavy-lifting like running
42    nightly billing cycles, generating points rewards, balancing ledgers, and running massive
43    file reconciliations.
44- **Data Persistence:** It holds the authoritative datastores (such as the core **Financial
45  database**, **Authorization logs**, and **Chargeback archives**) ensuring full auditing
46  capability and data integrity.
47 
48## Container Diagram — the Core Mainframe Layer's seven domains

1-- =========================================================================
2-- CreditCard Payment System Co. - Customer Domain DDL
3--
4-- The Customer Domain is the source of truth for customer identities and
5-- credit limits (HLD section 4). Its store is a three-level hierarchy
6-- with a product catalog beside it:
7--
8--   CUSTOMER  1 ──< ACCOUNT  1 ──< CREDIT_CARD
9--   PRODUCT   1 ──< ACCOUNT
10--   PRODUCT   1 ──< PRODUCT_PARAMETER
11--
12--   one Customer holds one or many Accounts;
13--   one Account holds one or many Credit Cards;
14--   every Account is opened under exactly one Product;
15--   one Product holds zero or many Product Parameters.
16--
17-- The credit limit is an ACCOUNT-level revolving pool: every card on the
18-- account draws against the same AVAILABLE_CREDIT. The Authorization
19-- Domain's Credit Policies Validator (SAUT002) reads it through the
20-- card's ACCOUNT_ID, and the Orchestrator (OAUT001) debits it on
21-- approval. Create CUSTOMER and PRODUCT before ACCOUNT before
22-- CREDIT_CARD.
23--
24-- Vocabulary: PRODUCT is the commercial product (this file's PRODUCT
25-- table, reached from ACCOUNT.PRODUCT_CODE); NETWORK is the card brand
26-- ('VS' VISA / 'MC' Mastercard) carried on CREDIT_CARD.NETWORK.
27-- =========================================================================
28 
29-- -----------------------------------------------------------------------
30-- PRODUCT: the commercial card product an account is opened under
31-- (e.g. VISA Classic, MC Gold). Identity and descriptive columns only;
32-- every tunable knob lives in PRODUCT_PARAMETER so product behaviour
33-- changes are data, not DDL. Managed by Customers Data Management;
34-- product-based policies (a later change) key off PRODUCT_CODE.
35-- NETWORK links the product to the card brand carried on
36-- CREDIT_CARD.NETWORK.
37-- -----------------------------------------------------------------------
38CREATE TABLE PRODUCT (
39    PRODUCT_CODE   CHAR(4)      NOT NULL PRIMARY KEY,
40    PRODUCT_NAME   VARCHAR(30)  NOT NULL,
41    DESCRIPTION    VARCHAR(100),
42    NETWORK        CHAR(2)      NOT NULL,              -- 'VS' / 'MC'
43    CURRENCY       CHAR(3)      NOT NULL,              -- ISO 4217
44    STATUS         CHAR(8)      NOT NULL,              -- ACTIVE / RETIRED
45    LAUNCH_DATE    CHAR(10)                            -- 'YYYY-MM-DD'
46);
47 
48-- -----------------------------------------------------------------------

1      ******************************************************************
2      * CCUS005 - Product catalog request/response record.
3      * Customer Domain. Linkage for SCUS006: pass a product code OR an
4      * account id OR a card number (SCUS006 resolves the product code
5      * from the most specific key given: card -> account -> product),
6      * get back the product's catalog row.
7      * Status 'OK' found / 'NF' not found / 'ER' DB error.
8      * Note: the card network (CREDIT_CARD.NETWORK, 'VS' / 'MC') is a
9      * different concept from this commercial product.
10      ******************************************************************
11       01  PRODUCT-CATALOG-REC.
12           05  SCUS6-PRODUCT-CODE    PIC X(4).
13           05  SCUS6-ACCOUNT-ID      PIC X(12).
14           05  SCUS6-CARD-NUMBER     PIC X(19).
15           05  SCUS6-STATUS          PIC X(2).
16           05  SCUS6-PRODUCT-NAME    PIC X(30).
17           05  SCUS6-NETWORK         PIC X(2).
18           05  SCUS6-CURRENCY        PIC X(3).
19           05  SCUS6-PRODUCT-STATUS  PIC X(8).
20           05  SCUS6-DESCRIPTION     PIC X(100).
21           05  SCUS6-LAUNCH-DATE     PIC X(10).
22 

1      ******************************************************************
2      * SCUS006 - Product Catalog Read.
3      * Customer Domain. Returns a product's catalog row from PRODUCT.
4      * The caller passes a product code (SCUS6-PRODUCT-CODE), an
5      * account id (SCUS6-ACCOUNT-ID) or a card number
6      * (SCUS6-CARD-NUMBER); the product code is resolved from the most
7      * specific key given (card -> account -> product), so a caller
8      * goes from any of the three to the product in one call.
9      * Status: 'OK' found, 'NF' not found, 'ER' DB error.
10      * PRODUCT_CODE and ACCOUNT_ID are fixed CHAR columns compared
11      * against equal-length host variables, so no RTRIM is needed
12      * there; the PAN is VARCHAR and is RTRIMmed on both sides (same
13      * issue as SAUT001's PAN).
14      ******************************************************************
15       IDENTIFICATION DIVISION.
16 
17       PROGRAM-ID. SCUS006.
18 
19       DATA DIVISION.
20 
21       WORKING-STORAGE SECTION.
22 
23           EXEC SQL INCLUDE SQLCA END-EXEC.
24 
25       01  WS-PRODUCT-CODE    PIC X(4).
26       01  WS-ACCOUNT-ID      PIC X(12).
27       01  WS-PAN             PIC X(19).
28       01  WS-PRODUCT-NAME    PIC X(30).
29       01  WS-NETWORK         PIC X(2).
30       01  WS-CURRENCY        PIC X(3).
31       01  WS-PRODUCT-STATUS  PIC X(8).
32       01  WS-DESCRIPTION     PIC X(100).
33       01  WS-LAUNCH-DATE     PIC X(10).
34 
35       LINKAGE SECTION.
36 
37           COPY CCUS005.
38 
39       PROCEDURE DIVISION USING PRODUCT-CATALOG-REC.
40 
41       000-MAIN SECTION.
42 
43           PERFORM 100-RESET-RESPONSE.
44 
45           PERFORM 200-RESOLVE-PRODUCT-CODE.
46 
47           IF SCUS6-STATUS = 'OK'
48 

1      ******************************************************************
2      * SCUS004 - Card Network Read.
3      * Customer Domain. Returns a card's network ('VS' / 'MC') from
4      * CREDIT_CARD. Status: 'OK' found, 'NF' not found, 'ER' DB error.
5      * The PAN is RTRIMmed on both sides (space-padded host variable;
6      * see SAUT001).
7      ******************************************************************
8       IDENTIFICATION DIVISION.
9 
10       PROGRAM-ID. SCUS004.
11 
12       DATA DIVISION.
13 
14       WORKING-STORAGE SECTION.
15 
16           EXEC SQL INCLUDE SQLCA END-EXEC.
17 
18       01  WS-PAN            PIC X(19).
19       01  WS-NETWORK        PIC X(2).
20 
21       LINKAGE SECTION.
22 
23           COPY CCUS004.
24 
25       PROCEDURE DIVISION USING NETWORK-READ-REC.
26 
27       000-MAIN SECTION.
28 
29           PERFORM 100-READ-NETWORK.
30 
31           GOBACK.
32 
33       000-MAIN-END.
34           EXIT.
35 
36       100-READ-NETWORK SECTION.
37 
38           MOVE SCUS4-CARD-NUMBER TO WS-PAN.
39 
40           EXEC SQL
41               SELECT NETWORK
42               INTO :WS-NETWORK
43               FROM CREDIT_CARD
44               WHERE RTRIM(CARD_NUMBER) = RTRIM(:WS-PAN)
45           END-EXEC.
46 
47           IF SQLCODE = 0
48               MOVE 'OK'       TO SCUS4-STATUS

1      ******************************************************************
2      * SAUT004 - Payment Policies Validator.
3      * Authorization Domain. Called by OAUT001 (Orchestrator).
4      * Applies the payment spending policies in order, first breach
5      * wins:
6      *   1. the card network's per-transaction ceiling
7      *      (PAYMENT_POLICY, read through SPOL001; the network is
8      *      looked up from the card through SCUS004);
9      *   2. the product's Spending Policy by MCC (PRODUCT_PARAMETER
10      *      key MCC_SPEND_LIMIT, list of 'MCC|amount' rows);
11      *   3. the product's Spending Policy by POS entry mode
12      *      (PRODUCT_PARAMETER key POS_SPEND_LIMIT, list of
13      *      'pos-entry-mode|amount' rows).
14      * Product parameters are read through SCUS006/SCUS007 (Customer
15      * Domain). A missing parameter means no limit; any read failure
16      * fails closed (91).
17      * Verdicts resolved from the parameter store via SSYS002 (no
18      * hardcoded code/text): 00 pass, 61 ceiling / spending limit
19      * exceeded, 91 network / policy read failed.
20      ******************************************************************
21       IDENTIFICATION DIVISION.
22 
23       PROGRAM-ID. SAUT004.
24 
25       DATA DIVISION.
26 
27       WORKING-STORAGE SECTION.
28 
29       01  WS-SEQ              PIC 9(4).
30       01  WS-LIMIT            PIC 9(12).
31       01  WS-WALK             PIC X(3).
32       01  WS-CRITERION        PIC X(10).
33       01  WS-LIMIT-TEXT       PIC X(20).
34       01  WS-LIST-KEY         PIC X(50).
35       01  WS-DECLINED         PIC X.
36 
37           COPY CSYS002.
38 
39           COPY CCUS004.
40 
41           COPY CPOL001.
42 
43           COPY CCUS005.
44 
45           COPY CCUS006.
46 
47       LINKAGE SECTION.
48 

1# CreditCard Payment System Co.
2 
3CreditCard Payment System Co. is a complete credit card payment processing platform built in COBOL and DB2 tha
4 
5## 🚀 Key Features
6 
7- **Real-Time Authorization Processing (CICS / COBOL)**: Sub-second online validation engine supporting Master
8- **Asynchronous Batch & EOD Reconciliation (JCL / DB2)**: Automated End-of-Day schedule (`core_mainframe_laye
9- **Central Financial Ledger**: Cleared transactions, reversals, payments and fees post to an audited DB2 ledg
10- **Chargeback Lifecycle**: Dispute intake, validation against the authorization log, resolution, and posting 
11- **Parameter-Driven Governance**: Product-bound policies (overlimit, MCC/POS spending limits, velocity, MCC b
12- **Network Simulation Infrastructure (MIPs & VEAs)**: Python simulator cores with HTTP trigger APIs that emit
13- **Bidirectional Message Normalization**: ISO 8583:1987 ↔ Common Format translation pipelines in the abstract
14- **Modular 7-Domain Mainframe Architecture**: Strict domain separation across Authorization, Financial, Charg
15- **Auditable Financial Persistence**: Centralized DB2 datastores ensuring transactional integrity, audit logg
16 
17## ✅ Verification
18 
19Every domain ships a golden-file test suite under `tests/` (`authorization`, `financial`, `chargeback`, `custo
20 
21## 📐 Conventions
22 
23- All COBOL programs follow the house style in docs/COBOL_STYLE.md (section-based layout with `-END. EXIT.` te
24