# chrinoreesambu/ledger architecture

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

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

## Overview

Formance Ledger is a programmable financial core: clients submit atomic postings or Numscript transactions, then query ledger state and balances. The API delegates ledger operations to controllers, which apply transaction rules and persist ledger records. The README identifies PostgreSQL as the transactional store and describes shipping ledger logs to replica stores; sampled pipeline code confirms ordered log fetching and exporter delivery. The v2 pipeline endpoints delegate lifecycle operations to the system controller. The tree documents additional query, schema, bucket, and log-import/export capabilities; their internal wiring is not inferred here.

Main entry points: [`internal/controller/ledger/controller_default.go`](https://github.com/chrinoreesambu/ledger/blob/main/internal/controller/ledger/controller_default.go) (Ledger controller), [`internal/api/v2/routes.go`](https://github.com/chrinoreesambu/ledger/blob/main/internal/api/v2/routes.go) (v2 controllers), [`internal/controller/system/controller.go`](https://github.com/chrinoreesambu/ledger/blob/main/internal/controller/system/controller.go) (System controller), [`internal/replication/drivers/driver.go`](https://github.com/chrinoreesambu/ledger/blob/main/internal/replication/drivers/driver.go) (Exporter drivers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_http["HTTP API<br/>[router.go]"]
  node_v2["v2 controllers<br/>[routes.go]"]
  node_pipeline_api["Pipeline endpoints"]
end

subgraph group_ledger["Ledger domain"]
  node_system["System controller<br/>[controller.go]"]
  node_ledger_controller["Ledger controller"]
  node_numscript["Numscript runtime"]
  node_machine["Transaction machine<br/>[run.go]"]
  node_accounts["Accounts and balances"]
  node_transactions["Transactions"]
  node_schemas["Schemas and queries"]
end

subgraph group_persistence["Persistence"]
  node_ledger_store["Ledger storage<br/>[store.go]"]
  node_system_store["System storage<br/>[store.go]"]
end

subgraph group_replication["Log replication"]
  node_pipeline_model["Pipeline state<br/>[pipeline.go]"]
  node_replication_pipeline["Log pipeline<br/>[pipeline.go]"]
  node_drivers["Exporter drivers<br/>[driver.go]"]
  node_clickhouse["ClickHouse exporter<br/>[driver.go]"]
  node_elastic["Elasticsearch exporter<br/>[driver.go]"]
  node_http_exporter["HTTP exporter<br/>[driver.go]"]
end

node_client["Ledger client<br/>[v2.go]"]
node_postgres[("PostgreSQL")]
node_replica[("Replica data store")]

node_client -->|"sends requests"| node_http
node_http -->|"routes requests"| node_v2
node_v2 -->|"dispatches"| node_transactions
node_v2 -->|"dispatches"| node_accounts
node_v2 -->|"dispatches"| node_schemas
node_v2 -->|"dispatches"| node_pipeline_api
node_transactions -->|"invokes"| node_ledger_controller
node_accounts -->|"invokes"| node_ledger_controller
node_schemas -->|"invokes"| node_ledger_controller
node_pipeline_api -->|"invokes"| node_system
node_system -->|"obtains controller"| node_ledger_controller
node_ledger_controller -->|"parses scripts"| node_numscript
node_ledger_controller -->|"executes transactions"| node_machine
node_ledger_controller -->|"reads and writes"| node_ledger_store
node_ledger_store -->|"persists records"| node_postgres
node_system -->|"manages state"| node_system_store
node_system_store -->|"persists state"| node_postgres
node_system -->|"manages pipelines"| node_pipeline_model
node_replication_pipeline -->|"fetches logs"| node_ledger_store
node_replication_pipeline -->|"delivers logs"| node_drivers
node_drivers -->|"selects exporter"| node_clickhouse
node_drivers -->|"selects exporter"| node_elastic
node_drivers -->|"selects exporter"| node_http_exporter
node_clickhouse -->|"writes replica data"| node_replica
node_elastic -->|"writes replica data"| node_replica
node_http_exporter -->|"sends replica data"| node_replica

click node_client "https://github.com/chrinoreesambu/ledger/blob/main/pkg/client/v2.go"
click node_http "https://github.com/chrinoreesambu/ledger/blob/main/internal/api/router.go"
click node_v2 "https://github.com/chrinoreesambu/ledger/blob/main/internal/api/v2/routes.go"
click node_pipeline_api "https://github.com/chrinoreesambu/ledger/blob/main/internal/api/v2/controllers_pipeline_create.go"
click node_system "https://github.com/chrinoreesambu/ledger/blob/main/internal/controller/system/controller.go"
click node_ledger_controller "https://github.com/chrinoreesambu/ledger/blob/main/internal/controller/ledger/controller_default.go"
click node_numscript "https://github.com/chrinoreesambu/ledger/blob/main/internal/controller/ledger/numscript_runtime.go"
click node_machine "https://github.com/chrinoreesambu/ledger/blob/main/internal/machine/vm/run.go"
click node_accounts "https://github.com/chrinoreesambu/ledger/blob/main/internal/api/v2/controllers_accounts_list.go"
click node_transactions "https://github.com/chrinoreesambu/ledger/blob/main/internal/api/v2/controllers_transactions_create.go"
click node_schemas "https://github.com/chrinoreesambu/ledger/blob/main/internal/api/v2/controllers_schema_insert.go"
click node_ledger_store "https://github.com/chrinoreesambu/ledger/blob/main/internal/storage/ledger/store.go"
click node_system_store "https://github.com/chrinoreesambu/ledger/blob/main/internal/storage/system/store.go"
click node_pipeline_model "https://github.com/chrinoreesambu/ledger/blob/main/internal/pipeline.go"
click node_replication_pipeline "https://github.com/chrinoreesambu/ledger/blob/main/internal/replication/pipeline.go"
click node_drivers "https://github.com/chrinoreesambu/ledger/blob/main/internal/replication/drivers/driver.go"
click node_clickhouse "https://github.com/chrinoreesambu/ledger/blob/main/internal/replication/drivers/clickhouse/driver.go"
click node_elastic "https://github.com/chrinoreesambu/ledger/blob/main/internal/replication/drivers/elasticsearch/driver.go"
click node_http_exporter "https://github.com/chrinoreesambu/ledger/blob/main/internal/replication/drivers/http/driver.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_http,node_v2,node_pipeline_api,node_client toneBlue
class node_system,node_ledger_controller,node_numscript,node_machine,node_accounts,node_transactions,node_schemas,node_postgres,node_replica toneAmber
class node_ledger_store,node_system_store toneMint
class node_pipeline_model,node_replication_pipeline,node_drivers,node_clickhouse,node_elastic,node_http_exporter toneRose
```

## Components

### API surface

- [HTTP API](https://github.com/chrinoreesambu/ledger/blob/main/internal/api/router.go): `internal/api/router.go`
- [v2 controllers](https://github.com/chrinoreesambu/ledger/blob/main/internal/api/v2/routes.go): `internal/api/v2/routes.go`
- [Pipeline endpoints](https://github.com/chrinoreesambu/ledger/blob/main/internal/api/v2/controllers_pipeline_create.go): `internal/api/v2/controllers_pipeline_create.go`

### Ledger domain

- [System controller](https://github.com/chrinoreesambu/ledger/blob/main/internal/controller/system/controller.go): `internal/controller/system/controller.go`
- [Ledger controller](https://github.com/chrinoreesambu/ledger/blob/main/internal/controller/ledger/controller_default.go): `internal/controller/ledger/controller_default.go`
- [Numscript runtime](https://github.com/chrinoreesambu/ledger/blob/main/internal/controller/ledger/numscript_runtime.go): `internal/controller/ledger/numscript_runtime.go`
- [Transaction machine](https://github.com/chrinoreesambu/ledger/blob/main/internal/machine/vm/run.go): `internal/machine/vm/run.go`
- [Accounts and balances](https://github.com/chrinoreesambu/ledger/blob/main/internal/api/v2/controllers_accounts_list.go): `internal/api/v2/controllers_accounts_list.go`
- [Transactions](https://github.com/chrinoreesambu/ledger/blob/main/internal/api/v2/controllers_transactions_create.go): `internal/api/v2/controllers_transactions_create.go`
- [Schemas and queries](https://github.com/chrinoreesambu/ledger/blob/main/internal/api/v2/controllers_schema_insert.go): `internal/api/v2/controllers_schema_insert.go`

### Persistence

- [Ledger storage](https://github.com/chrinoreesambu/ledger/blob/main/internal/storage/ledger/store.go): `internal/storage/ledger/store.go`
- [System storage](https://github.com/chrinoreesambu/ledger/blob/main/internal/storage/system/store.go): `internal/storage/system/store.go`

### Log replication

- [Pipeline state](https://github.com/chrinoreesambu/ledger/blob/main/internal/pipeline.go): `internal/pipeline.go`
- [Log pipeline](https://github.com/chrinoreesambu/ledger/blob/main/internal/replication/pipeline.go): `internal/replication/pipeline.go`
- [Exporter drivers](https://github.com/chrinoreesambu/ledger/blob/main/internal/replication/drivers/driver.go): `internal/replication/drivers/driver.go`
- [ClickHouse exporter](https://github.com/chrinoreesambu/ledger/blob/main/internal/replication/drivers/clickhouse/driver.go): `internal/replication/drivers/clickhouse/driver.go`
- [Elasticsearch exporter](https://github.com/chrinoreesambu/ledger/blob/main/internal/replication/drivers/elasticsearch/driver.go): `internal/replication/drivers/elasticsearch/driver.go`
- [HTTP exporter](https://github.com/chrinoreesambu/ledger/blob/main/internal/replication/drivers/http/driver.go): `internal/replication/drivers/http/driver.go`

### Other components

- [Ledger client](https://github.com/chrinoreesambu/ledger/blob/main/pkg/client/v2.go): `pkg/client/v2.go`
- **PostgreSQL**
- **Replica data store**

## Connections

- Ledger client → HTTP API: sends requests
- HTTP API → v2 controllers: routes requests
- v2 controllers → Transactions: dispatches
- v2 controllers → Accounts and balances: dispatches
- v2 controllers → Schemas and queries: dispatches
- v2 controllers → Pipeline endpoints: dispatches
- Transactions → Ledger controller: invokes
- Accounts and balances → Ledger controller: invokes
- Schemas and queries → Ledger controller: invokes
- Pipeline endpoints → System controller: invokes
- System controller → Ledger controller: obtains controller
- Ledger controller → Numscript runtime: parses scripts
- Ledger controller → Transaction machine: executes transactions
- Ledger controller → Ledger storage: reads and writes
- Ledger storage → PostgreSQL: persists records
- System controller → System storage: manages state
- System storage → PostgreSQL: persists state
- System controller → Pipeline state: manages pipelines
- Log pipeline → Ledger storage: fetches logs
- Log pipeline → Exporter drivers: delivers logs
- Exporter drivers → ClickHouse exporter: selects exporter
- Exporter drivers → Elasticsearch exporter: selects exporter
- Exporter drivers → HTTP exporter: selects exporter
- ClickHouse exporter → Replica data store: writes replica data
- Elasticsearch exporter → Replica data store: writes replica data
- HTTP exporter → Replica data store: sends replica data