# chainflip-io/chainflip-backend architecture

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

- Interactive diagram: https://gitdiagram.com/chainflip-io/chainflip-backend
- Repository: https://github.com/chainflip-io/chainflip-backend

## Overview

##### Core System
- That the project is organized as a Rust workspace with multiple executables (e.g., chainflip-broker-api, chainflip-cli, chainflip-ingress-egress-tracker, chainflip-lp-api, engine, engine-runner-bin, etc.) that together comprise the Chainflip protocol.

##### External Actors and Systems
- External Blockchains – Include external systems such as Bitcoin, Ethereum (including EVM), Solana, Polkadot, as well as other foreign chains (found under foreign-chains/solana). These represent the real-world blockchain networks that the system interacts with to perform cross-chain swaps.
- End Users / Traders – These might be application users or trading entities that trigger swaps (via the CLI or broker APIs).
- Administrators & Monitoring Tools – As the system includes testnet management (localnet, testnet, CI workflows) and health monitoring (logging endpoints in the engine), consider representing these actors too.
- Third Party Tools – You could show dependency on container orchestration, Docker, Helm charts, CI systems, and external services like Codecov (as seen in the README badge) that support development and deployment.

##### High-Level Interactions
- Use of containerization (Docker deployments, Helm charts, and localnet setups) as integration points for deployment and operational activities.

##### C4 System Context Scope
- Do not go into details of internal modules (e.g., the internal workings of engine, multisig, witness) but rather provide a high-level view.
- That while the internal implementation uses state-chain management, cross-chain witness modules, and complex cryptographic components, from a system context perspective they appear as part of the “Chainflip System” providing swap, governance, and liquidity services.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Internal Chainflip System Subgraph
    subgraph "Chainflip System"
        CF1("Chainflip Protocol"):::internal
        CF2("Chainflip Broker API"):::internal
        CF3("Chainflip CLI"):::internal
        CF4("Chainflip Ingress-Egress Tracker"):::internal
        CF5("Chainflip LP API"):::internal
        CF6("Chainflip Engine"):::internal
        CF7("Chainflip Engine Runner"):::internal
        CF8("Bouncer"):::internal
    end

    %% External Users Subgraph
    subgraph "External Users"
        U1("Trader"):::externalUser
        U2("Administrator"):::externalUser
    end

    %% External Blockchains Subgraph
    subgraph "External Blockchains"
        B1("Bitcoin"):::blockchain
        B2("Ethereum"):::blockchain
        B3("Solana"):::blockchain
        B4("Polkadot"):::blockchain
    end

    %% Infrastructure Subgraph
    subgraph "Infrastructure"
        I1("Third Party Tools"):::infrastructure
        I2("Localnet/Testnet Environment"):::infrastructure
    end

    %% Relationships between External Users and Chainflip Subcomponents
    U1 -->|"initiatesSwap"| CF2
    U1 -->|"issuesCommand"| CF3
    U2 -->|"monitors"| CF2

    %% Relationships between Chainflip Engine and External Blockchains (bidirectional)
    CF6 -->|"submitsTx"| B1
    B1 -->|"sendsEvent"| CF6

    CF6 -->|"submitsTx"| B2
    B2 -->|"sendsEvent"| CF6

    CF6 -->|"submitsTx"| B3
    B3 -->|"sendsEvent"| CF6

    CF6 -->|"submitsTx"| B4
    B4 -->|"sendsEvent"| CF6

    %% Relationships with Infrastructure
    I1 -->|"deployment"| CF1
    I2 -->|"integrationTest"| CF1

    %% Click Events for Chainflip Components
    click CF1 "https://github.com/chainflip-io/chainflip-backend/blob/main/."

    click CF2 "https://github.com/chainflip-io/chainflip-backend/tree/main/api/bin/chainflip-broker-api"
    click CF3 "https://github.com/chainflip-io/chainflip-backend/tree/main/api/bin/chainflip-cli"
    click CF4 "https://github.com/chainflip-io/chainflip-backend/tree/main/api/bin/chainflip-ingress-egress-tracker"
    click CF5 "https://github.com/chainflip-io/chainflip-backend/tree/main/api/bin/chainflip-lp-api"
    click CF6 "https://github.com/chainflip-io/chainflip-backend/tree/main/engine"
    click CF7 "https://github.com/chainflip-io/chainflip-backend/tree/main/engine-runner-bin"
    click CF8 "https://github.com/chainflip-io/chainflip-backend/tree/main/bouncer"

    %% Classes for styling
    classDef internal fill:#B3CDE0,stroke:#0D1B2A,stroke-width:2px;
    classDef externalUser fill:#FDEBD0,stroke:#E67E22,stroke-width:2px;
    classDef blockchain fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef infrastructure fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
```
