Double-Entry Banking Ledger API

Back to projects
Double-Entry Banking Ledger API
Published
Java/Spring Boot/PostgreSQL/Keycloak/Testcontainers/k6

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.

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.

Profile Image of the Author
nonameTAT
olleH :)
Site Statistics
Posts
2
Total Words
3,039
Running Days
0 days
Last Activity
0 days ago
Site Info
Build Platform
GitHub Actions
Blog Version
Firefly v6.16.9
License
All Rights Reserved
Table of Contents