A financial ledger designed to handle concurrent writes, retries, and message broker failures without ever losing a cent.

Quick Start · Architecture · Highlights · Benchmarks ·

---

Architecture

graph TB
    subgraph API["API Layer"]
        H["HTTP Handlers"]
        M["Idempotency Middleware"]
        RI["Request ID Middleware"]
        OT["OpenTelemetry Middleware"]
    end

    subgraph Core["Core"]
        S["Ledger Service<br/>invariants and concurrency"]
    end

    subgraph Storage["Storage"]
        PG[("PostgreSQL 16<br/>transactions, postings, outbox")]
        RD[("Redis 7<br/>idempotency store")]
    end

    subgraph Events["Event Pipeline"]
        P["Outbox Poller"]
        N["NATS JetStream<br/>at least once"]
        BC["Balance Consumer<br/>CQRS projection"]
    end

    subgraph Observability["Observability"]
        PROM["Prometheus"]
        JAE["Jaeger"]
        GR["Grafana"]
    end

    RI --> H
    OT --> H
    H --> M --> S
    S --> PG
    M --> RD
    PG --> P --> N --> BC --> PG
    S --> PROM
    OT --> JAE
    PROM --> GR

Loading

Highlights

• Double entry ledger. Every movement is an immutable posting; balances are derived, never stored, so they can't silently drift.
• SERIALIZABLE concurrency control. Exponential backoff retry absorbs write conflicts; 400/400 concurrent transfers settled correctly across every stress run, zero write skew.
• Idempotent writes. Redis backed middleware with an in flight lock; the same Idempotency-Key always returns the same response, exactly one DB row.
• Transactional outbox. The event publish step can never outrun the commit; FOR UPDATE SKIP LOCKED makes the poller horizontally scalable for free.
• CQRS read path. O(1) balance reads via an async maintained cache, with a SUM(postings) fallback that guarantees correctness on a cold start.
• Full observability. OpenTelemetry tracing, Prometheus metrics, and a Grafana dashboard for throughput, latency, and contention, out of the box.

Benchmarks

Quick Start

git clone https://github.com/ellay21/journal.git
cd journal
docker compose up -d    # Postgres, Redis, NATS, Jaeger, Prometheus, Grafana
make migrate-up
make run                # API on :8080

make test               # unit tests, integration tests and race detector
make test-concurrency   # stress test: concurrent transfers, race detector on
make load-test          # k6 load scenarios

License

This project is licensed under the MIT License. See the LICENSE file for details.