# Mainframe Modernization Design: [Programme or application name]

> Solution design for modernizing mainframe applications (COBOL, PL/I, CICS, IMS, JCL batch, Db2, VSAM): estate inventory, business rules extraction, the modernization pattern per application (retain and wrap, rehost, replatform, automated refactor, rewrite, replace), target architecture, online and batch modernization, data conversion (EBCDIC, packed decimal, record layouts) and migration, strangler fig increments with coexistence, integration through MQ and change data capture, non-functional design, equivalence testing and parallel run, cutover and decommissioning, skills and operations, risks and roadmap. It follows the strangler fig pattern described by Martin Fowler and maps to the published mainframe guidance of AWS (AWS Transform for mainframe, AWS Mainframe Modernization) and Microsoft (Azure Architecture Center mainframe scenarios). Replace every `[bracketed]` value and every row marked *Example*. The examples follow a regional bank modernizing its core lending system.

<!--
Guidance: How to use this template
- Use it after the portfolio decision. Legacy Modernization Assessment (`architecture/modernization-assessment`) and Application Migration Assessment (`architecture/application-migration-assessment`) decide which applications move and why; this document designs how the mainframe ones move.
- Start with the inventory and dependency discovery (section 2). Mainframe estates always contain more programs, jobs and data sets than the owners believe; plans built on a guess fail at the first wave.
- Decide the pattern per application, not per estate (section 4). A single estate often mixes rehost, refactor and replace.
- Treat data conversion (section 8) as a design topic in its own right. Code pages, packed decimals, REDEFINES and sort order cause most of the defects found in parallel run.
- Define equivalence and parallel-run acceptance criteria (section 12) before any code is converted, and agree them with the business owners.
- Related documents: Data Migration Strategy (`architecture/data-migration-strategy`), Data Migration Reconciliation (`project/data-migration-reconciliation`), Migration Wave Plan (`project/migration-wave-plan`), Cutover Plan (`project/cutover-plan`), CDC Pipeline Design (`system-design/design-cdc-pipeline`), Integration Design (`architecture/integration-design`), TCO Analysis (`architecture/tco-analysis`), Resilience Tiering and HA/DR Design (`architecture/resilience-tiering-ha-dr-design`).
-->

## Document control

<!-- Guidance: Identify the programme, the applications and LPARs in scope and the business owner. A change of pattern for an application, of target platform or of the coexistence approach is a new major version. -->

| Field | Value |
|---|---|
| Document ID | [MMD-001] |
| Programme | [Name] |
| Applications in scope | [App IDs from the application inventory] |
| Source platform | [z/OS version, LPARs, sysplex, subsystems] |
| Target platform | [Cloud provider and region / On-premises distributed platform] |
| Primary pattern | [Retain and wrap / Rehost / Replatform / Automated refactor / Rewrite / Replace / Mixed] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@lead-solution-architect] |
| Approvers/reviewers | [@business-owner], [@mainframe-systems-lead], [@data-architect], [@security-architect], [@operations-lead] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |
| Related documents | [Modernization assessment], [Business case], [Data migration strategy], [Cutover plan] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Business owner | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Mainframe systems lead | [@name] | [Decision] | YYYY-MM-DD |
| Data architect | [@name] | [Decision] | YYYY-MM-DD |
| Security architect | [@name] | [Decision] | YYYY-MM-DD |
| Architecture board | [@name] | [Decision] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 0.2 | YYYY-MM-DD | [@name] | *Example:* Inventory baselined from discovery tooling; pattern per application agreed |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Approved; increment 1 (customer enquiry) cleared for build |

## Contents

<!-- Guidance: Keep this list aligned with the headings. -->

