Case Study

Fintech Core: Credit Ledger

Production-ready reference architecture for SaaS credits, marketplace wallets, and usage-based billing.

Credit Ledger is a microservices blueprint for teams hitting the limits of simple "credits column" designs. It demonstrates how to build a scalable financial core using Go, Kafka, and Postgres—replacing fragile spreadsheets with an immutable, double-entry ledger that guarantees auditability and exactly-once processing.

I use this architecture as a reference for consulting clients who need to migrate from "moving fast and breaking things" to "moving money safely".

View Swagger API

View on GitHub

Read Case Study

The Problem: Spreadsheet Chaos

Most SaaS platforms and marketplaces start simple: a single credits_remaining column in a user table. This works until you scale, leading to:

Race Conditions: Concurrent requests double-spend credits.
Data Drift: Dashboards, invoices, and databases disagree on the balance.
Audit Blindness: Support cannot explain why a customer's balance is 37 instead of 50.

This project solves these issues by treating credits as financial transactions, not just a counter.

Architecture & Patterns

High-level architecture diagram showing Gateway, Ledger, Outbox, and Read Models. — The system decouples high-speed writing (Ledger) from querying (Read Models) via an event bus.

This is a comprehensive Reference Architecture designed to be cloned and adapted. It enforces strict financial invariants while maintaining microservice decoupling:

Double-Entry Core: Every move is a balanced transaction (Debit/Credit). Money is never created or destroyed, only moved.
Transactional Outbox: Writes to the DB and publishes events atomically. This prevents "dual-write" hazards where the DB updates but the event fails.
CQRS Projections: Read models are separate from the ledger. If you need a new dashboard view, you can replay the event history to build it without touching the core ledger.

Real-World Use Cases

Unlike toy demos, this project includes domain modeling for specific business scenarios found in Fintech and SaaS:

SaaS Subscriptions

Granting monthly usage credits that expire, handling overages, and reconciling invoices.

Marketplace Escrow

Holding funds in an intermediary wallet until a service is delivered, then releasing to the seller.

Loyalty Points

Managing earn/burn rates with audit trails for dispute resolution.

Digital Wallets

Peer-to-peer transfers with exactly-once guarantees.

Observability: 'What happened to my credit?'

A "black box" ledger is useless when money goes missing. This architecture comes pre-wired with a full observability stack to answer support questions instantly.

Jaeger trace showing the full journey of a transfer. — Distributed tracing visualizes the request lifecycle: Gateway → Orchestrator → Ledger Write → Outbox Relay → Kafka → Read Model.

Grafana dashboard showing business metrics and consumer lag. — Business-level monitoring tracks transfer volume, while system metrics watch for consumer lag and outbox health.

The system exposes OpenTelemetry traces and Prometheus metrics out of the box. This allows operators to distinguish between a slow database, a backed-up Kafka consumer, or a failed external webhook immediately.

Performance & Benchmarks

Designed for high-throughput reliability. On a standard 2-vCPU instance, the reference implementation sustains ~400 transfers/second (end-to-end) with p95 latency under 60ms.

It serves as a "middle path" for teams who need more structure than a SQL table but aren't ready to adopt specialized infrastructure like TigerBeetle.