Ledger

Problem

Most products that move money start with a balance column and an UPDATE. Then two concurrent requests spend the same balance, a retried request runs a transfer twice, a crash after the commit means a webhook is never sent, and nobody can explain why a balance is what it is.

Approach

Designing before writing code: a PRD listing the invariants Ledger must never break, a design doc, eight architecture decision records, a STRIDE threat model, and C4, ERD, sequence and state diagrams. The rules: money as integers in minor units, immutable entries with refunds as reversing transactions, every transaction summing to zero as enforced by the database, SERIALIZABLE isolation with bounded retries, idempotency keys written in the same transaction as the money movement, a transactional outbox for webhooks, and holds as an explicit state machine.

Tech highlights

Planned: a Python FastAPI core on Postgres, a TypeScript Fastify gateway for auth, rate limits and versioning, a Next.js merchant dashboard, a typed TypeScript SDK, and Helm charts with Chaos Mesh to kill pods mid-transfer.

Results

In progress: week 0 of a 10-week plan, the design, is done. The double-entry core and its property-based tests are next. Follow the build on GitHub.