Double-Entry Banking Ledger API
Back to projectsBackend & consistencyDouble-entry postings, append-only history, idempotent retries, deadlock-free locking and per-account access.Java 25 · Spring Boot 4.1 · Hibernate · PostgreSQL 17 · Flyway · Spring Security · Keycloak · Testcontainers Performance & operationsk6 capacity testing that found the ceiling and a concurrency bug, plus monitoring and a rehearsed restore.k6 · Docker Compose · Micrometer · Prometheus · pg_dump · GitHub Actions
Double-Entry Banking Ledger API
PublishedJavaSpring BootPostgreSQLKeycloakTestcontainersk6
A double-entry banking API in Spring Boot and PostgreSQL that stays correct under retries, concurrency and failure, load-tested at 700–800 req/s with zero failed requests.
- Role
- Solo developer
- Period
- Jul – Oct 2026
Backend & consistency
207
tests against real PostgreSQL via Testcontainers
- History that can't be rewritten: every posting writes two balancing entries, and a database trigger rejects UPDATE and DELETE on them. A mistake is corrected by a linked reversal, at most once per transaction.
- Retries post exactly once: each posting carries a caller-chosen reference id with a payload fingerprint. An identical retry returns the original result, a different payload under the same id gets 409, and concurrent duplicates queue on an advisory lock so exactly one posts.
- Opposing transfers never deadlock: balance changes take pessimistic row locks in a fixed order, and a posting's entries, balances and audit row commit together or not at all.
- Per-account access through Keycloak: OIDC sign-in with Authorization Code and PKCE. Customers reach only their own accounts, freezing, reversals and reconciliation need an administrator, and a transfer reports only the source balance, so paying into an account doesn't reveal it.
- Tested against the failures a ledger meets: faults injected mid-posting, statement timeouts, killed connections, real deadlocks and a stopped database each fail fast with a 503 and a trace id, roll back fully, and a retry posts exactly once.
Performance & operations
700–800
req/s sustained from 5 to 100 clients, zero failures
30.7% → 0
request failures, after a bug load testing found
12 s
rehearsed restore, about 1 s of database downtime
- Request failures cut from 30.7% to zero: the first load run failed with optimistic-lock errors. The ownership check loaded the account before the locking read, so Hibernate reused a stale version; it had been invisible because every concurrency test ran as an administrator, who skips that check.
- Traced the throughput ceiling to one row: reads sustain about 8× the write mix, because every deposit and withdrawal locks the single system cash account. Sharding that account is the documented next step.
- Found reads slowing 10× as history grows: the paged entries endpoint counts every row on each request, so throughput fell from 6,291 to 653 req/s between 0 and 35k entries. Keyset pagination is the planned fix.
- Bad backups refused before anything is destroyed: empty, corrupt, truncated, wrong-schema and non-reconciling dumps are all rejected while the live database is untouched. Restores go to a staging database, pass reconciliation, then swap in by rename.
- Balance drift detected, never silently fixed: scheduled reconciliation recomputes every balance from its entries and records differences. Trace ids reach every response and log line, and Prometheus metrics start at zero so the first failure shows.
Everything is public. The two reports below have the method, raw numbers and known limits behind the figures above.






