# shreyshringare/ledger architecture

> Architecture diagram of the GitHub repository shreyshringare/ledger, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shreyshringare/ledger
- Repository: https://github.com/shreyshringare/ledger

## Overview

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: [`internal/api/handlers.go`](https://github.com/shreyshringare/ledger/blob/main/internal/api/handlers.go) (REST API), [`internal/engine/engine.go`](https://github.com/shreyshringare/ledger/blob/main/internal/engine/engine.go) (Transaction engine), [`internal/mcp/tools.go`](https://github.com/shreyshringare/ledger/blob/main/internal/mcp/tools.go) (MCP tools), [`cmd/ledger-mcp/main.go`](https://github.com/shreyshringare/ledger/blob/main/cmd/ledger-mcp/main.go) (MCP command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_rest["REST API<br/>[handlers.go]"]
  node_cli["Ledger CLI<br/>[post.go]"]
  node_mcp_host["MCP command<br/>[main.go]"]
  node_mcp_server["MCP server<br/>[server.go]"]
  node_mcp_tools["MCP tools<br/>[tools.go]"]
end

subgraph group_ledger["Ledger core"]
  node_account_ops["Account operations<br/>[account.go]"]
  node_transaction_engine["Transaction engine<br/>[engine.go]"]
  node_transaction_rules["Entry validation<br/>[transaction.go]"]
  node_hash_chain["Chain verification<br/>[engine.go]"]
  node_store_contract["Store contract<br/>[store.go]"]
  node_postgres["PostgreSQL store<br/>[postgres.go]"]
  node_database[("PostgreSQL")]
end

subgraph group_analysis["Analysis services"]
  node_fraud_detection["Fraud detection<br/>[tarjan.go]"]
  node_reporting["Financial reports<br/>[report.go]"]
  node_reconciliation["Statement reconciliation<br/>[reconciler.go]"]
end

subgraph group_operations["Integrations and operations"]
  node_api_keys["API-key management"]
  node_circuit_breaker["Store resilience<br/>[circuitbreaker.go]"]
  node_metrics["Prometheus metrics<br/>[collectors.go]"]
  node_event_publisher["Event publisher<br/>[publisher.go]"]
end

node_client(("Ledger client"))
node_hermes["Hermes broker"]
node_prometheus(("Metrics scraper"))

node_client -->|"sends requests"| node_rest
node_rest -->|"posts transactions"| node_transaction_engine
node_rest -.->|"manages accounts"| node_account_ops
node_transaction_engine -->|"validates entries"| node_transaction_rules
node_transaction_engine -->|"persists transaction"| node_store_contract
node_store_contract -.->|"implemented by"| node_postgres
node_postgres -->|"reads and writes"| node_database
node_transaction_engine -->|"verifies chain"| node_hash_chain
node_rest -->|"requests verification"| node_hash_chain
node_rest -->|"detects rings"| node_fraud_detection
node_rest -->|"generates reports"| node_reporting
node_client -->|"runs commands"| node_cli
node_cli -->|"posts transactions"| node_transaction_engine
node_client -->|"uses MCP"| node_mcp_host
node_mcp_host -->|"starts server"| node_mcp_server
node_mcp_host -->|"registers tools"| node_mcp_tools
node_mcp_tools -->|"posts and verifies"| node_transaction_engine
node_mcp_tools -->|"detects rings"| node_fraud_detection
node_mcp_tools -->|"generates reports"| node_reporting
node_reconciliation -.->|"reads ledger"| node_store_contract
node_rest -->|"manages keys"| node_api_keys
node_circuit_breaker -->|"wraps store"| node_postgres
node_transaction_engine -->|"publishes events"| node_event_publisher
node_event_publisher -.->|"sends events"| node_hermes
node_prometheus -.->|"scrapes metrics"| node_metrics

click node_rest "https://github.com/shreyshringare/ledger/blob/main/internal/api/handlers.go"
click node_cli "https://github.com/shreyshringare/ledger/blob/main/cmd/ledger/post.go"
click node_mcp_host "https://github.com/shreyshringare/ledger/blob/main/cmd/ledger-mcp/main.go"
click node_mcp_server "https://github.com/shreyshringare/ledger/blob/main/internal/mcp/server.go"
click node_mcp_tools "https://github.com/shreyshringare/ledger/blob/main/internal/mcp/tools.go"
click node_account_ops "https://github.com/shreyshringare/ledger/blob/main/internal/engine/account.go"
click node_transaction_engine "https://github.com/shreyshringare/ledger/blob/main/internal/engine/engine.go"
click node_transaction_rules "https://github.com/shreyshringare/ledger/blob/main/internal/engine/transaction.go"
click node_hash_chain "https://github.com/shreyshringare/ledger/blob/main/internal/engine/engine.go"
click node_store_contract "https://github.com/shreyshringare/ledger/blob/main/internal/engine/store.go"
click node_postgres "https://github.com/shreyshringare/ledger/blob/main/internal/store/postgres.go"
click node_fraud_detection "https://github.com/shreyshringare/ledger/blob/main/internal/fraud/tarjan.go"
click node_reporting "https://github.com/shreyshringare/ledger/blob/main/internal/report/report.go"
click node_reconciliation "https://github.com/shreyshringare/ledger/blob/main/internal/reconcile/reconciler.go"
click node_api_keys "https://github.com/shreyshringare/ledger/blob/main/internal/api/handlers_apikeys.go"
click node_circuit_breaker "https://github.com/shreyshringare/ledger/blob/main/internal/store/circuitbreaker.go"
click node_metrics "https://github.com/shreyshringare/ledger/blob/main/internal/metrics/collectors.go"
click node_event_publisher "https://github.com/shreyshringare/ledger/blob/main/internal/stream/publisher.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rest,node_cli,node_mcp_host,node_mcp_server,node_mcp_tools,node_client toneBlue
class node_account_ops,node_transaction_engine,node_transaction_rules,node_hash_chain,node_store_contract,node_postgres,node_database toneAmber
class node_fraud_detection,node_reporting,node_reconciliation toneMint
class node_api_keys,node_circuit_breaker,node_metrics,node_event_publisher toneRose
class node_hermes,node_prometheus toneIndigo
```

## Components

### User interfaces

- [REST API](https://github.com/shreyshringare/ledger/blob/main/internal/api/handlers.go): `internal/api/handlers.go`
- [Ledger CLI](https://github.com/shreyshringare/ledger/blob/main/cmd/ledger/post.go): `cmd/ledger/post.go`
- [MCP command](https://github.com/shreyshringare/ledger/blob/main/cmd/ledger-mcp/main.go): `cmd/ledger-mcp/main.go`
- [MCP server](https://github.com/shreyshringare/ledger/blob/main/internal/mcp/server.go): `internal/mcp/server.go`
- [MCP tools](https://github.com/shreyshringare/ledger/blob/main/internal/mcp/tools.go): `internal/mcp/tools.go`

### Ledger core

- [Account operations](https://github.com/shreyshringare/ledger/blob/main/internal/engine/account.go): `internal/engine/account.go`
- [Transaction engine](https://github.com/shreyshringare/ledger/blob/main/internal/engine/engine.go): `internal/engine/engine.go`
- [Entry validation](https://github.com/shreyshringare/ledger/blob/main/internal/engine/transaction.go): `internal/engine/transaction.go`
- [Chain verification](https://github.com/shreyshringare/ledger/blob/main/internal/engine/engine.go): `internal/engine/engine.go`
- [Store contract](https://github.com/shreyshringare/ledger/blob/main/internal/engine/store.go): `internal/engine/store.go`
- [PostgreSQL store](https://github.com/shreyshringare/ledger/blob/main/internal/store/postgres.go): `internal/store/postgres.go`
- **PostgreSQL**

### Analysis services

- [Fraud detection](https://github.com/shreyshringare/ledger/blob/main/internal/fraud/tarjan.go): `internal/fraud/tarjan.go`
- [Financial reports](https://github.com/shreyshringare/ledger/blob/main/internal/report/report.go): `internal/report/report.go`
- [Statement reconciliation](https://github.com/shreyshringare/ledger/blob/main/internal/reconcile/reconciler.go): `internal/reconcile/reconciler.go`

### Integrations and operations

- [API-key management](https://github.com/shreyshringare/ledger/blob/main/internal/api/handlers_apikeys.go): `internal/api/handlers_apikeys.go`
- [Store resilience](https://github.com/shreyshringare/ledger/blob/main/internal/store/circuitbreaker.go): `internal/store/circuitbreaker.go`
- [Prometheus metrics](https://github.com/shreyshringare/ledger/blob/main/internal/metrics/collectors.go): `internal/metrics/collectors.go`
- [Event publisher](https://github.com/shreyshringare/ledger/blob/main/internal/stream/publisher.go): `internal/stream/publisher.go`

### Other components

- **Ledger client**
- **Hermes broker**
- **Metrics scraper**

## Connections

- Ledger client → REST API: sends requests
- REST API → Transaction engine: posts transactions (evidence: `internal/api/handlers.go`)
- REST API → Account operations: manages accounts
- Transaction engine → Entry validation: validates entries (evidence: `internal/engine/engine.go`)
- Transaction engine → Store contract: persists transaction (evidence: `internal/engine/engine.go`)
- Store contract → PostgreSQL store: implemented by
- PostgreSQL store → PostgreSQL: reads and writes
- Transaction engine → Chain verification: verifies chain (evidence: `internal/engine/engine.go`)
- REST API → Chain verification: requests verification (evidence: `internal/api/handlers.go`)
- REST API → Fraud detection: detects rings (evidence: `internal/api/handlers.go`)
- REST API → Financial reports: generates reports (evidence: `internal/api/handlers.go`)
- Ledger client → Ledger CLI: runs commands
- Ledger CLI → Transaction engine: posts transactions (evidence: `cmd/ledger/post.go`)
- Ledger client → MCP command: uses MCP
- MCP command → MCP server: starts server (evidence: `cmd/ledger-mcp/main.go`)
- MCP command → MCP tools: registers tools (evidence: `cmd/ledger-mcp/main.go`)
- MCP tools → Transaction engine: posts and verifies (evidence: `internal/mcp/tools.go`)
- MCP tools → Fraud detection: detects rings (evidence: `internal/mcp/tools.go`)
- MCP tools → Financial reports: generates reports (evidence: `internal/mcp/tools.go`)
- Statement reconciliation → Store contract: reads ledger
- REST API → API-key management: manages keys (evidence: `internal/api/handlers_apikeys.go`)
- Store resilience → PostgreSQL store: wraps store (evidence: `internal/store/circuitbreaker.go`)
- Transaction engine → Event publisher: publishes events (evidence: `internal/engine/engine.go`)
- Event publisher → Hermes broker: sends events
- Metrics scraper → Prometheus metrics: scrapes metrics
