How formancehq/ledger works
Main Components
a) Core Components:
• Ledger Engine (internal/machine)
• API Layer (internal/api/v1 and v2)
• Storage Layer (internal/storage)
• Event Bus System (internal/bus)
• Controllers Layer (internal/controller)
b) External Interfaces:
• HTTP API Endpoints
• Event Publishers (examples show Kafka and HTTP)
• Database (PostgreSQL, indicated by migrations)
• OpenTelemetry Integration (shown by otel-collector-config.yaml)
Key Architectural Patterns to Highlight
a) Layered Architecture:
[API Layer (v1, v2)]
• ↓
[Controllers Layer]
• ↓
[Ledger Engine]
• ↓
[Storage Layer]
b) Event-Driven Architecture:
[Ledger Engine] → [Event Bus] → [Publishers (Kafka/HTTP)]
Detailed Component Breakdown
a) Ledger Engine:
• NumScript VM (internal/machine/vm)
• Script Compiler (internal/machine/script)
• Transaction Processor
• Account Manager
b) Storage Layer:
• Bucket Storage (internal/storage/bucket)
• Ledger Storage (internal/storage/ledger)
• System Storage (internal/storage/system)
c) API Components:
• REST Endpoints
• Bulk Operations Handler
• Pagination System
• Error Handling
Data Flow Representations
Client → API → Controller → Ledger Engine → Storage
Client → API → Controller → Event Bus → External Publishers
Additional Elements
• Configuration components (shown in deployments/)
• Monitoring/metrics integration (Prometheus)
• Migration system
• Multi-ledger support architecture
Implementation Details to Note
• Database schema references (from docs/database)
• Transaction workflow with special emphasis
Specific Technical Elements
• PostgreSQL as the primary storage
• OpenTelemetry for observability
• Docker deployment support
• Multiple API versions (v1, v2)
Key Considerations: