# acinq/eclair architecture

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

- Interactive diagram: https://gitdiagram.com/acinq/eclair
- Repository: https://github.com/acinq/eclair

## Overview

##### Project type and purpose
- Eclair is a multi‐module, actor‐based Scala implementation of a Lightning Network node.
- It comprises a core library (eclair-core), a standalone node runtime with HTTP JSON API (eclair-node), an optional cluster/front-end service (eclair-front), a CLI client (eclair-cli), plugin support, Docker packaging, and monitoring assets.
- It interfaces with Bitcoin Core for on-chain operations, speaks the Lightning wire protocol to other peers, and exposes a JSON API for client applications.

##### File structure
- Top-level directories/modules:
- eclair-core: the heart of the system (actors, FSMs, routers, DB layer, crypto, key management, blockchain watchers).
- eclair-node: bootstraps eclair-core, loads plugins, hosts Akka HTTP JSON API and WebSocket handlers.
- eclair-front: an Akka-cluster-based front-end gateway (cluster listener, front router), packaged for AWS EB.
- monitoring: Grafana dashboard definitions for metrics.
- contrib, Dockerfile, CI/CD config, docs, pom.xml/mvn wrapper.
- Config/build files: application.conf (HOCON), logback.xml, Dockerfile, maven-wrapper.
- Persistence: supports SQLite or PostgreSQL via JDBC (eclair-core/src/main/scala/fr/acinq/eclair/db).

##### README for additional insights
- Project description, JSON API warnings, plugin interface, Docker usage, external Bitcoin Core requirements, monitoring guidance.
- References to Akka actor system (Kamon instrumentation), plugin SPI, cluster usage (Cluster.md).

a. External dependencies
- Bitcoin Core node
– Interfaces: JSON-RPC (funding, closing, fee estimation), ZMQ (block/tx notifications)
- Lightning P2P network
– TCP Lightning wire protocol
- Clients / CLI (eclair-cli, custom apps)
- Monitoring stack (Prometheus/Kamon → Grafana dashboards)
b. Core runtime
- Eclair-core (Akka Actor System)
– On-chain actors (OnChainWallet, ZmqWatcher, RPC client)
– Channel FSM actors (ChannelOpen, Commitments, HTLC handlers)
– Router actor (Gossip, PathFinding, Graph)
– Payment manager actors (send, receive, relay workflows)
– Crypto/KeyManager (noise handshake, onion, ChaCha20, ShaChain)
– DB layer (audit, channels, peers, payments; migrations; SQLite / PG)
- Eclair-node
– Boot.scala (startup), plugin loader, Service.scala (Akka HTTP routes), API handlers (Channel, Payment, Node, Fees, WebSocket)
- Eclair-front (optional cluster gateway)
– ClusterListener, FrontRouter
c. Persistence
- SQLite / PostgreSQL – channel and node state, migrations
d. Monitoring & logging
- Kamon metrics exported → Prometheus → Grafana dashboards (monitoring/grafana-dashboard)
- Logback for application logs

