Part 9 · 1 chapters · ~8 min

Capstone: A Ledger Service with Reconciliation

The capstone: build a small ledger service (accounts, balanced postings, holds, idempotent transfers, a payout state machine against a simulated rail with timeouts) and a reconciliation job against a generated bank statement with injected breaks.

The build

code

ledger-capstone/
  schema.sql            accounts, journal_entries, postings, balances, holds, payouts, idempotency_requests, recon_*
  src/post.ts           postEntry(entries, key): balanced check, ordered locks, funds check, append
  src/transfers.ts      POST /transfers with Idempotency-Key, fingerprint, stored responses
  src/payouts.ts        state machine; rail client with random success / failure / timeout (unknown)
  src/enquiry.ts        resolves unknown payouts by polling the fake rail
  src/recon.ts          parses statement.csv, normalises, exact + fuzzy matching, writes breaks
  test/
    double-submit.test.ts      100 concurrent identical requests → one entry
    invariant.test.ts          Σ postings = 0 per currency after 10,000 random operations (property test)
    recon.test.ts              injected breaks (missing, amount diff, late) are all detected
acceptance
  - rebuilding balances from postings equals the balances table
  - no payout is ever completed without a rail success or enquiry confirmation
  - every injected break appears exactly once, with the right type