{"id":48139195,"url":"https://github.com/albertdobmeyer/cobol-legacy-ledger","last_synced_at":"2026-04-04T16:50:13.750Z","repository":{"id":340855597,"uuid":"1160543497","full_name":"albertdobmeyer/cobol-legacy-ledger","owner":"albertdobmeyer","description":"Learn COBOL through a live banking system — 18 programs, 6-node settlement network, real-time simulation, Python read/write bridge, SHA-256 tamper detection, AI tutor (Ollama + Claude), static analysis with orthogonal call graphs, and a glass morphism web console. 800 tests.","archived":false,"fork":false,"pushed_at":"2026-04-03T04:33:35.000Z","size":11533,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T11:26:38.590Z","etag":null,"topics":["anthropic","banking","banking-simulation","call-graph","cobol","cobol-tutorial","education","fastapi","glass-morphism","hash-chain","legacy-modernization","llm","ollama","python","settlement","sha256","static-analysis","teaching-resource","tool-use"],"latest_commit_sha":null,"homepage":"https://cobol-legacy-ledger-production.up.railway.app/console/","language":"COBOL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/albertdobmeyer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-18T04:21:14.000Z","updated_at":"2026-04-03T04:33:39.000Z","dependencies_parsed_at":"2026-02-27T02:00:55.143Z","dependency_job_id":null,"html_url":"https://github.com/albertdobmeyer/cobol-legacy-ledger","commit_stats":null,"previous_names":["gitgoodordietrying/cobol-legacy-ledger","albertdobmeyer/cobol-legacy-ledger"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/albertdobmeyer/cobol-legacy-ledger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertdobmeyer%2Fcobol-legacy-ledger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertdobmeyer%2Fcobol-legacy-ledger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertdobmeyer%2Fcobol-legacy-ledger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertdobmeyer%2Fcobol-legacy-ledger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/albertdobmeyer","download_url":"https://codeload.github.com/albertdobmeyer/cobol-legacy-ledger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertdobmeyer%2Fcobol-legacy-ledger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31406282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","banking","banking-simulation","call-graph","cobol","cobol-tutorial","education","fastapi","glass-morphism","hash-chain","legacy-modernization","llm","ollama","python","settlement","sha256","static-analysis","teaching-resource","tool-use"],"created_at":"2026-04-04T16:50:10.761Z","updated_at":"2026-04-04T16:50:13.724Z","avatar_url":"https://github.com/albertdobmeyer.png","language":"COBOL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# COBOL Legacy Ledger\r\n\r\n[![Live Demo](https://img.shields.io/badge/%F0%9F%9A%80_Live_Demo-Try_It_Now-blue?style=for-the-badge)](https://cobol-legacy-ledger-production.up.railway.app/console/)\r\n\r\n[![CI](https://github.com/albertdobmeyer/cobol-legacy-ledger/actions/workflows/ci.yml/badge.svg)](https://github.com/albertdobmeyer/cobol-legacy-ledger/actions/workflows/ci.yml)\r\n![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)\r\n![License: MIT](https://img.shields.io/badge/license-MIT-green)\r\n![Tests: 820](https://img.shields.io/badge/tests-820%20passing-brightgreen)\r\n![COBOL Programs: 18](https://img.shields.io/badge/COBOL-18%20programs-purple)\r\n![Nodes: 6](https://img.shields.io/badge/nodes-6%20banks-orange)\r\n\r\n**Learn COBOL through a live banking system** — run simulations, corrupt ledgers, catch fraud with SHA-256 hash chains, and explore spaghetti code with AI-powered static analysis.\r\n\r\n\u003e \"COBOL isn't the problem. Lack of observability is.\"\r\n\r\nThis is a fully functional **6-node inter-bank settlement system** in COBOL, wrapped with a Python read/write bridge that adds cryptographic integrity without modifying a single line of legacy code. An AI tutor (Ollama local or Claude cloud) can explain any paragraph, trace execution paths, and compare spaghetti vs clean code side by side. Every source file teaches COBOL syntax, banking concepts, and integration patterns inline.\r\n\r\n## At a Glance\r\n\r\n**Stack**: COBOL (GnuCOBOL) · Python 3.9+ · FastAPI · SQLite · Vanilla JS · Docker\r\n\r\n- **18 COBOL programs** (10 clean + 8 intentional spaghetti) with a Python observation layer — no legacy code modified\r\n- **SHA-256 hash chain** integrity across 6 independent banking nodes, with live tamper detection in \u003c100ms\r\n- **807 automated tests** (unit, integration, E2E browser), CI with linting, multi-version Python matrix\r\n- **AI-powered static analysis** — call graphs, dead code detection, complexity scoring, cross-file dependency mapping\r\n\r\n**See it in action**: Run `python -m python.cli prove` to compile, seed, settle, verify, tamper, and detect — or try the [live demo](https://cobol-legacy-ledger-production.up.railway.app/console/).\r\n\r\n## How to Use This Repository\r\n\r\n### For Students (Self-Study)\r\n\r\nStart with the **[Learning Path](docs/LEARNING_PATH.md)** — a guided reading order from beginner to advanced, with exercises at each stage.\r\n\r\n### For Instructors\r\n\r\nSee the **[Teaching Guide](docs/TEACHING_GUIDE.md)** — 10 structured lessons covering COBOL fundamentals through modern integration, with objectives and exercises for each lesson. Three graded lab assignments with rubrics are in **[Assessments](docs/ASSESSMENTS.md)**.\r\n\r\n### For Reference\r\n\r\nThe **[Glossary](docs/GLOSSARY.md)** defines every COBOL keyword, banking term, and project-specific concept used in the codebase.\r\n\r\n## Quick Start\r\n\r\n### Option A: Docker (any OS — real COBOL included)\r\n\r\n```\r\ndocker compose up\r\n```\r\n\r\nOpen **http://localhost:8000/console/** — hit **Start** to run a simulation, or try **Corrupt Ledger** then **Integrity Check** to see SHA-256 tamper detection.\r\n\r\n### Option B: Native Python (any OS)\r\n\r\n```\r\ngit clone https://github.com/albertdobmeyer/cobol-legacy-ledger.git\r\ncd cobol-legacy-ledger\r\npip install -e \".[dev]\"\r\npython -m python.cli setup\r\npython -m uvicorn python.api.app:create_app --factory --host 127.0.0.1 --port 8000\r\n```\r\n\r\nOpen **http://localhost:8000/console/**\r\n\r\n\u003e **Windows PowerShell note**: Use single quotes for the install command: `pip install -e '.[dev]'`\r\n\r\n### Run the Full Demo\r\n\r\n```\r\npython -m python.cli prove\r\n```\r\n\r\nThis runs the full system lifecycle — compile, seed, settle, verify, tamper, detect:\r\n\r\n1. **Compiles** 18 COBOL programs (10 banking + 8 payment processor sidecar)\r\n2. **Seeds** 6 independent banking nodes (42 accounts, $100M+ in balances)\r\n3. **Settles** an inter-bank transfer: Alice@BANK_A pays Bob@BANK_B $2,500 through the clearing house\r\n4. **Verifies** all SHA-256 hash chains intact across the network\r\n5. **Tampers** one bank's ledger directly (bypassing COBOL and the integrity chain)\r\n6. **Detects** the tamper in \u003c100ms via balance reconciliation\r\n\r\n### Optional: Install GnuCOBOL for Real COBOL Execution\r\n\r\n```bash\r\n# Ubuntu/Debian\r\nsudo apt install gnucobol\r\n\r\n# macOS\r\nbrew install gnucobol\r\n\r\n# Windows (MSYS2)\r\npacman -S mingw-w64-x86_64-gnucobol\r\n```\r\n\r\nWithout GnuCOBOL, the system uses Python-only mode (Mode B). With it, every operation runs through real compiled COBOL programs (Mode A). Docker includes GnuCOBOL automatically.\r\n\r\n### Developer Tools (Linux/macOS)\r\n\r\n```bash\r\nmake lab-setup   # venv + deps + seed + smoke test\r\nmake run         # start server\r\nmake prove       # full end-to-end proof (bash version)\r\n```\r\n\r\nThe `scripts/` directory also contains bash scripts (`prove.sh`, `build.sh`, `seed.sh`) for Unix environments.\r\n\r\nThe **web console** at `http://localhost:8000/console/` provides:\r\n- **Dashboard** — Hub-and-spoke network with health rings, split transaction log (outgoing/incoming), live COBOL ticker viewport with syntax highlighting, simulation controls\r\n- **Analysis** — Orthogonal call graph with toggleable edge types, execution trace, dead code detection, complexity scoring, cross-file dependency analysis, spaghetti-vs-clean comparison\r\n- **Chat** — LLM chatbot with tool-use cards, tutor mode, prompt chips, provider switching (Ollama/Anthropic), session management\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"docs/screenshots/dashboard.png\" alt=\"Dashboard with hub-and-spoke network, split transaction log, live COBOL ticker, and simulation controls\" width=\"800\"\u003e\r\n\u003c/p\u003e\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"docs/screenshots/analysis.png\" alt=\"Analysis tab with orthogonal call graph routing, toggleable edge legend, complexity scoring, and execution trace\" width=\"800\"\u003e\r\n\u003c/p\u003e\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"docs/screenshots/chat.png\" alt=\"LLM chatbot with tool-use cards, prompt chips, and provider switching\" width=\"800\"\u003e\r\n\u003c/p\u003e\r\n\r\n## Features at a Glance\r\n\r\n- **18 production COBOL programs** — 10 clean banking + 8 intentional spaghetti spanning 1974-2012\r\n- **800 automated tests** — unit, integration, E2E browser (Playwright)\r\n- **Real-time 6-node banking simulation** via Server-Sent Events\r\n- **SHA-256 tamper detection** in \u003c100ms across all nodes\r\n- **AI-powered COBOL tutor** (Ollama local / Claude cloud) with 19 RBAC-gated analysis tools\r\n- **Spaghetti archaeology** — GO TO networks, ALTER state machines, 6-level nested IF, Y2K dead code\r\n- **Cross-file dependency analysis** with shared copybook detection\r\n- **\"Analyzed in 47ms. Human estimate: 3-5 days.\"** — human vs AI comparison timer\r\n- **10 lessons, 3 graded labs**, classroom checkpoint save/restore\r\n- **One-click setup**: `docker compose up` / `python -m python.cli setup` / GitHub Codespaces\r\n\r\n## What You'll Learn\r\n\r\n### COBOL Fundamentals (Lessons 1-4)\r\n\r\n| Concept | Where to Find It | File |\r\n|---------|-------------------|------|\r\n| Four divisions (IDENTIFICATION, ENVIRONMENT, DATA, PROCEDURE) | Every `.cob` file | Start with `SMOKETEST.cob` |\r\n| PIC clauses (`X`, `9`, `S9`, `V99`) | Copybook annotations | `ACCTREC.cpy`, `TRANSREC.cpy` |\r\n| 88-level condition names | Account status flags | `ACCTREC.cpy`, `COMCODE.cpy` |\r\n| FILE-CONTROL / SELECT ASSIGN | File-to-program binding | `ACCOUNTS.cob` |\r\n| COPY statement (copybooks) | Shared record definitions | Every `.cob` file |\r\n| PERFORM / PERFORM VARYING | Loops and subroutines | `ACCOUNTS.cob`, `TRANSACT.cob` |\r\n| EVALUATE TRUE | Switch/case equivalent | `TRANSACT.cob`, `REPORTS.cob` |\r\n| STRING / UNSTRING | String manipulation | `ACCOUNTS.cob`, `TRANSACT.cob` |\r\n\r\n### Banking Operations (Lessons 5-7)\r\n\r\n| Concept | Where to Find It | File |\r\n|---------|-------------------|------|\r\n| Account lifecycle (CRUD) | Account master file operations | `ACCOUNTS.cob` |\r\n| Transaction processing | Deposits, withdrawals, transfers | `TRANSACT.cob` |\r\n| Batch processing | Pipe-delimited input files | `TRANSACT.cob` (BATCH mode) |\r\n| Interest accrual | COMPUTE with ROUNDED | `INTEREST.cob` |\r\n| Fee processing | Balance floor protection | `FEES.cob` |\r\n| Reconciliation | Cross-file balance verification | `RECONCILE.cob` |\r\n| Inter-bank settlement | 3-leg clearing house settlement | `SETTLE.cob` |\r\n\r\n### Modern Integration (Lesson 8)\r\n\r\n| Concept | Where to Find It | File |\r\n|---------|-------------------|------|\r\n| COBOL subprocess wrapping | Mode A: calling COBOL from Python | `python/bridge.py` |\r\n| Fixed-width file I/O | Mode B: Python reads/writes DAT files | `python/bridge.py` |\r\n| SHA-256 hash chains | Cryptographic tamper detection | `python/integrity.py` |\r\n| Cross-node verification | Multi-node settlement matching | `python/cross_verify.py` |\r\n| REST API (FastAPI) | HTTP endpoints wrapping all operations | `python/api/` |\r\n| LLM tool-use | AI chatbot with RBAC-gated banking tools | `python/llm/` |\r\n\r\n### Legacy Code Archaeology (Lesson 9)\r\n\r\n| Concept | Where to Find It | File |\r\n|---------|-------------------|------|\r\n| GO TO networks | Paragraph spaghetti, non-sequential flow | `PAYROLL.cob`, `MERCHANT.cob` |\r\n| ALTER statement | Runtime GO TO modification, state machines | `PAYROLL.cob`, `DISPUTE.cob` |\r\n| PERFORM THRU | Paragraph range execution | `TAXCALC.cob` |\r\n| Nested IF (no END-IF) | Period-terminated 6-level nesting | `TAXCALC.cob` |\r\n| GO TO DEPENDING ON | Computed branching | `MERCHANT.cob` |\r\n| SORT INPUT/OUTPUT PROCEDURE | Callback-style file processing | `FEEENGN.cob` |\r\n| INSPECT TALLYING | String scanning for risk scoring | `RISKCHK.cob` |\r\n| Dead code | Unreachable paragraphs left for decades | All payroll/payment programs |\r\n| Misleading comments | Code/comment divergence over time | `TAXCALC.cob`, `DEDUCTN.cob` |\r\n\r\n### Static Analysis Tools (Lesson 10)\r\n\r\n| Concept | Where to Find It | File |\r\n|---------|-------------------|------|\r\n| Call graph analysis | Paragraph dependency mapping | `python/cobol_analyzer/call_graph.py` |\r\n| Execution tracing | GO TO/ALTER chain resolution | `python/cobol_analyzer/call_graph.py` |\r\n| Dead code detection | Reachability analysis | `python/cobol_analyzer/dead_code.py` |\r\n| Complexity scoring | Per-paragraph anti-pattern weighting | `python/cobol_analyzer/complexity.py` |\r\n| Pattern knowledge base | COBOL idiom encyclopedia | `python/cobol_analyzer/knowledge_base.py` |\r\n| Cross-file analysis | Multi-program CALL/COPY dependency graphs | `python/cobol_analyzer/cross_file.py` |\r\n\r\n## Architecture\r\n\r\n```\r\n                    ┌─────────────────────┐\r\n                    │  Layer 4: Console   │\r\n                    │  Glass Morphism UI  │\r\n                    │  Dashboard + Chat   │\r\n                    └─────────┬───────────┘\r\n                              │\r\n                    ┌─────────┴───────────┐\r\n                    │   Layer 3: LLM/API  │\r\n                    │  FastAPI + Tool-Use │\r\n                    │  Ollama / Anthropic  │\r\n                    └─────────┬───────────┘\r\n                              │\r\n                    ┌─────────┴───────────┐\r\n                    │  Layer 2: Python     │\r\n                    │  Bridge + Integrity  │\r\n                    │  Settlement + RBAC   │\r\n                    └─────────┬───────────┘\r\n                              │\r\n                    ┌─────────┴───────────┐\r\n                    │  Layer 5: Analysis  │\r\n                    │  Call Graph + Trace │\r\n                    │  Dead Code + Score  │\r\n                    │  Cross-File Deps    │\r\n                    └─────────┬───────────┘\r\n                              │\r\nBANK_A ─────┐                 │                ┌───── BANK_D\r\nBANK_B ─────┤◄── Settlement ──┤──────────────►├───── BANK_E\r\nBANK_C ─────┘    Coordinator  │                └───── CLEARING\r\n                              │\r\n                    ┌─────────┴───────────┐\r\n                    │  Layer 1: COBOL     │\r\n                    │  18 programs, DAT   │\r\n                    │  SHA-256 chain/node  │\r\n                    └─────────────────────┘\r\n```\r\n\r\n**6 nodes** (5 banks + 1 clearing house), each with:\r\n- `ACCOUNTS.DAT` — COBOL fixed-width account records (70 bytes each)\r\n- `TRANSACT.DAT` — COBOL transaction log (103 bytes each)\r\n- `{node}.db` — SQLite with integrity chain, transaction history, account snapshots\r\n\r\n**Inter-bank settlement** flows through 3 steps:\r\n1. Source bank debits sender's account\r\n2. Clearing house records both sides (deposit from source, withdraw to dest)\r\n3. Destination bank credits receiver's account\r\n\r\nEvery step is recorded in the node's SHA-256 hash chain. Cross-node verification matches settlement references across all 6 chains.\r\n\r\nSee [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full topology, data flow, and integrity model.\r\n\r\n## Payment Processor Spaghetti\r\n\r\nThe payroll/payment sidecar contains **8 intentionally spaghetti COBOL programs** — real anti-patterns from 4 decades of mainframe development, written by 8 fictional developers across 5 eras:\r\n\r\n| Program | Era | Developer | Anti-Patterns |\r\n|---------|-----|-----------|---------------|\r\n| `PAYROLL.cob` | 1974 | JRK | GO TO network, ALTER, magic numbers, dead P-085 |\r\n| `TAXCALC.cob` | 1983 | TKN | 6-level nested IF, PERFORM THRU, misleading comments |\r\n| `DEDUCTN.cob` | 1991 | PMR | Structured/spaghetti hybrid, mixed COMP types, dead code |\r\n| `PAYBATCH.cob` | 2002 | RBJ+SLW+ACS+Y2K | Y2K dead code, excessive DISPLAY tracing, half-finished refactor |\r\n| `MERCHANT.cob` | 1978 | KMW | GO TO DEPENDING ON, shared working storage, COPY REPLACING |\r\n| `FEEENGN.cob` | 1986 | KMW | SORT INPUT/OUTPUT PROCEDURE, 3-deep PERFORM VARYING, \"temporary\" blended pricing |\r\n| `DISPUTE.cob` | 1994 | OFS | ALTER state machine, dead Report Writer, STRING/UNSTRING parsing |\r\n| `RISKCHK.cob` | 2008 | OFS | Contradicting velocity checks, duplicate scoring, INSPECT TALLYING |\r\n\r\nEvery issue is documented in the **[Anti-Pattern Catalog](COBOL-BANKING/payroll/KNOWN_ISSUES.md)** with issue codes (PY/TX/DD/PB/PC/ER/MR/FE/DP/RK). The full fictional developer history is in the **[Payroll README](COBOL-BANKING/payroll/README.md)**.\r\n\r\nThese programs are **educational showcases for anti-pattern analysis**, not operational simulation components. The banking simulation runs pure 6-node transactions; the payment processor exists to teach legacy code archaeology using the analysis tools.\r\n\r\n## Repository Structure\r\n\r\n```\r\nCOBOL-BANKING/           Standalone COBOL banking system\r\n  src/                   10 COBOL banking programs — thoroughly commented for teaching\r\n    SMOKETEST.cob        START HERE — minimal program, teaches all 4 divisions\r\n    ACCOUNTS.cob         Account lifecycle: CREATE, READ, UPDATE, CLOSE, LIST\r\n    TRANSACT.cob         Transaction engine: DEPOSIT, WITHDRAW, TRANSFER, BATCH\r\n    VALIDATE.cob         Business rules: status checks, balance limits\r\n    REPORTS.cob          Reporting: STATEMENT, LEDGER, EOD, AUDIT\r\n    INTEREST.cob         Monthly interest accrual (COMPUTE, ROUNDED)\r\n    FEES.cob             Monthly maintenance fee processing\r\n    RECONCILE.cob        Transaction-to-balance reconciliation\r\n    SIMULATE.cob         Deterministic daily transaction generator\r\n    SETTLE.cob           3-leg inter-bank clearing house settlement\r\n  payroll/               Legacy payment processor sidecar (intentional spaghetti)\r\n    src/                 8 COBOL programs with documented anti-patterns\r\n      PAYROLL.cob        Main controller (1974, GO TO + ALTER spaghetti)\r\n      TAXCALC.cob        Tax calculator (1983, 6-level nested IF)\r\n      DEDUCTN.cob        Deductions processor (1991, mixed COMP types)\r\n      PAYBATCH.cob       Batch formatter (2002, Y2K dead code)\r\n      MERCHANT.cob       Merchant onboarding (1978, GO TO DEPENDING ON)\r\n      FEEENGN.cob        Fee calculation engine (1986, SORT INPUT/OUTPUT)\r\n      DISPUTE.cob        Chargeback lifecycle (1994, ALTER state machine)\r\n      RISKCHK.cob        Risk scoring (2008, INSPECT TALLYING)\r\n    copybooks/           7 payroll/payment-specific copybooks\r\n      EMPREC.cpy         Employee record layout (95 bytes)\r\n      TAXREC.cpy         Tax bracket table with COMP-3 work fields\r\n      PAYREC.cpy         Pay stub output record\r\n      PAYCOM.cpy         Common constants (intentional conflicts)\r\n      MERCHREC.cpy       Merchant record layout (120 bytes, REDEFINES)\r\n      FEEREC.cpy         Fee interchange table (OCCURS 4)\r\n      DISPREC.cpy        Dispute record layout (150 bytes)\r\n    KNOWN_ISSUES.md      Anti-pattern catalog — the \"answer key\" for Lesson 9\r\n    README.md            Fictional developer history (JRK, TKN, PMR, RBJ, SLW, ACS, Y2K, KMW+OFS)\r\n  copybooks/             Shared record definitions — annotated with byte offsets\r\n    ACCTREC.cpy          Account record (70 bytes) — PIC clause tutorial\r\n    TRANSREC.cpy         Transaction record (103 bytes)\r\n    COMCODE.cpy          Status codes, bank IDs, constants\r\n    ACCTIO.cpy           Shared account I/O table (OCCURS clause tutorial)\r\n    SIMREC.cpy           Simulation parameters (REDEFINES tutorial)\r\n  data/                  6 independent node directories (gitignored)\r\n\r\npython/                  Python observation layer — commented for integration concepts\r\n  bridge.py              COBOL subprocess execution + DAT file I/O + SQLite sync\r\n  integrity.py           SHA-256 hash chain + HMAC verification\r\n  settlement.py          3-step inter-bank settlement coordinator\r\n  cross_verify.py        Cross-node integrity verification + tamper detection\r\n  simulator.py           Multi-day banking simulation engine\r\n  cli.py                 Command-line interface (build, setup, prove, seed, transact, verify, simulate)\r\n  auth.py                RBAC (4 roles, 18 permissions)\r\n  payroll_bridge.py      Payroll COBOL bridge (Mode A/B) + settlement integration\r\n  api/                   FastAPI REST layer\r\n    app.py               Application factory + static mounts + exception handlers\r\n    routes_banking.py    Account, transaction, chain, settlement endpoints\r\n    routes_simulation.py Simulation control + SSE streaming + tamper demo\r\n    routes_codegen.py    COBOL parse/generate/edit/validate endpoints\r\n    routes_chat.py       LLM chat with tool-use resolution\r\n    routes_health.py     System health check\r\n    routes_payroll.py    Payroll employee/run/stubs endpoints\r\n    routes_analysis.py   COBOL analysis (call graph, trace, dead code, complexity)\r\n  llm/                   LLM tool-use layer\r\n    tools.py             19 tool definitions (8 banking + 4 codegen + 7 analysis)\r\n    tool_executor.py     RBAC-gated dispatch to bridge/codegen/analyzer\r\n    providers.py         Ollama (local) + Anthropic (cloud) providers\r\n    conversation.py      Session management + tool-use loop\r\n    audit.py             SQLite audit log for all tool invocations\r\n  cobol_analyzer/        Static analysis for legacy spaghetti COBOL (6 modules)\r\n    call_graph.py        Paragraph dependency graph + trace_execution()\r\n    data_flow.py         Field read/write tracking per paragraph\r\n    dead_code.py         Unreachable paragraph detection\r\n    complexity.py        Per-paragraph complexity scoring\r\n    knowledge_base.py    COBOL pattern encyclopedia (~20 entries)\r\n    cross_file.py        Multi-file CALL/COPY dependency analysis\r\n  tests/                 820 tests (733 unit + 74 E2E) — all green\r\n\r\nconsole/                 Web dashboard + chatbot UI (static HTML/CSS/JS)\r\n  index.html             SPA shell — nav tabs, role selector, health dot\r\n  css/                   Glass morphism design system (6 files)\r\n  js/                    Modular vanilla JS (11 files)\r\n\r\ndocs/\r\n  ARCHITECTURE.md        Full system topology, data flow, integrity model\r\n  GLOSSARY.md            COBOL, banking, and project terminology\r\n  TEACHING_GUIDE.md      Instructor's manual — 10 structured lessons\r\n  LEARNING_PATH.md       Student self-study guide with exercises\r\n  ASSESSMENTS.md         3 graded lab assignments with rubrics\r\n  archive/               Original specification and handoff documents\r\n\r\nscripts/\r\n  prove.sh               Executable proof (bash version — see also: python -m python.cli prove)\r\n  build.sh               Compile COBOL programs\r\n  seed.sh                Seed all 6 nodes with demo data\r\n  checkpoint.sh          Save/restore data snapshots for classroom lessons\r\n\r\nMakefile                 Single entry point: make build/seed/test/run/prove/lab-setup\r\nDockerfile               Multi-stage build: GnuCOBOL + Python + FastAPI\r\ndocker-compose.yml       Single `docker compose up` for demo\r\n```\r\n\r\n## Key Design Decisions\r\n\r\n**Dual-mode execution** — Every operation works two ways: Mode A calls compiled COBOL binaries as subprocesses (production path), Mode B uses Python file I/O as fallback (when `cobc` isn't available). Same business logic, same data formats.\r\n\r\n**COBOL immutability** — The COBOL programs are never modified. Python wraps them non-invasively, reading their output and maintaining integrity chains alongside the legacy data.\r\n\r\n**Per-node isolation** — Each node has its own SQLite database and hash chain. No shared ledger. This mirrors how real banking systems operate — distributed, independent, reconciled through settlement.\r\n\r\n**Tamper detection** — Two layers: (1) SHA-256 hash chains detect if chain entries are modified or deleted, (2) balance reconciliation compares DAT file balances against SQLite snapshots to detect direct file tampering.\r\n\r\n**Payment processor is analysis-only** — The 8 payment processor programs are educational showcases for anti-pattern analysis, not operational simulation components. The simulation runs pure 6-node banking transactions. This is intentional: the spaghetti code exists to teach legacy code archaeology.\r\n\r\n## Prerequisites\r\n\r\n- **Python 3.9+** (required) — [python.org/downloads](https://www.python.org/downloads/)\r\n- **GnuCOBOL 3.x** (optional — falls back to Python-only mode)\r\n- **Docker** (optional — alternative to local install)\r\n\r\n### Installing GnuCOBOL (optional)\r\n\r\n```bash\r\n# Ubuntu/Debian\r\nsudo apt install gnucobol\r\n\r\n# macOS\r\nbrew install gnucobol\r\n\r\n# Windows — use the included installer script:\r\npowershell -File scripts/install_gnucobol.ps1\r\n# Or via MSYS2:\r\npacman -S mingw-w64-x86_64-gnucobol\r\n```\r\n\r\nThe system works fully without GnuCOBOL. All 820 tests pass in Python-only mode (Mode B).\r\n\r\n## Status Codes\r\n\r\nCOBOL programs return standard status codes in all responses:\r\n\r\n| Code | Meaning | COBOL Constant |\r\n|------|---------|----------------|\r\n| `00` | Success | `RC-SUCCESS` |\r\n| `01` | Insufficient funds | `RC-NSF` |\r\n| `02` | Limit exceeded | `RC-LIMIT-EXCEEDED` |\r\n| `03` | Invalid account/operation | `RC-INVALID-ACCT` |\r\n| `04` | Account frozen | `RC-ACCOUNT-FROZEN` |\r\n| `99` | System error | `RC-FILE-ERROR` |\r\n\r\nThese are defined in `COBOL-BANKING/copybooks/COMCODE.cpy` and shared across all programs.\r\n\r\n## Running Tests\r\n\r\n```bash\r\n# Unit tests (733 tests) — works on all platforms\r\npython -m pytest python/tests/ -v --ignore=python/tests/test_e2e_playwright.py\r\n\r\n# E2E tests (74 tests, requires running server + Playwright)\r\npython -m pytest python/tests/test_e2e_playwright.py -v\r\n\r\n# All 820 tests\r\npython -m pytest python/tests/ -v\r\n```\r\n\r\nOn Linux/macOS with `make`: `make test` and `make test-e2e`.\r\n\r\n## License\r\n\r\nMIT\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertdobmeyer%2Fcobol-legacy-ledger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falbertdobmeyer%2Fcobol-legacy-ledger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertdobmeyer%2Fcobol-legacy-ledger/lists"}