# cerebellum-network/blockchain-node architecture

> Architecture diagram of the GitHub repository cerebellum-network/blockchain-node, 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/cerebellum-network/blockchain-node
- Repository: https://github.com/cerebellum-network/blockchain-node

## Overview

##### Main components
- Blockchain Node Binary: The central executable built from Cargo (the Cargo.toml files at the root and in subprojects). This includes the core node under “node” (with subcomponents like cli, client, rpc, service) and is the entrypoint for running the blockchain.
- Runtime Layer: Located under the “runtime” directory (with “cere” and “cere-dev” folders) as well as “runtime/common”. This layer encapsulates the business logic, governance, consensus parameters, weights, and migration functions.
- Pallets: Found in the “pallets” folder with multiple pallets (e.g., chainbridge, ddc-clusters, ddc-customers, ddc-nodes, ddc-payouts, ddc-staking, ddc-verification, erc20, erc721, origins). Each pallet represents a modular component that extends the blockchain’s functionality.
- API and External Interfaces: The “ddc-api” directory includes API endpoints (and serialization logic via JSON and Protobuf definitions) that likely are used for external communication.
- Off-chain Tools & Supporting Modules: Tools like Zombienet (for testing ephemeral networks), various scripts (in the “scripts” directory), and Docker configurations (Dockerfile, docker-compose.yml) which help with deployment and testing.
- Developer and CI/CD Infrastructure: GitHub workflows, Docker deployment, and continuous integration files that ensure code quality and automated testing.

##### Analysing Relationships and Interactions
- The Node Component (esp. under “node/service”, “node/cli”, “node/rpc”) interacts with the Runtime Layer by initializing the chain state, loading runtime logic, and providing node services (e.g., RPC endpoints for querying, P2P networking for consensus).
- The Runtime Layer loads the configured pallets (from “pallets”) which collectively provide the blockchain’s modular logic—each pallet has its responsibilities (from metrics, staking, and verification, to ERC token standards) forming the core business logic.
- The API Layer (“ddc-api”) acts as an interface for external services to interact with the node, handling JSON or Protobuf requests, likely communicating with internal client and runtime modules.
- Testing, development, and orchestration tools (Zombienet, docker-compose, shell scripts) ensure that nodes, networks, and deployments are correctly configured for various environments (development chain, testnet, mainnet, etc.).
- Supporting infrastructure such as configuration files (.envrc, .cargo, Dockerfiles, and GitHub workflows) provide environment configuration, dependency management, and deployment instructions.

##### Architectural Patterns and Design Principles
- A layered architecture is evident: the lower layers (networking, consensus, storage) are abstracted away from the business logic in runtimes and pallets.
- Modular design using pallets supports extensibility; each pallet is self-contained with its own tests, migrations, and benchmarks.
- Separation of concerns is maintained by isolating command-line interfaces (CLI), client services, and APIs in the “node” and “ddc-api” directories.
- Containers and CI/CD pipelines are integrated via Docker, GitHub workflows, and shell scripts, ensuring consistent build and deployment practices.

##### Relevant Technologies, Frameworks, and Libraries
- Rust and Cargo are core to building the project.
- Substrate framework: The use of pallets, runtimes, and node service structure hints at Substrate’s design patterns.
- Docker and GitHub Actions: For containerization, continuous integration, and deployment.
- Zombienet: For testing network scenarios and ephemeral blockchain networks.
- Tools like dprint, rustfmt, and local script-based tooling support code formatting and pre-commit checks.

