# celestiaorg/celestia-node architecture

> Architecture diagram of the GitHub repository celestiaorg/celestia-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/celestiaorg/celestia-node
- Repository: https://github.com/celestiaorg/celestia-node

## Overview

This project is a Golang implementation of Celestia’s data availability node types (bridge, full, and light) that form part of the Celestia data availability (DA) network. The system is designed to interface with the underlying celestia-core consensus network and transform block data into a format that is digestible for data availability sampling. In other words, it wraps the consensus communication layer with additional logic for sampling, validating, and storing block data—in both a full reconstruction mode and a lighter, verification-only mode.

##### Main Components
- Node Types: The system supports different operating modes (bridge, full, and light nodes). Each node type has its own executable entry point (found in the “cmd” directory) and associated configuration/initialization logic.
- API Layer: Under “api”, there are components like the gateway (api/gateway) and RPC interfaces (api/rpc). These expose the public API for node management, health monitoring, client interaction, and network communication.
- Data Availability & Sampling Modules: The “das” folder, along with the “share” package and parts of “header” in the repository, handle data availability sampling, header verification, and the underlying block share processing.
- Blob & Storage Management: The “blob” directory and related modules in “store” outline the handling of data blobs, including the parsing, commitment proofs, and caching of block data.
- Core & Node Building Modules: The “core” directory and especially the large “nodebuilder” folder (with submodules like p2p, header, gateway, and state) indicate a modular architecture where various functionalities (like P2P communications, consensus integration, RPC, and state management) are built as interconnecting modules.
- Supporting Libraries & Utilities: Under “libs” and “store”, there are components for authentication, keystore (key management), PID storage, and common utilities which support core operations.
- Containerization & Infrastructure: Directories such as “Dockerfile”, “docker”, and GitHub workflows point to automated build/deployment and operational tooling.

##### Establish Relationships and Interactions
- API and RPC: Once processed, the data is made accessible over an API layer served by the gateway and RPC modules. These provide interaction points for administrators and other nodes.
- Node Builder Integration: Indicate how the “nodebuilder” modules integrate various functionalities:
- P2P Communications: Responsible for node discovery, data exchanges, and bootstrapping (nodebuilder/p2p).
- Header / Fraud Detection: Modules that handle header verification and fraud proofs (nodebuilder/header and nodebuilder/fraud).
- State & Storage: Components that manage node state and persistence (nodebuilder/state and the “store” package).
- Modular Architecture: Capture the modularity by showing that each module (gateway, rpc, das, blob, etc.) operates as a separate bounded context that collectively makes up the full node functionality.

##### Architectural Patterns and Technologies
- Modularity and Component Reuse: The repository is structured using well-defined modules (e.g., separate packages for node types, API, and data sampling), consistent with patterns such as layered architecture or microkernel design.
- Technology Stack: Note that the project is built entirely in Golang, using Docker for containerization, GitHub workflows for continuous integration/deployment, and various supporting libraries for key management, logging, and error handling.