1. [Scope, drivers and constraints](#1-scope-drivers-and-constraints)
2. [Estate inventory and dependencies](#2-estate-inventory-and-dependencies)
3. [Business rules extraction](#3-business-rules-extraction)
4. [Modernization pattern per application](#4-modernization-pattern-per-application)
5. [Target architecture](#5-target-architecture)
6. [Online transaction modernization](#6-online-transaction-modernization)
7. [Batch modernization and scheduling](#7-batch-modernization-and-scheduling)
8. [Data conversion and migration](#8-data-conversion-and-migration)
9. [Strangler increments and coexistence](#9-strangler-increments-and-coexistence)
10. [Integration](#10-integration)
11. [Non-functional design](#11-non-functional-design)
12. [Testing, equivalence and parallel run](#12-testing-equivalence-and-parallel-run)
13. [Cutover and decommissioning](#13-cutover-and-decommissioning)
14. [Skills, organisation and operations](#14-skills-organisation-and-operations)
15. [Decisions, risks and roadmap](#15-decisions-risks-and-roadmap)
16. [Traceability matrix](#16-traceability-matrix)
17. [Glossary and references](#17-glossary-and-references)

## 1. Scope, drivers and constraints

<!-- Guidance: Say why the programme exists in business terms, what is in and out of scope, and which constraints cannot move (contract end dates, regulatory deadlines, batch windows). Common pitfall: "reduce MIPS cost" as the only driver; it leads to a rehost that keeps every other problem. -->

### 1.1 Scope

[Describe the applications, business capabilities, users and interfaces in scope.] *Example:* Core lending (origination, servicing, repayments, interest, arrears, statements) for 1.4 million loan accounts, running on CICS and IMS with Db2 and VSAM data and a nightly JCL batch. In scope: the lending application group APP-L01 to APP-L06 and their interfaces. Out of scope: deposits (separate programme), the general ledger package and the payments hub, which stay as they are and are integrated through existing interfaces.

### 1.2 Drivers and constraints

| ID | Type | Statement | Source |
|---|---|---|---|
| DRV-01 *(Example)* | Business | Launch new loan products in weeks rather than quarters | Lending strategy |
| DRV-02 *(Example)* | Skills | Six of nine COBOL developers retire within four years | HR workforce plan |
| DRV-03 *(Example)* | Cost | Software licence renewal for the mainframe stack due in 2029 | Vendor contract |
| CON-01 *(Example)* | Operational | Nightly batch must finish between 22:00 and 02:00 | Operations calendar |
| CON-02 *(Example)* | Regulatory | Loan records retained 10 years after closure and retrievable within 2 working days | Records schedule |
| CON-03 *(Example)* | Regulatory | Outsourcing and ICT third-party rules apply to the target platform | Compliance review |
| CON-04 *(Example)* | Technical | Deposits system keeps using Db2 tables shared with lending until 2028 | Dependency analysis |
| [ID] | [Type] | [Statement] | [Source] |

## 2. Estate inventory and dependencies

<!-- Guidance: Build the inventory from discovery tooling and system catalogues, not from interviews. Count programs, copybooks, jobs, transactions and data sets, and mark what is actually used (from SMF or monitor data over a full business cycle including month end and year end). Common pitfall: missing dead code and unused jobs, which inflate effort, or missing hidden callers, which break increments. -->

### 2.1 Inventory

| Item | Count | Used in last 13 months | Source | Notes |
|---|---|---|---|---|
| COBOL programs *(Example)* | 3,850 | 2,910 | Source library scan and runtime usage | 9.6 million lines including copybooks |
| PL/I programs *(Example)* | 120 | 95 | Source library scan | Interest engine |
| Assembler modules *(Example)* | 64 | 40 | Load library scan | Date and checksum utilities |
| Copybooks *(Example)* | 1,420 | Not applicable | Source library scan | Record layouts for files and messages |
| JCL jobs *(Example)* | 2,600 | 1,870 | Scheduler database | Including 140 month-end and 25 year-end jobs |
| JCL procedures (PROCs) *(Example)* | 310 | 260 | Procedure libraries | |
| CICS transactions *(Example)* | 640 | 410 | CICS statistics | 3270 screens (BMS maps) and web service front ends |
| IMS transactions and databases *(Example)* | 85 transactions, 22 databases | 60 transactions | IMS system definitions | Hierarchical customer history |
| Db2 tables *(Example)* | 780 | 610 | Db2 catalogue | 4.2 TB |
| VSAM data sets *(Example)* | 260 (KSDS, ESDS, RRDS) | 190 | Catalogue and usage | 180 GB |
| Sequential and GDG data sets *(Example)* | 5,400 | Not applicable | Catalogue | Batch intermediates and archives |
| MQ queues *(Example)* | 95 | 72 | MQ definitions | Channels to payments hub and digital channels |
| Third-party products *(Example)* | 18 | 18 | Licence register | Sort, scheduler, report distribution, security, compression |
| [Item] | [Count] | [Used] | [Source] | [Notes] |

### 2.2 Dependency discovery

Record the dependency types and how each was found. Use the result to cut the estate into increments (section 9) that can move with the fewest live links back to the mainframe.

| Dependency type | Discovery method | Result |
|---|---|---|
| Program calls (static and dynamic) | Static analysis of CALL statements; runtime traces for dynamic calls | *Example:* 14 call clusters; 3 utility clusters used by everything |
| Transaction to program | CICS and IMS definitions | *Example:* 410 used transactions map to 1,120 programs |
| Program to data | Static analysis of file and SQL access; Db2 package dependencies | *Example:* 61 Db2 tables shared with deposits |
| Job to data set | JCL analysis and SMF records | *Example:* 230 data sets passed between lending and other applications |
| External interfaces | MQ channels, file transfers, connectors | *Example:* 47 interfaces, 12 of them undocumented |
| [Type] | [Method] | [Result] |

## 3. Business rules extraction

<!-- Guidance: Decide how much logic must be understood, by whom and in what form. Rehost and automated refactor need less rule extraction than a rewrite, but every pattern needs the rules behind regulatory calculations to be documented and tested. Common pitfall: extracting every rule into documents nobody tests; tie each important rule to an executable test case. -->

| Topic | Decision |
|---|---|
| Extraction depth | *Example:* Full extraction for interest, fees, arrears and regulatory reporting; summary only for screens and housekeeping jobs |
| Method | *Example:* Static analysis tooling to locate rules, review by subject matter experts, rules recorded in a rules catalogue with source references |
| Use of AI-assisted analysis | *Example:* Allowed for code explanation and documentation drafts; every extracted rule is reviewed and signed off by an SME; no source code sent to services outside the approved tenancy |
| Representation | *Example:* Each rule has ID, description, inputs, outputs, source program and paragraph, test cases |
| Ownership | *Example:* Business analysts own the catalogue; SMEs approve; testers derive equivalence cases |
| [Topic] | [Decision] |

| Rule ID | Rule | Source | Criticality | Test cases | SME sign-off |
|---|---|---|---|---|---|
| BR-INT-001 *(Example)* | Daily interest accrues on the cleared balance using the product rate and an actual/365 day count | `LNINT010` (PL/I), procedure `ACCRUE_DAILY` | Regulatory | TC-INT-001 to TC-INT-024 | [@sme] YYYY-MM-DD |
| BR-ARR-004 *(Example)* | An account enters arrears stage 2 after two missed instalments, counting partial payments below the threshold as missed | `LNARR020` | Regulatory | TC-ARR-010 to TC-ARR-019 | [@sme] YYYY-MM-DD |
| BR-FEE-012 *(Example)* | Late fee is capped per month and waived for accounts under hardship arrangement | `LNFEE005` | Customer impact | TC-FEE-030 to TC-FEE-036 | [@sme] YYYY-MM-DD |
| [BR-xxx-nnn] | [Rule] | [Program, paragraph] | [Level] | [Cases] | [Sign-off] |

## 4. Modernization pattern per application

<!-- Guidance: Choose a pattern per application or component with explicit criteria. The pattern names are a vocabulary; providers use slightly different names, so record yours. Common pitfall: choosing automated refactor for code nobody understands without budgeting for the testing it needs; conversion is fast, proving equivalence is not. -->

### 4.1 Patterns

| Pattern | What it means here | Fits when | Watch out for |
|---|---|---|---|
| Retain and wrap | Keep the application on the mainframe and expose it through APIs or events | Stable, well-performing logic; other priorities first | Mainframe cost and skills risk remain |
| Rehost | Run the same COBOL and PL/I on an emulation or compatible runtime on distributed hardware, usually with recompilation (binary emulation runs the existing load modules without it) | Fixed exit date; little change demand | Runtime licence lock-in; skills problem not solved |
| Replatform | Rehost plus targeted changes, such as moving VSAM to a relational database or replacing the scheduler | As rehost, with some managed services | Scope creep into a rewrite |
| Automated refactor | Convert code and data with tooling to Java or C# and a relational database, keeping behaviour | Large code base, need to leave COBOL, behaviour must stay | Converted code can be hard to maintain; heavy equivalence testing |
| Rewrite (reimagine) | Rebuild the capability with a new design, using extracted rules | High change demand and value; domain well understood | Longest and riskiest; needs strong rule extraction |
| Replace | Move to a package or SaaS product and migrate data | Non-differentiating capability with a mature market | Fit-gap and customisation; data mapping |
| Retire | Switch off and archive | No longer used, or capability duplicated | Retention and retrieval duties |

### 4.2 Decision criteria

| Criterion | Weight | Question |
|---|---|---|
| Business change demand | *Example:* 25% | How often must this capability change in the next five years? |
| Code health and knowledge | *Example:* 20% | Is the code understood, documented and testable? |
| Coupling | *Example:* 20% | How many programs, tables and jobs does it share with the rest of the estate? |
| Performance and batch criticality | *Example:* 15% | Does it sit on the critical path of the batch or a high-volume online path? |
| Market alternatives | *Example:* 10% | Is there a mature product for this capability? |
| Deadline pressure | *Example:* 10% | Must it leave by a fixed date? |

### 4.3 Pattern per application

| App ID | Application | Pattern | Rationale | Target | Increment |
|---|---|---|---|---|---|
| APP-L01 *(Example)* | Customer and account enquiry | Rewrite | High change demand from digital channels; simple read logic | Enquiry services on the container platform | INC-1 |
| APP-L02 *(Example)* | Loan servicing online (CICS) | Automated refactor | 1,900 programs; behaviour must stay; skills risk | Java services on the container platform | INC-3 |
| APP-L03 *(Example)* | Interest and fees engine (PL/I) | Rewrite | Product agility is the main driver; rules extracted | Rules-driven pricing service | INC-2 |
| APP-L04 *(Example)* | Nightly lending batch | Automated refactor | Tightly coupled to APP-L02 data | Batch framework on the target platform | INC-3 |
| APP-L05 *(Example)* | Customer history (IMS) | Replatform | Read-mostly; data moved to relational store | Relational database and read API | INC-2 |
| APP-L06 *(Example)* | Statement printing | Replace | Commodity capability | Customer communications SaaS | INC-1 |
| [APP-nn] | [Name] | [Pattern] | [Why] | [Target] | [INC-n] |

## 5. Target architecture

<!-- Guidance: Show the end state and name the platform services. Keep detail for the High-Level Design (`architecture/high-level-design`); here, show how mainframe concepts map to target concepts. Common pitfall: a target that reproduces the mainframe's shared database in the cloud, which keeps every coupling. -->

```mermaid
flowchart LR
    CH["Digital and branch channels"] --> GW["API gateway (routing facade)"]
    GW --> ENQ["Enquiry services"]
    GW --> SRV["Servicing services (refactored)"]
    GW --> PRC["Pricing service"]
    GW --> CICS["Remaining CICS transactions (mainframe)"]
    ENQ --> RDB[("Relational operational store")]
    SRV --> RDB
    PRC --> RUL[("Rules store")]
    BAT["Batch framework and scheduler"] --> RDB
    CDC["Change data capture from Db2"] --> EVT["Event streaming platform"]
    EVT --> ENQ
    MQ["IBM MQ bridge"] --> EVT
    CICS --> DB2[("Db2 for z/OS")]
    DB2 --> CDC
    EVT --> DP["Data platform"]
```

| Mainframe concept | Target equivalent | Note |
|---|---|---|
| CICS or IMS transaction | *Example:* REST or gRPC service operation behind the API gateway | Unit of work becomes a database transaction per service call |
| BMS map or MFS screen | *Example:* Web front end or channel API | Screen flows redesigned with users |
| COBOL program | *Example:* Java class or service (refactor); new service (rewrite) | |
| Copybook | *Example:* Generated data classes and schema definitions | Kept as the single source for layouts during coexistence |
| JCL job and PROC | *Example:* Batch job definitions in the batch framework, orchestrated by the scheduler | |
| GDG | *Example:* Versioned object storage prefixes with retention rules | |
| VSAM KSDS | *Example:* Relational table with primary key | Check key order after conversion (section 8) |
| Db2 for z/OS | *Example:* Managed relational database | SQL dialect differences reviewed |
| RACF profiles | *Example:* Central identity provider groups and service roles | Section 11 |
| SMF and monitor data | *Example:* Platform observability stack | |

## 6. Online transaction modernization

<!-- Guidance: Describe how online transactions behave on the target: request handling, unit of work, locking, session state and screen replacement. Common pitfall: ignoring pseudo-conversational design and COMMAREA state; the target needs an explicit place for that state. -->

| Topic | Source behaviour | Target design |
|---|---|---|
| Unit of work | *Example:* CICS syncpoint across Db2 and VSAM updates | Single database transaction per service call; VSAM data moved into the same database so no distributed transaction is needed |
| Conversation state | *Example:* Pseudo-conversational with COMMAREA and temporary storage queues | Stateless services; state held by the channel or in a session store with expiry |
| Locking | *Example:* Record locks held during an update task | Optimistic concurrency with version columns; conflicts returned to the caller |
| Volume and latency | *Example:* Peak 900 transactions per second, 95th percentile 180 ms | Same or better at peak plus 30% headroom (section 11) |
| Screens | *Example:* 3270 green screens for back office | Web screens for top 40 transactions by use; the rest retired or merged |
| Error handling | *Example:* ABEND codes and transaction dumps | Structured errors, correlation IDs, alerts |
| [Topic] | [Source] | [Target] |

## 7. Batch modernization and scheduling

<!-- Guidance: Batch is where performance surprises appear. Map the critical path, measure it on the target in a proof of concept and design restart, dependencies and calendars. End the estimate with a consequence for the design. Common pitfall: converting record-by-record COBOL logic to row-by-row database calls; it is often many times slower than the sequential file processing it replaces. -->

### 7.1 Batch inventory and design

| Topic | Decision |
|---|---|
| Scheduler | *Example:* Enterprise scheduler kept as the single orchestrator during coexistence, with agents on the target platform |
| Job structure | *Example:* One job definition per JCL job; steps become tasks; PROC parameters become job parameters |
| Sort and utilities | *Example:* Sort steps replaced by database operations or a distributed sort utility; IDCAMS steps replaced by storage operations |
| Restart | *Example:* Checkpoint per commit interval; each job restartable from the last successful step without manual data fixes |
| Calendars | *Example:* Business day, month-end and year-end calendars migrated and tested with a full year simulation |
| Data hand-offs | *Example:* Files between jobs on shared object storage; file layouts unchanged in increments 1 and 2 |
| [Topic] | [Decision] |

### 7.2 Critical path estimate

| Job | Function | Mainframe (min) | Target, first PoC (min) | Target, after redesign (min) |
|---|---|---|---|---|
| J1 *(Example)* | Extract daily transactions | 35 | 30 | 30 |
| J2 *(Example)* | Sort by account | 20 | 15 | 15 |
| J3 *(Example)* | Post transactions to accounts | 70 | 112 | 34 |
| J4 *(Example)* | Accrue interest | 40 | 38 | 38 |
| J5 *(Example)* | Produce statement extracts | 25 | 20 | 20 |
| Total | | 190 | 215 | 137 |

Consequences: *Example:* The window is 240 minutes and the programme requires a 20% margin, so the critical path must finish in 192 minutes. The first PoC result of 215 minutes fits the window but leaves only 25 minutes (about 10%) of margin, which fails the requirement. J3 posting was redesigned to run in four parallel streams by account range (112 / 4 = 28 minutes plus 6 minutes to merge control totals = 34 minutes), bringing the path to 137 minutes and the margin to 103 minutes (about 43%). Parallel streams require that no account appears in two ranges, which the sort step guarantees.

## 8. Data conversion and migration

<!-- Guidance: Specify conversion rules per field type, not per file, and prove them with test data that includes edge cases (negative values, maximum lengths, low values, high values, redefined fields). Common pitfall: converting a whole record from EBCDIC to ASCII as text, which corrupts every packed and binary field in it. -->

### 8.1 Conversion rules

| Source type | COBOL example | Storage | Conversion rule |
|---|---|---|---|
| Alphanumeric | `PIC X(20)` | 20 bytes EBCDIC | Translate with the agreed code page (for example CCSID 037 or 1140 for US English, 273 or 1141 for German); trim or keep trailing spaces as agreed |
| Zoned decimal | `PIC S9(3)` (DISPLAY) | 1 byte per digit; sign in the zone half of the last byte | Decode digits and sign: +123 is `F1 F2 C3`, -123 is `F1 F2 D3` |
| Packed decimal | `PIC S9(7)V99 COMP-3` | (digits + 1) / 2 bytes, rounded up: 9 digits use 5 bytes | Decode two digits per byte and a sign in the last half byte (`C` positive, `D` negative, `F` unsigned); apply the implied decimal point: +12,345.67 is `00 12 34 56 7C` |
| Binary | `PIC S9(4) COMP` | 2 bytes big-endian; S9(9) uses 4, S9(18) uses 8 | Convert byte order where the target is little-endian; check the compiler TRUNC setting for values above the PIC limit |
| Floating point | `COMP-1`, `COMP-2` | IBM hexadecimal floating point | Convert to IEEE 754 with a documented rounding rule; flag precision changes |
| Dates | `PIC 9(8)` or packed `CYYDDD` | Various | Map each format to a date type; define handling of `00000000`, `99999999` and invalid dates |
| Redefined fields | `REDEFINES` | Same bytes, several layouts | Choose the layout per record from a type field; document the selector rule |
| Variable occurrence | `OCCURS DEPENDING ON` | Variable-length record | Normalise to a child table or array using the counter field |
| Special values | `LOW-VALUES`, `HIGH-VALUES` | `00` or `FF` bytes | Map to null, empty or a sentinel as agreed per field; never translate as characters |

Worked example: a negative amount of -42.50 in `PIC S9(3)V99 COMP-3` has five digits (04250), stored in 3 bytes as `04 25 0D`. Decoding gives digits 04250 with sign D, so the value is -042.50, that is -42.50.

### 8.2 Sort order and keys

EBCDIC and ASCII order characters differently: in EBCDIC lowercase letters sort before uppercase letters and both sort before digits, while in ASCII digits come first, then uppercase, then lowercase. Any key, report or merge logic that depends on order must be checked after conversion.

| Key or ordering | Risk | Decision |
|---|---|---|
| VSAM KSDS keys with mixed letters and digits *(Example)* | Range reads and "next record" logic return different records | Use a binary or EBCDIC collation for those columns, or rewrite range logic |
| Report sort order *(Example)* | Reports differ from the mainframe in parallel run | Compare after sorting both sides with the same collation |
| Control-break processing in batch *(Example)* | Totals split differently | Retest with converted data in J3 and J5 |
| [Key] | [Risk] | [Decision] |

### 8.3 Migration approach

| Data set | Source | Target | Volume | Strategy | Reconciliation |
|---|---|---|---|---|---|
| Loan accounts and history *(Example)* | Db2 tables | Relational operational store | 3.6 TB of the 4.2 TB Db2 estate | Bulk load plus CDC catch-up until cutover | Row counts, balance totals per product, field-level sample (`project/data-migration-reconciliation`) |
| Rate and fee tables *(Example)* | VSAM KSDS | Rules store | 12 GB of the 180 GB VSAM estate, with history | Convert and verify by replaying 3 months of calculations | Calculation parity |
| Tables shared with deposits *(Example)* | Db2 tables (61) | Relational operational store, lending as system of record | 0.6 TB | Bulk load plus CDC catch-up with the loan accounts; reverse feed to deposits after INC-3 (section 9) | Row counts and checksums on both sides of the reverse feed |
| Other lending VSAM files *(Example)* | VSAM KSDS and ESDS | Relational tables in the operational store | 168 GB | Convert with the field rules in 8.1, load with the Db2 data | Record counts, key ranges and control totals |
| Customer history *(Example)* | IMS databases | Relational tables | 900 GB | Unload, flatten hierarchy, load; read-only after INC-2 | Segment counts and checksums |
| [Data set] | [Source] | [Target] | [Volume] | [Strategy] | [Checks] |

Estimate: *Example:* At a measured conversion and load rate of 400 GB per hour, the Db2 data and the other lending VSAM files that move at the INC-3 cutover (3,600 + 600 + 168 = 4,368 GB) take about 10.92 hours. The rate and fee tables (12 GB, a few minutes) and the IMS customer history (900 GB, about 2.25 hours) move earlier, in INC-2. With CDC catch-up after the bulk load, the cutover weekend only needs the final delta and reconciliation, so the 36-hour window in the cutover plan holds with margin. Strategy detail belongs in Data Migration Strategy (`architecture/data-migration-strategy`).

## 9. Strangler increments and coexistence

<!-- Guidance: Plan increments that each move a capability end to end and can be rolled back. For each, state who owns the data (the system of record) during coexistence, which way data is synchronised and how calls are routed. Common pitfall: two-way synchronisation of the same records between mainframe and target; it creates conflicts that nobody can resolve. Prefer one owner per record at any time. -->

The strangler fig pattern replaces a system gradually: a routing facade sends each capability either to the legacy system or to the new implementation, and capabilities move one at a time until the legacy system can be removed. The temporary code that lets both run together (routing, synchronisation, reconciliation) is transitional architecture; budget it and plan its removal.

| Increment | Capability moved | System of record during increment | Data synchronisation | Routing | Rollback | Exit criteria |
|---|---|---|---|---|---|---|
| INC-1 *(Example)* | Account enquiry; statement printing | Mainframe | One-way CDC from Db2 to the enquiry store | Gateway sends enquiry calls to new services, 10% then 50% then 100% | Route back to CICS enquiry transactions | Enquiry results identical on 1 million replayed requests; statements accepted by business |
| INC-2 *(Example)* | Pricing, interest and fees; customer history | Mainframe for accounts; new pricing service for rates | Rates published from the pricing service to the mainframe through MQ | Mainframe batch calls pricing through MQ request and reply | Switch batch back to `LNINT010` | Interest parity within 0.01 currency unit per account for 3 month-ends |
| INC-3 *(Example)* | Servicing online and nightly batch | Target platform after cutover | CDC catch-up until cutover; reverse feed to deposits for shared tables until 2028 | All lending calls to target | Fall back to mainframe within the cutover window only | Parallel run criteria in section 12 met |
| [INC-n] | [Capability] | [Owner] | [Direction] | [Routing] | [Rollback] | [Criteria] |

```mermaid
sequenceDiagram
    participant C as Channel
    participant G as API gateway
    participant N as New enquiry service
    participant M as CICS (mainframe)
    participant D as Db2 for z/OS
    participant Q as CDC and event stream
    C->>G: Get account
    alt Routed to new
        G->>N: Get account
        N-->>G: Account view
    else Routed to legacy
        G->>M: Enquiry transaction
        M->>D: Read
        M-->>G: Account view
    end
    M->>D: Update from servicing
    D-->>Q: Change captured
    Q-->>N: Apply change to enquiry store
```

## 10. Integration

<!-- Guidance: List every interface and decide, per increment, whether it stays on the mainframe, moves or is replaced. Common pitfall: undocumented file transfers found only at cutover; use the job-to-data-set analysis from section 2. -->

| Interface ID | Partner | Mechanism today | During coexistence | Target | Owner |
|---|---|---|---|---|---|
| INT-01 *(Example)* | Payments hub | IBM MQ request and reply | Unchanged; MQ bridge adds events to the stream | Events and APIs on the integration platform | Integration team |
| INT-02 *(Example)* | General ledger | Nightly fixed-length file via managed file transfer | Unchanged layout produced by mainframe until INC-3 | Same layout produced by target batch, then API in a later phase | Finance IT |
| INT-03 *(Example)* | Digital channels | CICS web services | Gateway routes per capability | Native APIs | Digital team |
| INT-04 *(Example)* | Credit bureau | Batch file exchange | Unchanged | Moved with INC-3 | Lending IT |
| INT-05 *(Example)* | Deposits system | Shared Db2 tables | Reverse CDC feed from target to Db2 | API when deposits modernizes | Data architecture |
| [INT-nn] | [Partner] | [Today] | [Coexistence] | [Target] | [@owner] |

Detailed interface design belongs in Integration Design (`architecture/integration-design`) and CDC Pipeline Design (`system-design/design-cdc-pipeline`).

## 11. Non-functional design

<!-- Guidance: Mainframes set a high bar for availability, throughput, security and auditability. Restate the measured current values, the targets and how the target platform will meet them. Common pitfall: converting MIPS to cloud cores with a rule of thumb; size from a benchmark of your own workload on the target. -->

| ID | Quality | Current (measured) | Target | Design response | Verification |
|---|---|---|---|---|---|
| MMD-NFR-001 *(Example)* | Online throughput | 900 TPS peak | 1,170 TPS (peak plus 30%) | Horizontal scaling of stateless services | Load test with production mix |
| MMD-NFR-002 *(Example)* | Online latency | p95 180 ms | p95 at most 200 ms | Database close to services; connection pooling | Load test |
| MMD-NFR-003 *(Example)* | Batch window | 190 min | At most 192 min (20% margin) | Parallel posting (section 7.2) | Full-volume batch run |
| MMD-NFR-004 *(Example)* | Availability | 99.95% monthly | 99.95% monthly | Multi-zone deployment; tier per `architecture/resilience-tiering-ha-dr-design` | DR test |
| MMD-NFR-005 *(Example)* | Security | RACF profiles per transaction and data set | Equivalent or stronger access per role | Role mapping from RACF groups; least privilege service identities | Access review (`ops/access-review`) |
| MMD-NFR-006 *(Example)* | Auditability | SMF and application journals | Tamper-evident audit log per business event | Append-only audit store | Audit walkthrough |
| MMD-NFR-007 *(Example)* | Sizing | 4,200 MIPS installed, 2,900 used by lending at peak | Benchmark-based sizing | PoC benchmark on target hardware | PoC report (`architecture/proof-of-concept`) |
| [MMD-NFR-nnn] | [Quality] | [Current] | [Target] | [Response] | [Method] |

## 12. Testing, equivalence and parallel run

<!-- Guidance: Define equivalence before conversion: what counts as the same result, at which level (field, record, total, report), with which tolerance, and on which data. Common pitfall: comparing outputs that legitimately differ (timestamps, sequence numbers, sort order) without masking them, so the team drowns in false differences. -->

| Test level | Purpose | Data | Pass criterion |
|---|---|---|---|
| Conversion unit tests | Prove field conversion rules | Synthetic edge-case records per copybook | 100% of cases pass |
| Program equivalence | Same outputs for the same inputs, per converted program | Captured inputs and outputs from production (masked) | No unexplained differences |
| Online replay | Same responses for recorded transactions | 1 million recorded requests from a peak day | Identical responses after masking agreed volatile fields |
| Batch equivalence | Same files and database state after each job | Full copy of a month-end business day | Record counts and control totals equal; field differences explained |
| Parallel run | Business-level proof over real cycles | Live inputs fed to both platforms | Criteria below |
| Performance | Meet section 11 | Production volumes | MMD-NFR-001 to MMD-NFR-003 met |

Parallel run acceptance criteria (*Example*):

1. Runs for at least two month-ends and one quarter-end.
2. Account balances, accrued interest and arrears status are equal for every account, with a tolerance of 0.01 currency unit only where a documented rounding change was approved.
3. Every difference is classified as a legacy defect, a target defect or an approved change, and none remains unclassified at the go decision.
4. Interfaces to the general ledger and the payments hub reconcile to the same totals.
5. The business owner signs the parallel run report.

Test strategy detail belongs in Test Strategy (`quality/test-strategy`); reconciliation reports in Data Migration Reconciliation (`project/data-migration-reconciliation`).

## 13. Cutover and decommissioning

<!-- Guidance: Plan the move of the system of record, the point of no return and the switch-off of mainframe components, licences and data. Common pitfall: keeping the mainframe running "just in case" for years; set a decommission date and the evidence needed to meet it. -->

| Topic | Decision |
|---|---|
| Cutover approach | *Example:* Final CDC delta, freeze of mainframe updates, reconciliation, routing switch, smoke tests; detailed in Cutover Plan (`project/cutover-plan`) |
| Point of no return | *Example:* First nightly batch on the target platform completes and posts to the general ledger |
| Fallback before that point | *Example:* Route back to mainframe; replay target transactions to mainframe from the event stream |
| Read-only period | *Example:* Mainframe lending data kept read-only for 90 days for comparison |
| Archive | *Example:* Closed loans archived in a searchable store to meet CON-02; layouts and code pages documented with the archive |
| Licence and contract exit | *Example:* Notice periods for ISV products tracked from the licence register; capacity reduction agreed with the vendor per increment |
| Decommission evidence | *Example:* No lending access for 60 days in SMF data; data archived and verified; security profiles removed |
| [Topic] | [Decision] |

## 14. Skills, organisation and operations

<!-- Guidance: Modernization moves knowledge as well as code. Plan how mainframe experts and new platform engineers work together, and how the target is run. Common pitfall: releasing COBOL experts before parallel run ends, when their knowledge is needed most to explain differences. -->

| Topic | Plan |
|---|---|
| Knowledge retention | *Example:* SMEs paired with each increment team; retention agreements to the end of INC-3 parallel run |
| Upskilling | *Example:* COBOL developers trained on the target language and platform; platform engineers trained on mainframe concepts to read the source |
| Converted code ownership | *Example:* Product teams own refactored services from go-live; coding standards adapted for generated code |
| Operations | *Example:* Run book per batch job; on-call rota covers both platforms during coexistence |
| Monitoring | *Example:* Batch job status, transaction latency, CDC lag and reconciliation status on one dashboard |

| Activity | Programme lead | Mainframe team | Target platform team | Business owner | Test lead |
|---|---|---|---|---|---|
| Inventory and dependency analysis | A | R | C | I | I |
| Rule extraction and sign-off | C | R | C | A | C |
| Conversion and build | A | C | R | I | C |
| Equivalence testing and parallel run | A | C | C | C | R |
| Cutover go decision | R | C | C | A | C |
| Decommissioning | A | R | C | I | I |

## 15. Decisions, risks and roadmap

<!-- Guidance: Record the decisions reviewers will challenge, the main risks and the increment roadmap. Keep the full decision records in the decision log. Common pitfall: a roadmap that ends at the last cutover and omits decommissioning and licence exit, where most of the savings sit. -->

### 15.1 Key decisions

| ID | Decision | Options considered | Choice and reason |
|---|---|---|---|
| MMD-ADR-001 *(Example)* | Programme approach | Big-bang conversion; incremental strangler | Incremental: lower risk, earlier value, learning between increments |
| MMD-ADR-002 *(Example)* | Servicing online | Rehost on emulation; automated refactor to Java | Refactor: removes COBOL skills dependency; budget for equivalence testing approved |
| MMD-ADR-003 *(Example)* | Coexistence data flow | Two-way sync; one owner per record with one-way CDC | One owner per record: avoids conflicts |
| [MMD-ADR-nnn] | [Decision] | [Options] | [Choice] |

Record the full decisions in Architecture Decision Log (`architecture/architecture-decision-log`).

### 15.2 Risks

| ID | Risk | Likelihood | Impact | Mitigation | Owner |
|---|---|---|---|---|---|
| MMD-RSK-01 *(Example)* | Hidden dependencies break an increment | High | High | Runtime usage data over 13 months; dependency review gate per increment | Lead architect |
| MMD-RSK-02 *(Example)* | Converted batch misses the window | Medium | High | PoC on full volume; parallel design (section 7.2) | Batch lead |
| MMD-RSK-03 *(Example)* | Data conversion defects in packed and redefined fields | Medium | High | Field-level rules and edge-case tests (section 8) | Data lead |
| MMD-RSK-04 *(Example)* | Loss of SMEs before parallel run ends | Medium | High | Retention agreements; pairing | Programme lead |
| MMD-RSK-05 *(Example)* | Licence costs do not fall as planned | Medium | Medium | Contract exit plan per increment | Procurement |
| [ID] | [Risk] | [L] | [I] | [Mitigation] | [@owner] |

### 15.3 Roadmap

| Increment | Scope | Start | Go-live | Parallel run end | Decommission |
|---|---|---|---|---|---|
| INC-1 *(Example)* | Enquiry and statements | YYYY-MM-DD | YYYY-MM-DD | YYYY-MM-DD | YYYY-MM-DD |
| INC-2 *(Example)* | Pricing and customer history | YYYY-MM-DD | YYYY-MM-DD | YYYY-MM-DD | YYYY-MM-DD |
| INC-3 *(Example)* | Servicing and batch | YYYY-MM-DD | YYYY-MM-DD | YYYY-MM-DD | YYYY-MM-DD |

Wave detail belongs in Migration Wave Plan (`project/migration-wave-plan`).

## 16. Traceability matrix

<!-- Guidance: Trace drivers and requirements to design elements, increments and tests. Common pitfall: drivers that no increment delivers. -->

| Driver or requirement | Design element | Increment | Test or evidence | Status |
|---|---|---|---|---|
| DRV-01 *(Example)* | Rewrite of pricing (APP-L03), section 4.3 | INC-2 | New product configured in under 2 weeks in UAT | [Planned / Met] |
| DRV-02 *(Example)* | Refactor to Java (MMD-ADR-002), section 14 | INC-3 | COBOL code in production for lending: zero | [Status] |
| CON-01 / MMD-NFR-003 *(Example)* | Parallel posting, section 7.2 | INC-3 | Full-volume batch run at most 192 min | [Status] |
| CON-02 *(Example)* | Archive, section 13 | INC-3 | Retrieval test within 2 working days | [Status] |
| BR-INT-001 *(Example)* | Pricing service rules | INC-2 | TC-INT-001 to TC-INT-024; parallel run | [Status] |
| [ID] | [Element] | [INC-n] | [Evidence] | [Status] |

## 17. Glossary and references

<!-- Guidance: Define mainframe terms for readers from distributed platforms, and list every source with the version you checked. -->

### 17.1 Glossary

| Term | Meaning in this document |
|---|---|
| ABEND | Abnormal end of a program or task |
| CCSID | Coded character set identifier that names a code page, for example 037 or 1140 |
| CICS | Online transaction monitor on z/OS |
| COMMAREA | Communication area that passes data between CICS programs and across pseudo-conversational steps |
| COMP-3 | COBOL packed decimal storage: two digits per byte and a sign half byte |
| Copybook | Source member included in programs, often holding record layouts |
| EBCDIC | Character encoding family used on IBM mainframes |
| GDG | Generation data group: a set of versioned sequential data sets |
| IMS | Hierarchical database (IMS DB) and transaction manager (IMS TM) |
| JCL | Job control language that defines batch jobs and their data sets |
| MIPS | Traditional measure of mainframe processing capacity |
| RACF | Security product on z/OS that controls access to resources |
| SMF | System management facility records that log system and job activity |
| VSAM | File access method with keyed (KSDS), entry-sequenced (ESDS) and relative record (RRDS) data sets |

### 17.2 References

| Reference | Version or date checked | Use |
|---|---|---|
| Martin Fowler, "Strangler Fig", martinfowler.com/bliki/StranglerFigApplication.html | Revised 2024-08-22 | Pattern and transitional architecture |
| AWS, "AWS Transform for mainframe is now generally available", aws.amazon.com | 2025-05-15 | Service name and status |
| AWS, "AWS Blu Insights is now AWS Transform for mainframe refactor", aws.amazon.com | 2026-03 | Refactor, replatform and reimagine patterns under one service; AWS Mainframe Modernization console where not yet available |
| AWS Mainframe Modernization service page, End of Support Notice, aws.amazon.com/mainframe-modernization | Checked 2026-10-23 | The self-managed experience is closed to new customers; check the current status before planning on it |
| Microsoft Azure Architecture Center, General mainframe refactor to Azure, learn.microsoft.com | ms.date 2025-04-02 | Refactor scenario, single-pass versus gradual migration |
| Microsoft Cloud Adoption Framework, Select your cloud migration strategies, learn.microsoft.com | Checked YYYY-MM-DD | Strategy vocabulary |
| IBM documentation for Enterprise COBOL, CICS Transaction Server, IMS, Db2 for z/OS and z/OS DFSMS | [Versions in use] | Data types, code pages, subsystem behaviour |
| [Internal mainframe standards] | [Version] | [Use] |

## Standard and licence note

Based on the strangler fig pattern described by Martin Fowler (cited, not copied) and on the publicly documented mainframe modernization guidance of Amazon Web Services and Microsoft, whose service and pattern names were checked at their official pages; names change often, so check the current pages before use. COBOL data types, code pages and subsystem terms are described in original words; consult the vendor documentation for the compiler and subsystem versions you run. AWS, Microsoft Azure, IBM, z/OS, CICS, IMS, Db2, RACF and IBM MQ are trademarks of their owners; this template is not affiliated with or endorsed by them. This template is original text written for this collection; examples and figures are illustrative, not benchmarks. Template licence: MIT.