##### Elements
– Node (with subcomponents: CLI, Client, RPC, Service)
– Runtime (with sublayers: governance, weights, chain specs, off-chain workers possibly)
– API Layer (ddc-api) connected to the Node and external clients
– External Integration/Testing Tools (Zombienet, Docker, scripts)
– Data flow (e.g., user/CLI commands to the node, RPC calls to runtime and back)
– Dependencies (node initializes and loads runtime which, in turn, integrates pallets)
– Rectangles for execution modules (node, API)
– Rounded rectangles for logical layers (runtime, pallets)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User Interaction
    U("User"):::external

    %% API Layer
    subgraph "API Layer"
        A1("API: ddc-api"):::api
    end

    %% Blockchain Node Binary Subcomponents
    subgraph "Blockchain Node Binary"
        N1("CLI"):::node
        N2("Client"):::node
        N3("RPC"):::node
        N4("Service"):::node
    end

    %% Runtime Layer
    subgraph "Runtime Layer"
        R1("Runtime: Cere"):::runtime
        R2("Runtime: Cere-dev"):::runtime
        R3("Runtime: Common"):::runtime
    end

    %% Pallets (Modular Business Logic)
    subgraph "Pallets"
        P1("Pallet: chainbridge"):::pallet
        P2("Pallet: ddc-clusters-gov"):::pallet
        P3("Pallet: ddc-clusters"):::pallet
        P4("Pallet: ddc-customers"):::pallet
        P5("Pallet: ddc-metrics-offchain-worker"):::pallet
        P6("Pallet: ddc-nodes"):::pallet
        P7("Pallet: ddc-payouts"):::pallet
        P8("Pallet: ddc-staking"):::pallet
        P9("Pallet: ddc-verification"):::pallet
        P10("Pallet: erc20"):::pallet
        P11("Pallet: erc721"):::pallet
        P12("Pallet: origins"):::pallet
    end

    %% Off-chain Tools & Deployment
    subgraph "Off-chain & Deployment Tools"
        T1("Zombienet"):::tool
        T2("Scripts"):::tool
        T3("Dockerfile"):::tool
        T4("docker-compose.yml"):::tool
    end

    %% Developer & CI/CD Infrastructure
    subgraph "Dev & CI/CD Infrastructure"
        C1("GitHub Workflows"):::cicd
        C2("Cargo Config"):::cicd
        C3("Support Files"):::cicd
    end

    %% Relationships
    U -->|"sendsCommands"| N1
    U -->|"sendsRequests"| A1

    A1 -->|"callsRPC"| N3
    N3 -->|"forwards"| N4
    N1 -->|"initiates"| N4
    N4 -->|"loadsRuntime"| R3
    R3 -->|"selects"| R1
    R3 -->|"selects"| R2
    R3 -->|"integrates"| P1

    %% Off-chain interactions
    N4 -->|"testedBy"| T1
    N4 -->|"scriptedBy"| T2
    N4 -->|"containerizedBy"| T3
    N4 -->|"containerizedBy"| T4

    %% Dev & CI/CD support
    C1 -->|"automatesBuilds"| N2
    C2 -->|"configuresDeps"| N2
    C3 -->|"supportsProject"| N4

    %% Styling
    classDef external fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef api fill:#FFDEAD,stroke:#000,stroke-width:2px;
    classDef node fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef runtime fill:#B0E0E6,stroke:#000,stroke-width:2px;
    classDef pallet fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef tool fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef cicd fill:#AFEEEE,stroke:#000,stroke-width:2px;

    %% Click Events for Blockchain Node Binary
    click N1 "https://github.com/cerebellum-network/blockchain-node/tree/dev/node/cli"
    click N2 "https://github.com/cerebellum-network/blockchain-node/tree/dev/node/client"
    click N3 "https://github.com/cerebellum-network/blockchain-node/tree/dev/node/rpc"
    click N4 "https://github.com/cerebellum-network/blockchain-node/tree/dev/node/service"

    %% Click Events for Runtime Layer
    click R1 "https://github.com/cerebellum-network/blockchain-node/tree/dev/runtime/cere"
    click R2 "https://github.com/cerebellum-network/blockchain-node/tree/dev/runtime/cere-dev"
    click R3 "https://github.com/cerebellum-network/blockchain-node/tree/dev/runtime/common"

    %% Click Events for Pallets
    click P1 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/chainbridge"
    click P2 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/ddc-clusters-gov"
    click P3 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/ddc-clusters"
    click P4 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/ddc-customers"
    click P5 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/ddc-metrics-offchain-worker"
    click P6 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/ddc-nodes"
    click P7 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/ddc-payouts"
    click P8 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/ddc-staking"
    click P9 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/ddc-verification"
    click P10 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/erc20"
    click P11 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/erc721"
    click P12 "https://github.com/cerebellum-network/blockchain-node/tree/dev/pallets/origins"

    %% Click Event for API Layer
    click A1 "https://github.com/cerebellum-network/blockchain-node/tree/dev/ddc-api"

    %% Click Events for Off-chain Tools
    click T1 "https://github.com/cerebellum-network/blockchain-node/tree/dev/zombienet"
    click T2 "https://github.com/cerebellum-network/blockchain-node/tree/dev/scripts"
    click T3 "https://github.com/cerebellum-network/blockchain-node/tree/dev/Dockerfile"
    click T4 "https://github.com/cerebellum-network/blockchain-node/blob/dev/docker-compose.yml"

    %% Click Events for Dev & CI/CD Infrastructure
    click C1 "https://github.com/cerebellum-network/blockchain-node/tree/dev/.github/workflows"
    click C2 "https://github.com/cerebellum-network/blockchain-node/blob/dev/.cargo/config.toml"
    click C3 "https://github.com/cerebellum-network/blockchain-node/blob/dev/.envrc"
```
