Overview
Double-Entry Ledger Abstraction for building financial systems
Book Keeper is a ledger storage service that provides a clean API for recording and querying financial transactions. It's the foundational primitive for building wallets, billing systems, payment platforms, and accounting applications.
What is Book Keeper?
Think of it as a database specifically designed for money:
- Records balanced transactions using double-entry bookkeeping (every debit has an equal credit)
- Provides adapters for different storage backends (PostgreSQL, TigerBeetle, KurrentDB)
- Generates financial reports (General Ledger, Trial Balance, Balance Sheet)
- Handles multi-tenant isolation so multiple companies/products can share one deployment
- Maintains immutable audit trail of every financial state change
Real-World Example
Building a Digital Wallet? See Wallet Use Case for a complete walkthrough of how Book Keeper powers a multi-user wallet system with transfers, refills, and balance tracking.
Key Capabilities
| Feature | Description |
|---|---|
| Double-Entry Ledger | All transactions are balanced (debits = credits). Built-in validation. |
| Swappable Storage | Start with PostgreSQL, scale to TigerBeetle for high-throughput. |
| Event Integration | Listen to business events (e.g., InvoicePaid) and auto-record transactions. |
| Financial Reports | Pre-built projectors for GL, Trial Balance, Balance Sheet. |
| Multi-Tenancy | Strict data isolation per company/tenant. |
| 92% Test Coverage | Battle-tested with comprehensive integration and unit tests. |
Quick Start
Prerequisites
Development Setup
# Clone the repository
git clone https://gitlab.com/castlecraft/citadel.git
cd citadel
# Copy dev container config
cp -r devcontainer-example .devcontainer
# Open in VS Code and "Reopen in Container"
# VS Code will build the container and start all services
# Setup book-keeper environment
cd citadel/apps/book-keeper
cp devcontainer.env .env
# Run tests
pytest
# Start the service
python -m uvicorn app.main:app --reload
For detailed setup instructions, see the Getting Started Guide.
Documentation
| Document | Description |
|---|---|
| Wallet Use Case | Complete example: building a digital wallet system |
| Configuration Guide | Adapter setup, environment variables, deployment |
| Architecture Overview | Design patterns, bounded contexts, infrastructure |
| Technology Stack | Python, FastAPI, PostgreSQL, adapters |
| Getting Started | Development environment setup |
| ADRs | Architectural decisions and rationale |
Architectural Notes
Book Keeper uses Event Sourcing and CQRS patterns for auditability and performance:
- Write-side: Commands record events to an immutable event store
- Read-side: Projectors build optimized views for reports and queries
- Event Bus: Integrates with other services via NATS/Kafka
While these patterns provide strong guarantees, they add complexity. For simple use cases, consider whether you need full event sourcing or just a transactional ledger.
Note: The plugin-based translator pattern exists for event integration but is not the preferred approach. Use direct event handlers instead.
Contributing
See the Global Contributing Guidelines for development process, standards, and how to submit changes.
License
MIT License. See LICENSE for details.