# formancehq/ledger architecture

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

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

## Overview

##### 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:

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph External
        Client([Client])
        Kafka([Kafka])
        HTTP_Pub([HTTP Publisher])
        Prometheus([Prometheus])
        OpenTel([OpenTelemetry])
    end

    subgraph API_Layer
        V1[V1 API]:::api
        V2[V2 API]:::api
        Bulk[Bulk Operations]:::api
        Common[Common API]:::api
    end

    subgraph Controller_Layer
        LedgerCtrl[Ledger Controller]:::controller
        SystemCtrl[System Controller]:::controller
    end

    subgraph Engine_Layer
        VM[NumScript VM]:::engine
        Compiler[Script Compiler]:::engine
        TxProcessor[Transaction Processor]:::engine
        AccManager[Account Manager]:::engine
    end

    subgraph Storage_Layer
        BucketStore[Bucket Storage]:::storage
        LedgerStore[Ledger Storage]:::storage
        SystemStore[System Storage]:::storage
        DB[(PostgreSQL)]:::db
    end

    subgraph Event_System
        EventBus[Event Bus]:::event
        EventListener[Event Listener]:::event
        MessageHandler[Message Handler]:::event
    end

    subgraph Observability
        Metrics[Metrics]:::monitoring
        Traces[Traces]:::monitoring
    end

    %% Connections
    Client --> V1 & V2
    V1 & V2 --> Common
    V1 & V2 --> Bulk
    V1 & V2 --> LedgerCtrl & SystemCtrl
    LedgerCtrl & SystemCtrl --> VM
    VM --> Compiler
    VM --> TxProcessor
    VM --> AccManager
    TxProcessor & AccManager --> BucketStore & LedgerStore & SystemStore
    BucketStore & LedgerStore & SystemStore --> DB
    VM --> EventBus
    EventBus --> EventListener
    EventListener --> MessageHandler
    MessageHandler --> Kafka & HTTP_Pub
    Metrics --> Prometheus
    Traces --> OpenTel

    %% Click Events
    click VM "https://github.com/formancehq/ledger/tree/main/internal/machine/vm"
    click Compiler "https://github.com/formancehq/ledger/tree/main/internal/machine/script/compiler"
    click TxProcessor "https://github.com/formancehq/ledger/tree/main/internal/machine/vm/program"
    click V1 "https://github.com/formancehq/ledger/tree/main/internal/api/v1"
    click V2 "https://github.com/formancehq/ledger/tree/main/internal/api/v2"
    click Bulk "https://github.com/formancehq/ledger/tree/main/internal/api/bulking"
    click Common "https://github.com/formancehq/ledger/tree/main/internal/api/common"
    click BucketStore "https://github.com/formancehq/ledger/tree/main/internal/storage/bucket"
    click LedgerStore "https://github.com/formancehq/ledger/tree/main/internal/storage/ledger"
    click SystemStore "https://github.com/formancehq/ledger/tree/main/internal/storage/system"
    click EventBus "https://github.com/formancehq/ledger/tree/main/internal/bus"
    click EventListener "https://github.com/formancehq/ledger/blob/main/internal/bus/listener.go"
    click MessageHandler "https://github.com/formancehq/ledger/blob/main/internal/bus/message.go"
    click LedgerCtrl "https://github.com/formancehq/ledger/tree/main/internal/controller/ledger"
    click SystemCtrl "https://github.com/formancehq/ledger/tree/main/internal/controller/system"

    %% Styles
    classDef api fill:#90EE90,stroke:#333,stroke-width:2px
    classDef controller fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef engine fill:#4169E1,stroke:#333,stroke-width:2px
    classDef storage fill:#FFD700,stroke:#333,stroke-width:2px
    classDef event fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef db fill:#B8860B,stroke:#333,stroke-width:2px
    classDef monitoring fill:#20B2AA,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        L1[API Components]:::api
        L2[Controllers]:::controller
        L3[Engine Components]:::engine
        L4[Storage Components]:::storage
        L5[Event System]:::event
        L6[(Database)]:::db
        L7[Monitoring]:::monitoring
    end
```
