# formancehq/stack architecture

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

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

## Overview

##### Main Components Identification

a) Core Services:
- Formance Ledger (double-entry accounting)
- Formance Payments (unified payments processing)
- Formance Numscript (DSL for monetary computations)

b) Infrastructure Components:
- PostgreSQL (main storage)
- Redis (caching/syncing)
- Kafka/NATS (async communication)
- Traefik (API gateway)

##### Architectural Layers

**┌─ Client Layer ─────────────────────┐**
- CLI (fctl)                       │
- HTTP Clients                     │
- ┬───────────────────┘
- ↓
**┌─ Gateway Layer ────────────────────┐**
- Traefik                         │
- ┬───────────────────┘
- ↓
**┌─ Service Layer ────────────────────┐**
- ┌─────────┐ ┌────────┐ ┌────────┐ │
- Ledger  │ │Payments│ │Numscript│ │
- ┘ └────────┘ └────────┘ │
- ┬───────────────────┘
- ↓
**┌─ Message Layer ────────────────────┐**
- Kafka/NATS                       │
- ┬───────────────────┘
- ↓
**┌─ Storage Layer ────────────────────┐**
- PostgreSQL                       │
- Redis                           │
- ┘

##### Component Relationships
Key interactions:

a) Event Flow:
- Event versioning (v1.0.0, v2.0.0) as seen in the events directory

b) Service Integration:
- Integration points between services
- Webhook configurations and triggers
- Authentication flow

##### Additional Elements

a) Testing Infrastructure:
- Benchmark components
- Integration testing setup
- Load testing architecture

b) Deployment Options:
- Cloud deployment path
- Local development setup
- Container orchestration

##### Specific Implementation Details

- The modular nature of the system (services can be used independently)
- Event-driven architecture (based on the events/ directory structure)
- Multiple version support (as seen in the API versioning)
- Integration points (webhooks, triggers, workflows)

##### Notes for Implementation
- Use standard UML notation where applicable
- Keep service boundaries clear
- Scaling points
- Stateful vs stateless components
- Security and authentication boundaries

Remember to include observability components (seen in the benchmarks/tools directory) and show how monitoring and logging fit into the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Infrastructure Layer"
        PG[(PostgreSQL)]
        RD[(Redis)]
        KF[Kafka/NATS]
        TF[Traefik Gateway]
    end

    subgraph "Core Services"
        LS["Ledger Service"]:::core
        PS["Payments Service"]:::core
        NS["Numscript Service"]:::core
    end

    subgraph "Webhooks Service"
        subgraph "Config Management"
            WCM["Webhook Config Manager"]:::webhook
            SM["Secret Manager"]:::webhook
        end

        subgraph "Event Processing"
            EP["Event Processor"]:::webhook
            EF["Event Filter"]:::webhook
            ER["Event Router"]:::webhook
        end

        subgraph "Delivery System"
            WD["Webhook Dispatcher"]:::webhook
            RM["Retry Manager"]:::webhook
            ST["Status Tracker"]:::webhook
        end
    end

    EXT["External Services"]:::external

    %% Core Service Connections
    LS --> KF
    PS --> KF
    NS --> KF

    %% Event Flow
    KF --> EP
    EP --> EF
    EF --> ER
    ER --> WD

    %% Config Management Flow
    WCM --> PG
    WCM --> SM
    EP -.-> WCM
    
    %% Delivery System Flow
    WD --> RM
    WD --> ST
    RM --> WD
    WD --> EXT
    ST --> PG

    %% Infrastructure Connections
    WCM --> RD
    ST --> RD
    TF --> LS
    TF --> PS
    TF --> NS
    TF --> WCM

    %% Click Events
    click LS "https://github.com/formancehq/stack/blob/release/v2.1/tests/integration/internal/modules/ledger.go"
    click PS "https://github.com/formancehq/stack/blob/release/v2.1/tests/integration/internal/modules/payments.go"
    click WCM "https://github.com/formancehq/stack/blob/release/v2.1/tests/integration/suite/webhooks-configs-*.go"
    click EP "https://github.com/formancehq/stack/blob/release/v2.1/tests/integration/suite/webhooks-ledger-committed-transaction.go"
    click RM "https://github.com/formancehq/stack/blob/release/v2.1/tests/integration/suite/webhooks-retries.go"
    click TF "https://github.com/formancehq/stack/tree/release/v2.1/.local/gateway/Caddyfile"
    click PG "https://github.com/formancehq/stack/blob/release/v2.1/.local/postgres/multi-db.sh"

    %% Styling
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef webhook fill:#f1c40f,stroke:#f39c12,color:black
    classDef infrastructure fill:#2ecc71,stroke:#27ae60,color:white
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Legend
    subgraph Legend
        L1["Core Services"]:::core
        L2["Webhook Components"]:::webhook
        L3["Infrastructure"]:::infrastructure
        L4["External Systems"]:::external
    end
```
