ledger-flow
A transaction ledger that never charges twice.
An event-driven transaction ledger in Java 21, Spring Boot and Kafka, built to demonstrate a tested transactional outbox, idempotency keys and a deduplicating consumer.
ledger-api accepts POST /transactions with a required Idempotency-Key, writes the ledger row and an outbox row in one PostgreSQL transaction, and a relay publishes to Kafka once the broker acknowledges. ledger-notifier consumes the events, deduplicates on event id and projects the status into its own database.
The guarantees are proven by integration tests on real containers that inject failures — outbox atomicity, idempotent replay, broker outage, consumer deduplication. A Docker Compose stack runs both databases, Redpanda, the services, Prometheus and Grafana, with a correlation id traced across services. Decisions are recorded as ADRs.
- Type: Event-driven backend
- Status: In development — Milestone M5 of six; release 0.2.0. The README lists its production gaps (no authentication, single broker).
- Code: simonvildonelohim/ledger-flow
- Year: 2026
Built
- Idempotency keys: 201 new, 200 replay, 409 conflict
- Atomic ledger + outbox write
- Outbox relay publishing after broker ack
- Deduplicating consumer and status projection
- Correlation id across HTTP, outbox and Kafka
- Prometheus metrics: outbox depth, publication lag
- Failure-injection integration tests
- Architecture decision records
Technology
Java 21, Spring Boot, Apache Kafka, PostgreSQL, Flyway, Testcontainers, Prometheus, Grafana, Docker Compose
