How shreyshringare/ledger works
Ledger is a double-entry accounting engine exposed through a REST API, CLI, and MCP tools. The main workflow is a client request to post a transaction: API or MCP handling delegates to the engine, which validates the entries and persists a hash-chained transaction; a committed post may also publish an event. The product additionally supports account and balance operations, chain verification, fraud-ring detection, financial reports, reconciliation, API-key security, and Prometheus metrics. Some subsystems are documented but unsampled, so their edges are included only where the README establishes the relationship.
Main entry points: handlers.go REST API · engine.go Transaction engine · tools.go MCP tools · main.go MCP command
Components 22
User interfaces
- REST API
internal/api/handlers.go - Ledger CLI
cmd/ledger/post.go - MCP command
cmd/ledger-mcp/main.go - MCP server
internal/mcp/server.go - MCP tools
internal/mcp/tools.go
Ledger core
- Account operations
internal/engine/account.go - Transaction engine
internal/engine/engine.go - Entry validation
internal/engine/transaction.go - Chain verification
internal/engine/engine.go - Store contract
internal/engine/store.go - PostgreSQL store
internal/store/postgres.go - PostgreSQL
Analysis services
- Fraud detection
internal/fraud/tarjan.go - Financial reports
internal/report/report.go - Statement reconciliation
internal/reconcile/reconciler.go
Integrations and operations
- API-key management
internal/api/handlers_apikeys.go - Store resilience
internal/store/circuitbreaker.go - Prometheus metrics
internal/metrics/collectors.go - Event publisher
internal/stream/publisher.go
Other components
- Ledger client
- Hermes broker
- Metrics scraper
Connections 25
- Ledger client → REST API: sends requests
- REST API → Transaction engine: posts transactions
internal/api/handlers.go - REST API → Account operations: manages accounts
- Transaction engine → Entry validation: validates entries
internal/engine/engine.go - Transaction engine → Store contract: persists transaction
internal/engine/engine.go - Store contract → PostgreSQL store: implemented by
- PostgreSQL store → PostgreSQL: reads and writes
- Transaction engine → Chain verification: verifies chain
internal/engine/engine.go - REST API → Chain verification: requests verification
internal/api/handlers.go - REST API → Fraud detection: detects rings
internal/api/handlers.go - REST API → Financial reports: generates reports
internal/api/handlers.go - Ledger client → Ledger CLI: runs commands
- Ledger CLI → Transaction engine: posts transactions
cmd/ledger/post.go - Ledger client → MCP command: uses MCP
- MCP command → MCP server: starts server
cmd/ledger-mcp/main.go - MCP command → MCP tools: registers tools
cmd/ledger-mcp/main.go - MCP tools → Transaction engine: posts and verifies
internal/mcp/tools.go - MCP tools → Fraud detection: detects rings
internal/mcp/tools.go - MCP tools → Financial reports: generates reports
internal/mcp/tools.go - Statement reconciliation → Store contract: reads ledger
- REST API → API-key management: manages keys
internal/api/handlers_apikeys.go - Store resilience → PostgreSQL store: wraps store
internal/store/circuitbreaker.go - Transaction engine → Event publisher: publishes events
internal/engine/engine.go - Event publisher → Hermes broker: sends events
- Metrics scraper → Prometheus metrics: scrapes metrics