##### Architectural patterns & technologies
- Actor model (Akka actors & FSM)
- Layered modules: core library → node application → front gateway → CLI/API clients
- Plugin SPI (dynamic JARs implementing Plugin.scala)
- Configuration via HOCON (application.conf), Logback
- Docker containers for node (x86_64/arm64), Bitcoin Core, monitoring
- CI/CD (GitHub Actions)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External"
        BitcoinCore["Bitcoin Core Node"]:::infra
        LightningNet["Lightning P2P Network"]:::external
        Clients["CLI/Clients"]:::external
        Prometheus["Prometheus"]:::infra
    end

    %% Monitoring
    subgraph "Monitoring Stack"
        Grafana["Grafana Dashboards"]:::monitor
    end

    %% Database
    subgraph "Persistence"
        DB["SQLite / PostgreSQL"]:::infra
    end

    %% Core Runtime
    subgraph "Eclair-core (Akka Actor System)" 
        OCActors["OnChain Wallet Actors"]:::core
        RPCClient["BasicBitcoinJsonRPCClient"]:::core
        ZmqWatcher["ZmqWatcher"]:::core
        ChannelFSM["Channel FSM Actors"]:::core
        Router["Router Actor & PathFinding"]:::core
        Crypto["Crypto & KeyManager"]:::core
        DBLayer["DB Layer & Migrations"]:::core
        JDBCUtils["JdbcUtils"]:::core
        PGImpl["PostgreSQL Impl"]:::core
        SQLiteImpl["SQLite Impl"]:::core
    end

    %% Node Runtime
    subgraph "Eclair-node (Akka HTTP JSON API)"
        BootNode["Boot.scala"]:::node
        PluginSPI["Plugin SPI Interface"]:::node
        Service["Service.scala (HTTP API)"]:::node
        Directive["API Directives"]:::node
        Handlers["API Handlers"]:::node
    end

    %% Front Gateway
    subgraph "Eclair-front (Akka Cluster Gateway)"
        BootFront["Boot.scala"]:::front
        ClusterListener["ClusterListener"]:::front
        FrontRouter["FrontRouter"]:::front
    end

    %% Connections
    BitcoinCore -->|"JSON-RPC"| RPCClient
    BitcoinCore -->|"ZMQ Notifications"| ZmqWatcher
    RPCClient -->|feeds| OCActors
    ZmqWatcher -->|feeds| OCActors
    OCActors -->|state| DB
    DB -->|jdbc| DBLayer
    DBLayer -->|uses| JDBCUtils
    DBLayer -->|PostgreSQL| PGImpl
    DBLayer -->|SQLite| SQLiteImpl
    OCActors -->|metrics| Prometheus
    Prometheus -->|visualize| Grafana
    OCActors -->|"TCP Lightning Protocol"| LightningNet

    OCActors -->|"actor msgs"| BootNode
    BootNode -->|"loads plugins"| PluginSPI
    BootNode -->|"starts service"| Service
    Clients -->|"HTTPS/JSON API"| Service
    Service -->|"uses directives"| Directive
    Service -->|"routes to handlers"| Handlers
    Service -->|"internal API"| OCActors

    %% Front cluster links
    BootFront -->|"cluster msgs"| OCActors
    OCActors -->|"cluster msgs"| BootFront

    %% Click Events
    click OCActorsGeneral "https://github.com/acinq/eclair/tree/master/eclair-core/src/main/scala/fr/acinq/eclair/blockchain/"
    click RPCClient "https://github.com/acinq/eclair/blob/master/eclair-core/src/main/scala/fr/acinq/eclair/blockchain/bitcoind/rpc/BasicBitcoinJsonRPCClient.scala"
    click ZmqWatcher "https://github.com/acinq/eclair/blob/master/eclair-core/src/main/scala/fr/acinq/eclair/blockchain/bitcoind/ZmqWatcher.scala"
    click ChannelFSM "https://github.com/acinq/eclair/tree/master/eclair-core/src/main/scala/fr/acinq/eclair/channel/fsm/"
    click Router "https://github.com/acinq/eclair/blob/master/eclair-core/src/main/scala/fr/acinq/eclair/router/Router.scala"
    click Crypto "https://github.com/acinq/eclair/tree/master/eclair-core/src/main/scala/fr/acinq/eclair/crypto/keymanager/"
    click DBLayer "https://github.com/acinq/eclair/tree/master/eclair-core/src/main/scala/fr/acinq/eclair/db/"
    click JDBCUtils "https://github.com/acinq/eclair/blob/master/eclair-core/src/main/scala/fr/acinq/eclair/db/jdbc/JdbcUtils.scala"
    click PGImpl "https://github.com/acinq/eclair/tree/master/eclair-core/src/main/scala/fr/acinq/eclair/db/pg/"
    click SQLiteImpl "https://github.com/acinq/eclair/tree/master/eclair-core/src/main/scala/fr/acinq/eclair/db/sqlite/"
    click EclairCore "https://github.com/acinq/eclair/tree/master/eclair-core/"
    click BootNode "https://github.com/acinq/eclair/blob/master/eclair-node/src/main/scala/fr/acinq/eclair/Boot.scala"
    click PluginSPI "https://github.com/acinq/eclair/blob/master/eclair-node/src/main/scala/fr/acinq/eclair/Plugin.scala"
    click Service "https://github.com/acinq/eclair/blob/master/eclair-node/src/main/scala/fr/acinq/eclair/api/Service.scala"
    click Directive "https://github.com/acinq/eclair/tree/master/eclair-node/src/main/scala/fr/acinq/eclair/api/directives/"
    click Handlers "https://github.com/acinq/eclair/tree/master/eclair-node/src/main/scala/fr/acinq/eclair/api/handlers/"
    click EclairNode "https://github.com/acinq/eclair/tree/master/eclair-node/"
    click BootFront "https://github.com/acinq/eclair/blob/master/eclair-front/src/main/scala/fr/acinq/eclair/Boot.scala"
    click ClusterListener "https://github.com/acinq/eclair/blob/master/eclair-front/src/main/scala/fr/acinq/eclair/ClusterListener.scala"
    click FrontRouter "https://github.com/acinq/eclair/blob/master/eclair-front/src/main/scala/fr/acinq/eclair/router/FrontRouter.scala"
    click EclairFront "https://github.com/acinq/eclair/tree/master/eclair-front/"
    click Clients "https://github.com/acinq/eclair/blob/master/contrib/eclair-cli.bash-completion"
    click Grafana "https://github.com/acinq/eclair/tree/master/monitoring/grafana-dashboard/"
    click Dockerfile "https://github.com/acinq/eclair/tree/master/Dockerfile"
    click ConfigRef "https://github.com/acinq/eclair/blob/master/eclair-core/src/main/resources/reference.conf"
    click AppConf "https://github.com/acinq/eclair/blob/master/eclair-node/src/main/resources/application.conf"
    click Logback "https://github.com/acinq/eclair/blob/master/eclair-node/src/main/resources/logback.xml"

    %% Styles
    classDef core fill:#D6E4F0,stroke:#45729D,color:#0B1D3A
    classDef node fill:#E7F6E7,stroke:#3D8B3D,color:#1B3D1B
    classDef front fill:#FFF0E1,stroke:#C87F0A,color:#4D2B00
    classDef infra fill:#F0F0F0,stroke:#AAAAAA,color:#333333
    classDef external fill:#FFEFEF,stroke:#D9534F,color:#5A1A1A
    classDef monitor fill:#F5E6FF,stroke:#9B59B6,color:#4B0082
```
