Chapter 01 - Fintech backend engineering
Live in production
A production Go ledger proving money correctness with 600 TPS max clean sustained throughput, explicit row locks, transactional outbox delivery, and Family Finance shadow-write validation.
Why a ledger
Arus isolates the money-correctness core first: balanced entries, idempotent mutations, scoped API keys, immutable postings, and trial-balance verification before higher-level payment flows are added.
Source: ledger/docs/product-requirements/2026-06-11-v01-ledger-v1-prd.mdWhy a ledger
Family Finance shadow-writes transaction create, update, and delete events into Arus without changing user balances, then reports zero drift after the outbox drains.
Source: family-finance/docs/docs/runbooks/2026-06-11-v01-ledger-shadow-write-walkthrough.mdArchitecture
The API writes entries through one posting engine transaction. PostgreSQL holds the journal, materialized balances, idempotency claims, and outbox rows; a relay publishes through Kafka locally or Pub/Sub in Cloud Run.
ADR
Go keeps the locking, idempotency, and SQL choices visible in the diff while matching the Family Finance backend and Cloud Run deployment path.
Source: ledger/docs/adr/2026-06-11-v01-adr-001-go-over-spring.mdADR
Correctness lives in the transactional outbox, so Kafka can prove local broker semantics while Pub/Sub keeps the cloud deployment serverless and inexpensive.
Source: ledger/docs/adr/2026-06-11-v01-adr-002-outbox-pluggable-transport.mdADR
READ COMMITTED plus deterministic account-balance row locks blocks overdraft races without a broad serializable retry loop.
Source: ledger/docs/adr/2026-06-11-v01-adr-003-locking-and-balance-strategy.mdCorrectness evidence
Race storms, property tests, append-only triggers, cross-ledger isolation tests, and relay chaos tests all protect the path where financial systems usually fail.
Concurrent idempotency and overdraft storms are release gates under go test -race; zero balance drift is expected under contention.
Source: ledger/docs/runbooks/2026-06-11-v01-ledger-m1-walkthrough.md
Rapid balanced-entry tests keep the trial balance at net zero across generated posting sequences.
Source: ledger/docs/runbooks/2026-06-11-v01-ledger-m1-walkthrough.md
A simulated relay crash after partial publish rolls back the batch and the next relay run republishes without event loss.
Source: ledger/docs/runbooks/2026-06-11-v01-ledger-m2-walkthrough.md
Entries and postings reject UPDATE and DELETE through database triggers; corrections use reversal entries.
Source: ledger/docs/system-analysis/2026-06-11-v01-ledger-threat-model-sa.md
The effective ledger_id is derived from the API key, foreign-ledger objects return 404, and read-only keys cannot mutate.
Source: ledger/docs/system-analysis/2026-06-11-v01-ledger-threat-model-sa.md
Load evidence
The 600 TPS run is the sustained result. The 800 TPS target was deliberately published as not sustained because k6 dropped iterations even though the trial balance stayed zero.
| Target | Observed req/s | p50 ms | p99 ms | Failed rate | Dropped | Status |
|---|---|---|---|---|---|---|
| 600 | 599.00 | 3.04 | 228.73 | 0.0000 | 0 | Sustained Max clean sustained target; trial balance net 0. |
| 800 | 770.60 | 358.78 | 1038.51 | 0.0000 | 29 | Not sustained Not sustained at target; 29 dropped iterations, trial balance still net 0. |
Production
The live footprint is Cloud Run, Cloud SQL PostgreSQL, Pub/Sub, Secret Manager, and Cloud Scheduler, with relay and daily close as scheduled jobs.
Production runs on Cloud Run API, Cloud SQL PostgreSQL, Pub/Sub, Secret Manager, and Cloud Scheduler.
Source: ledger/docs/runbooks/2026-06-11-v01-ledger-cloud-run-deploy-walkthrough.mdExpected low-traffic monthly cost is approximately $17.50, dominated by the smallest viable Cloud SQL footprint.
Source: ledger/docs/runbooks/2026-06-11-v01-ledger-cloud-run-deploy-walkthrough.mdThe deployment creates scheduled Cloud Run jobs for outbox relay and daily close snapshots.
Source: ledger/docs/runbooks/2026-06-11-v01-ledger-cloud-run-deploy-runbook.mdThe 2026-06-11 PRD, three milestone walkthroughs, hardening, deployment, and shadow-write docs record the PRD-to-production path.
Source: ledger/docs/INDEX.mdIntegration
The first consumer uses shadow writes, reversal-based updates, and a consistency report so the portfolio story is backed by an end-to-end system, not a standalone demo.
The Family Finance demo enqueued create, update, income create, and delete events; the drain processed 4/4 successfully.
Source: family-finance/docs/docs/runbooks/2026-06-11-v01-ledger-shadow-write-walkthrough.mdUpdate posts reverse the prior successful ledger entry before posting the next version; delete performs reversal only.
Source: family-finance/docs/docs/system-analysis/2026-06-11-v01-ledger-shadow-write-sa.mdThe consistency report returned zero_drift with expected cash balance 20000 matching ledger cash balance 20000.
Source: family-finance/docs/docs/runbooks/2026-06-11-v01-ledger-shadow-write-walkthrough.mdRoadmap
Phase 3 reconciliation has shipped as Selaras, Phase 4 payment orchestration has shipped as Alur, and Phase 5 dispute adjudication has shipped as Banding. Family Finance money storage hardening remains a consumer-side track.
Phase 1 hardening
Family Finance still stores money as float64; Arus is int64 minor units, so the durable integration path starts by removing float money from the consumer.
Source: family-finance/docs/docs/runbooks/2026-06-11-v01-ledger-shadow-write-walkthrough.mdPhase 4 shipped
Alur now models authorize-to-capture payment state transitions on top of the verified ledger core with a chaos PSP gate and exactly-once booking.
Read Alur case studySource: family-finance/docs/docs/system-analysis/2026-06-12-v01-alur-case-study-evidence-sa.mdPhase 5 shipped
Banding now adjudicates Alur captures through a durable deadline scheduler, deterministic network events, and exactly-once Arus dispute writebacks.
Read Banding case studySource: family-finance/docs/docs/system-analysis/2026-06-13-v01-banding-case-study-evidence-sa.mdPhase 3 shipped
Selaras now closes the Arus v1 control loop with deterministic matching, five break classes, balanced reports, and a fixture-backed demo.
Read Selaras case studySource: family-finance/docs/docs/system-analysis/2026-06-12-v01-selaras-case-study-evidence-sa.mdEvidence trail