Skip to content
Documentation

Legacy Diagram Patterns (Mermaid)

FieldValue
TypeSkill Resource
Source~/.copilot/skills/architecture/references/discovery/mermaid-legacy-patterns.md
DescriptionNot specified

Source Content

Legacy Diagram Patterns (Mermaid)

The canonical diagram set for a legacy discovery. Each pattern below is a ready-to-fill skeleton — valid per the technical-writing skill’s diagram rules, sized to the 5–7 node budget, grouped with subgraphs, and captioned with a “what to notice” line. Copy the skeleton, swap in the real entities, and keep the caption. Always invoke the technical-writing skill (which owns the diagram rules) before emitting any block; these skeletons pass its checklist but your filled-in version must too.

Use these in the onboarding doc exactly where onboard-template.md calls for them. One rule binds all of them: every diagram gets a one-line “what to notice” caption that names the boundary or takeaway it teaches.

Contents

Logical ERD

When to use it: section 5 of the onboard doc, to show the reverse-engineered data model — the entities, their keys, and how they relate. This is the picture of what the system is about, decoded from DDS, DB2 for i, VSAM copybooks, or flat-file layouts.

erDiagram
  CLAIM ||--o{ PAYMENT : "pays out"
  CLAIM }o--|| CLAIMANT : "filed by"
  CLAIM }o--|| EMPLOYER : "charged to"
  CLAIMANT ||--o{ WAGE_RECORD : "earns"
  CLAIM {
    string claim_id PK
    string claimant_id FK
    string employer_id FK
    string status_code "A/D/P — decode in field dict"
    decimal weekly_benefit "packed, scaled /100"
    int    filed_date "YYYYMMDD integer"
  }
  CLAIMANT {
    string claimant_id PK
    string ssn "zoned decimal"
  }

What to notice: crow’s-foot marks tell the reader the cardinality at a glance — one claimant, many wage records — and the field notes carry the decode (packed, scaled, date-as-integer) so nobody reads the raw storage as its business value.

Program call graph

When to use it: section 3 or section 6, to show what calls what, grouped by subsystem. Group by subsystem (or by what people do vs. batch when both are present) so the reader sees structure before labels — never a flat call chain.

flowchart TD
  subgraph online["Online subsystem (5250/CICS)"]
    INQ["fas:fa-desktop Claim inquiry"] --> LOOKUP["fas:fa-magnifying-glass Read claim"]
  end
  subgraph batch["Batch subsystem"]
    CALC["fas:fa-calculator Benefit calc"] --> POST["fas:fa-money-bill Post payment"]
  end
  LOOKUP -->|shares| MASTER["fas:fa-database Claim master"]
  CALC -->|reads| MASTER
  classDef online fill:#eef2f7,stroke:#4a5b70,color:#22303f
  classDef batch fill:#f6f0e6,stroke:#8a6a2f,color:#3d2f10
  class INQ,LOOKUP online
  class CALC,POST batch

What to notice: the shared claim master sits between the two subgraphs — that shared file is the coupling point a rebuild has to plan around, and the grouping makes the online/batch split visible before any label is read.

Batch-job DAG

When to use it: section 9, to draw the nightly cycle as a directed acyclic graph — which jobs run, in what order, grouped by schedule window. Use LR here because the left-to-right direction is the time order of the cycle.

flowchart LR
  subgraph evening["Evening window"]
    EXTRACT["fas:fa-file-export Extract wages"]
  end
  subgraph overnight["Overnight window"]
    CALC["fas:fa-calculator Benefit calc"] --> EDIT["fas:fa-list-check Edit & validate"]
    EDIT --> POST["fas:fa-money-bill Post payments"]
  end
  subgraph morning["Morning window"]
    REPORT["fas:fa-file-lines Federal report"]
  end
  EXTRACT -->|feeds| CALC
  POST -->|feeds| REPORT
  classDef evening fill:#eef2f7,stroke:#4a5b70,color:#22303f
  classDef overnight fill:#f6f0e6,stroke:#8a6a2f,color:#3d2f10
  classDef morning fill:#e8f1fb,stroke:#2f6096,color:#122c42
  class EXTRACT evening
  class CALC,EDIT,POST overnight
  class REPORT morning

What to notice: the arrows crossing window boundaries are the hard dependencies — if the evening extract slips, the overnight calc cannot start, and the morning federal report is late; that chain is where the 2 a.m. failures live.

Entity state lifecycle

When to use it: section 6 or section 8, to show the status transitions of a core entity — a claim, a case, an application. The status codes in the data model (a status_code of A/D/P) become named states, and the business rules become the transitions between them.

stateDiagram-v2
  [*] --> Filed: claim submitted
  Filed --> UnderReview: passes intake edits
  UnderReview --> Approved: eligibility met
  UnderReview --> Denied: eligibility fails
  Approved --> Paid: payment posted
  Denied --> [*]
  Paid --> [*]

What to notice: every arrow is a business rule — “eligibility met” and “passes intake edits” are the exact conditions the code enforces, so this diagram doubles as the index into the rule catalog.

Green-screen user journey

When to use it: section 7, to show what a person at a 5250 or CICS screen experiences — panel by panel, function key by function key. A CICS transaction is pseudo-conversational, which means it is a state machine (see cics-online.md); model it as one, or a linear flowchart will lie about how it behaves.

stateDiagram-v2
  [*] --> Menu: user types TRANSID
  Menu --> SearchPanel: PF-key select
  SearchPanel --> ResultList: Enter (claim found)
  SearchPanel --> SearchPanel: Enter (not found — error)
  ResultList --> DetailPanel: select a row
  DetailPanel --> Menu: PF3 (back)
  DetailPanel --> [*]: PF3 from menu (exit)

What to notice: the self-loop on the search panel is the “not found” error path staying on the same screen, and every transition is a key press — this is the keyboard contract the EIBAID dispatcher (CICS) or the display file’s function keys (5250) actually enforce.

Integration / system-context

When to use it: section 10, to draw the legacy system at the center with its external feeds, vendors, downstream consumers, and reports around it. This is a multi-layer diagram, so it is the exception to the single-shape rule: every layer gets its own shape and its own muted color from the technical-writing skill’s system-node palette, so a reader tells an inbound feed from a vendor from a report before reading a label.

flowchart TD
  subgraph inbound["Inbound feeds"]
    WAGE[("fas:fa-file-import Employer wage file")]
    IRS[("fas:fa-file-import IRS 1099 feed (monthly)")]
  end
  CORE{{"fas:fa-server Legacy claims system"}}
  subgraph outbound["Outbound consumers"]
    FED["fas:fa-building-columns Federal report"]
    BANK(("fas:fa-money-check Payment vendor"))
  end
  WAGE -->|nightly file drop| CORE
  IRS -.-> CORE
  CORE -->|nightly| FED
  CORE ==>|daily ACH| BANK
  classDef feed fill:#eef2f7,stroke:#4a5b70,color:#22303f
  classDef core fill:#eaf4ee,stroke:#2f7a52,color:#173926
  classDef report fill:#e8f1fb,stroke:#2f6096,color:#122c42
  classDef vendor fill:#f4f0fa,stroke:#6d4fa3,color:#2b2440
  class WAGE,IRS feed
  class CORE core
  class FED report
  class BANK vendor

What to notice: each layer has its own shape and colour — cylinders for inbound stores, a hexagon for the core, a rectangle for the report, a circle for the external vendor — so the seams (dashed monthly feed, thick daily ACH) read as different kinds of coupling at a glance; those seams are where migration risk concentrates.

File-usage / CRUD matrix

When to use it: section 6 or the dependency map, to show which programs touch which files and how — Create, Read, Update, Delete. This one is not a Mermaid diagram. A program-by-file grid is a matrix, and a Markdown table renders it far more clearly than any graph could; a diagram with an edge per CRUD verb would be an unreadable hairball past a handful of programs.

Build it as a table: one row per program, one column per file, and the CRUD letters in each cell. Fill any cell where a program does not touch a file with - (never blank).

ProgramClaim masterPayment fileWage recordEmployer file
Claim inquiryR-RR
Benefit calcR-R-
Post paymentUC--
Nightly purgeDR--

What to notice: the columns reveal ownership — the file only one program writes is that program’s private store, while a file several programs update (the claim master here) is a shared-write hotspot a rebuild must decouple first.

Read each cell as: C creates records, R reads, U updates, D deletes. A program with only R across the row is a pure reader (a report or an inquiry); a program with C/U/D is a writer whose behavior a golden-master test must pin before anything changes.