Chronicle Ledger is a financial auditing system that prioritizes data integrity above all else. By using Event Sourcing, it ensures that no financial state is ever overwritten; instead, every transaction is stored as an immutable event. It implements CQRS to separate high-throughput writes (CockroachDB) from lightning-fast reads (PostgreSQL), bridged by NATS JetStream.
Run the entire distributed ledger (DBs + Bus + APIs) in 2 steps:
# 1. Start Infrastructure
docker-compose up -d
# 2. Start Application Services
npm install && npm run devDetailed Setup: See GETTING_STARTED.md.
Live event log streaming and account materialization.
CQRS Split: Write API (Event Store) -> NATS -> Read Processor -> Projected View.
Step-by-step: Command validation, Event persistence, and View migration.
Deep Dive: See ARCHITECTURE.md for Causal Consistency and Schema details.
- 📜 Immutable Event Log: Uses CockroachDB to store append-only financial records.
- ⚡ CQRS Implementation: Completely decouples Write Scaling from Read Performance.
- ⏰ Time-Travel Debugging: Ability to query account state at any historical microsecond.
- 🛡️ Double-Spend Protection: Optimistic Concurrency Control (OCC) at the event layer.
- 🌊 Async Projection: NATS JetStream ensures the Read side stays eventually consistent with 100% RELIABILITY.
How a simple deposit becomes an unhackable record:
- Command: User submits "Deposit $100" via the Write API.
- Verify: API validates current version (Concurrency check).
- Persist: The "Deposited" event is committed to the CockroachDB Event Store.
- Publish: NATS JetStream picks up the new event and broadcasts it.
- Project: The Read Processor consumes the event and updates the PostgreSQL Materialized View.
- Query: The user sees their updated balance instantly via the Query API.
| Document | Description |
|---|---|
| System Architecture | Event Schemas, NATS topology, and CQRS trade-offs. |
| Getting Started | Docker environment, DB init, and Load tests. |
| Failure Scenarios | Handling "Offline Processors" and NATS persistence. |
| Interview Q&A | "Event Sourcing vs CRUD", "Why CockroachDB?". |
| Component | Technology | Role |
|---|---|---|
| Write Store | CockroachDB | Distributed, Immutable Event Log. |
| Read Store | PostgreSQL | High-performance Projected Views. |
| Messaging | NATS JetStream | Resilient Async Event Bus. |
| Frontend | Next.js 14 | Real-time Audit & Visualization. |
Harshan Aiyappa
Senior Full-Stack Hybrid AI Engineer
Voice AI • Distributed Systems • Infrastructure
This project is licensed under the MIT License - see the LICENSE file for details.