##### Be Detailed and Explicit
- As many components as possible – even if some modules are internal or serve helper functions, it is better to visually break them out.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Systems
    EXTERNAL["Consensus Listener / Celestia-Core Interface"]:::external

    %% Node Types Subgraph
    subgraph "Node Types"
        CT["Celestia (Bridge Node)"]:::nodeType
        CK["Cel-key (Full Node)"]:::nodeType
        CS["Cel-shed (Light Node)"]:::nodeType
    end

    %% API Layer Subgraph
    subgraph "API Gateway & RPC Layer"
        AG["API Gateway"]:::api
        AR["RPC Layer"]:::api
    end

    %% Data Availability & Sampling Subgraph
    subgraph "Data Availability & Sampling"
        DAS["DAS Module"]:::das
        SHARE["Share Module"]:::das
        HDR["Header Verification"]:::das
    end

    %% Blob & Storage Management Subgraph
    subgraph "Blob & Storage Management"
        BLOB["Blob Management"]:::blob
        STORE["Storage Module"]:::blob
    end

    %% Core Module Subgraph
    subgraph "Core Module"
        CORE["Core Integration"]:::core
    end

    %% Node Builder Submodules Subgraph
    subgraph "Node Builder Modules"
        P2P["P2P Networking"]:::nodebuilder
        NB_HDR["Header Module"]:::nodebuilder
        NB_GATE["Gateway Module"]:::nodebuilder
        STATE["State Management"]:::nodebuilder
    end

    %% Supporting Libraries Subgraph
    subgraph "Supporting Libraries & Utilities"
        LIBS["Common Utilities"]:::support
        KEYSTORE["Keystore"]:::support
        PIDSTORE["PID Storage"]:::support
        CACHE["Cache Store"]:::support
    end

    %% Containerization & Infrastructure Subgraph
    subgraph "Containerization & Infrastructure"
        DOCKERFILE["Dockerfile"]:::infra
        DOCKER["Docker Configurations"]:::infra
        CI["GitHub Workflows"]:::infra
    end

    %% Connections
    EXTERNAL -->|"sends block data"| CT
    EXTERNAL -->|"sends block data"| CK
    EXTERNAL -->|"sends block data"| CS

    %% Node Types feeding into Data Availability
    CT -->|"initiate sampling"| DAS
    CK -->|"initiate sampling"| DAS
    CS -->|"initiate sampling"| DAS

    %% Data Availability internal processing
    DAS -->|"shares data with"| SHARE
    SHARE -->|"verifies headers"| HDR

    %% Data flows to Blob/Storage Management
    HDR -->|"processes block data"| BLOB
    DAS -->|"processes block data"| BLOB
    BLOB -->|"stores processed data"| STORE

    %% Blob/Storage to Core Integration
    STORE -->|"integrates node data"| CORE

    %% Core Integration splits into Node Builder Modules
    CORE -->|"enables peer comms"| P2P
    CORE -->|"validates headers"| NB_HDR
    CORE -->|"routes gateway calls"| NB_GATE
    CORE -->|"manages state"| STATE

    %% Node Builder Modules interact with API Layer
    NB_GATE -->|"serves client requests"| AG
    NB_GATE -->|"serves client requests"| AR

    %% Supporting Libraries used by multiple modules
    DAS --- LIBS
    BLOB --- LIBS
    CORE --- LIBS
    P2P --- LIBS
    NB_HDR --- LIBS
    NB_GATE --- LIBS
    STATE --- LIBS
    LIBS --- KEYSTORE
    LIBS --- PIDSTORE
    STORE --- CACHE

    %% Containerization impacts overall deployment
    CI --> DOCKERFILE
    DOCKERFILE --> CT
    DOCKERFILE --> CK
    DOCKERFILE --> CS
    DOCKER --> AG
    DOCKER --> AR

    %% Click Events for Node Types
    click CT "https://github.com/celestiaorg/celestia-node/tree/main/cmd/celestia"
    click CK "https://github.com/celestiaorg/celestia-node/tree/main/cmd/cel-key"
    click CS "https://github.com/celestiaorg/celestia-node/tree/main/cmd/cel-shed"

    %% Click Events for API Layer
    click AG "https://github.com/celestiaorg/celestia-node/tree/main/api/gateway"
    click AR "https://github.com/celestiaorg/celestia-node/tree/main/api/rpc"

    %% Click Events for Data Availability & Sampling
    click DAS "https://github.com/celestiaorg/celestia-node/tree/main/das"
    click SHARE "https://github.com/celestiaorg/celestia-node/tree/main/share"
    click HDR "https://github.com/celestiaorg/celestia-node/tree/main/header"

    %% Click Events for Blob & Storage Management
    click BLOB "https://github.com/celestiaorg/celestia-node/tree/main/blob"
    click STORE "https://github.com/celestiaorg/celestia-node/tree/main/store"

    %% Click Event for Core Module
    click CORE "https://github.com/celestiaorg/celestia-node/tree/main/core"

    %% Click Events for Node Builder Modules
    click P2P "https://github.com/celestiaorg/celestia-node/tree/main/nodebuilder/p2p"
    click NB_HDR "https://github.com/celestiaorg/celestia-node/tree/main/nodebuilder/header"
    click NB_GATE "https://github.com/celestiaorg/celestia-node/tree/main/nodebuilder/gateway"
    click STATE "https://github.com/celestiaorg/celestia-node/tree/main/nodebuilder/state"

    %% Click Events for Supporting Libraries & Utilities
    click LIBS "https://github.com/celestiaorg/celestia-node/tree/main/libs"
    click KEYSTORE "https://github.com/celestiaorg/celestia-node/tree/main/libs/keystore"
    click PIDSTORE "https://github.com/celestiaorg/celestia-node/tree/main/libs/pidstore"
    click CACHE "https://github.com/celestiaorg/celestia-node/tree/main/store/cache"

    %% Click Events for Containerization & Infrastructure
    click DOCKERFILE "https://github.com/celestiaorg/celestia-node/tree/main/Dockerfile"
    click DOCKER "https://github.com/celestiaorg/celestia-node/tree/main/docker"
    click CI "https://github.com/celestiaorg/celestia-node/tree/main/.github/workflows"

    %% Styles
    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px,color:#000000;
    classDef nodeType fill:#cce5ff,stroke:#3399ff,stroke-width:2px,color:#000000;
    classDef api fill:#e6ccff,stroke:#a64dff,stroke-width:2px,color:#000000;
    classDef das fill:#ccffe6,stroke:#33cc99,stroke-width:2px,color:#000000;
    classDef blob fill:#e6ffe6,stroke:#33cc33,stroke-width:2px,color:#000000;
    classDef core fill:#ffe6e6,stroke:#ff6666,stroke-width:2px,color:#000000;
    classDef nodebuilder fill:#fff2cc,stroke:#ffcc00,stroke-width:2px,color:#000000;
    classDef support fill:#e6f7ff,stroke:#33adff,stroke-width:2px,color:#000000;
    classDef infra fill:#f2f2f2,stroke:#a6a6a6,stroke-width:2px,color:#000000;
```
