fintech-ledger-engine

Double-entry ledger engine for financial transaction processing, multi-currency reconciliation, and treasury cash management — built for fintech systems that move real money.

Written in Python with strict typing and immutable data structures, because financial code that's wrong by a penny is wrong by everything.

What's Inside

fintech-ledger-engine/
├── ledger/
│   ├── __init__.py
│   ├── core.py               # Double-entry ledger with ACID guarantees
│   ├── account.py            # Chart of accounts and account types
│   ├── transaction.py        # Transaction creation, validation, posting
│   ├── reconciliation.py     # Multi-source reconciliation engine
│   ├── currency.py           # Multi-currency support with FX rates
│   ├── treasury.py           # Cash position tracking and forecasting
│   └── audit.py              # Immutable audit trail
├── tests/
│   ├── test_ledger.py
│   ├── test_reconciliation.py
│   └── test_treasury.py
├── requirements.txt
└── Makefile

Core Capabilities

Double-Entry Ledger

• Every transaction has balanced debits and credits — enforced at the engine level
• Immutable transaction log — posted entries are never modified, only reversed
• Account balance tracking with real-time and point-in-time queries
• Support for accrual and cash-basis accounting

Multi-Currency

• Transaction amounts stored in original currency and reporting currency
• FX rate snapshots at transaction time for audit trail
• Realized and unrealized gain/loss tracking on currency conversion
• Configurable rounding rules per currency (banker's rounding by default)

Reconciliation

• Match transactions across internal ledger, bank feeds, and payment processors
• Configurable matching rules: exact amount, date tolerance, reference matching
• Automatic categorization of breaks: timing, amount, missing, duplicate
• Break resolution workflow with audit trail

Treasury / Cash Management

• Real-time cash position across all accounts and currencies
• Cash flow forecasting based on scheduled transactions and historical patterns
• Liquidity analysis: available vs. committed vs. reserved
• Sweep rules for automated inter-account transfers

Audit Trail

• Hash-chained transaction log for tamper detection
• Every state change recorded with actor, timestamp, and reason
• Exportable for external audit (SOX, SOC 2 aligned)

Quick Start

pip install -r requirements.txt
python -m pytest tests/ -v

# Run the ledger demo
python -m ledger.core

Design Principles

1. Debits must equal credits — the fundamental invariant, enforced everywhere
2. Immutable history — transactions are facts; you correct by reversing, not editing
3. Decimal, never float — all monetary values use Python's Decimal type
4. Auditable by default — if money moved, there's a record of why

Background

Built from experience at the US Department of the Treasury, where financial systems operate under regulatory scrutiny that makes SOX look casual. The patterns here — double-entry enforcement, immutable logs, reconciliation engines — are the foundation of every serious fintech system.

License

MIT