# humanode-network/substrate architecture

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

- Interactive diagram: https://gitdiagram.com/humanode-network/substrate
- Repository: https://github.com/humanode-network/substrate

## Overview

This repository is the new consolidated Polkadot SDK – the result of merging the Substrate, Polkadot, and Cumulus repositories. Its purpose is to provide a unified, modular framework for developing Polkadot-based blockchains. The codebase is vast and highly segmented into logical modules such as client components, runtime modules (or “frame” pallets), primitives, networking, consensus mechanisms, database and state management, execution environments (including WASM runtimes), and assorted utilities and scripts for testing, CI, and debugging.

##### Main Components
- Node Client/Core Application – This includes the main runtime, executor, and client logic that orchestrate block building, validation, and chain state management. In the file tree, look at directories like “bin/node”, “client”, “primitives”, “runtime”, and “executor.”
- Runtime Module Layer (“Frame”):
– Contains the pallets that implement various blockchain features (e.g., balances, democracy, staking, consensus-related pallets, etc.). The “frame” directory and subdirectories (such as frame/contracts, frame/balances, frame/democracy, etc.) represent these components.
- Consensus and Networking:
– Structures in “client/consensus” (for Aura, Babe, Grandpa, etc.) and “client/network” represent the node-to-node communication protocols, block propagation, and consensus algorithms. These components interact closely with the client.
- RPC/API Layer and External Interfaces:
– The “client/rpc”, “client/rpc-api”, “client/rpc-servers” and similar directories expose REST/WebSocket endpoints, enabling communication with external services and front-end applications.
- Storage and Database:
– Modules under “client/db”, “client/state-db”, and “primitives/database” handle state persistence, key–value storage, and caching.
- Testing & Utilities:
– Directories such as “test-utils”, “scripts”, “utils”, “docker”, and “zombienet” support testing (including integration tests and performance benchmarks), build processes, and deployment automation.

##### Relationships and Interactions
- The Node Client is the central component. It invokes the WASM runtime (built from frame pallets) via the executor and interacts with the underlying state database.
- Consensus and Networking modules interact with the client to receive transactions/blocks, validate them, and propagate state:
– For instance, consensus engines such as Babe, Aura, or Grandpa are tightly integrated with the block builder and are depicted as separate but collaborating modules.
- The RPC/API layer sits on top, receiving requests from external applications and routing them to the client and runtime layers.
- Low-level primitives and storage libraries support all the above, providing cryptography, hashing, off-chain features, and other utilities.
- Testing frameworks (e.g., zombienet and test-utils) simulate a live network environment, helping validate consensus, networking, and runtime upgrades.

##### Architectural Patterns and Design Principles
- Modularity: The design emphasizes separation of concerns – runtime (“frame”) components are isolated from consensus and network modules, which are themselves separated from client and database components.
- Layering: The system is naturally layered from low-level primitives and storage up to high-level APIs. Each layer has clearly defined interactions with adjacent layers.
- Extensibility: There are several “pallet” modules (runtime modules) that can be independently developed, tested, or replaced. The project also supports multiple consensus algorithms allowing different network configurations.
- Build-time Tooling: Scripts and docker configurations help with continuous integration, multi-node simulations (using zombienet), and benchmarking.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% RPC/API Layer and External Interfaces
    subgraph "RPC/API Layer and External Interfaces"
        RPC1("RPC"):::rpc
        RPC2("RPC-API"):::rpc
        RPC3("RPC-Servers"):::rpc
    end

    %% Node Client/Core Application
    subgraph "Node Client/Core Application"
        NC1("Core Node"):::node
        NC2("CLI"):::node
        NC3("Service"):::node
        NC4("Executor"):::node
        NC5("Primitives"):::node
        NC6("Runtime"):::node
    end

    %% Runtime Module Layer (Frame Pallets)
    subgraph "Runtime Module Layer (Frame Pallets)"
        R1("Balances"):::runtime
        R2("Contracts"):::runtime
        R3("Democracy"):::runtime
        R4("Beefy"):::runtime
    end

    %% Storage and Database
    subgraph "Storage and Database"
        DB1("DB"):::storage
        DB2("State DB"):::storage
        DB3("Database (Primitive)"):::storage
    end

    %% Consensus and Networking
    subgraph "Consensus and Networking"
        subgraph "Consensus Engines"
            C1("Aura Consensus"):::consensus
            C2("Babe Consensus"):::consensus
            C3("Grandpa Consensus"):::consensus
        end
        subgraph "Networking Layer"
            N1("Gossip"):::network
            N2("Sync"):::network
        end
    end

    %% Testing & Utilities
    subgraph "Testing & Utilities"
        T1("Test Utils"):::test
        T2("Scripts (CI)"):::test
        T3("Docker"):::test
        T4("Utils"):::test
        T5("Zombienet"):::test
    end

    %% Connections
    %% RPC/API to Node Client
    RPC1 -->|"routes"| NC1
    RPC2 -->|"calls"| NC1
    RPC3 -->|"connects"| NC1

    %% Node Client internal interactions (vertical flow not explicitly detailed)
    NC4 -->|"invokesRuntime"| R1
    NC4 -->|"invokesRuntime"| R2
    NC4 -->|"invokesRuntime"| R3
    NC4 -->|"invokesRuntime"| R4

    %% Node Client to Storage and Database
    NC1 -->|"managesState"| DB2
    R1 -->|"writesState"| DB1
    R2 -->|"writesState"| DB3

    %% Consensus and Networking to Node Client
    C1 -->|"validates"| NC1
    C2 -->|"validates"| NC1
    C3 -->|"validates"| NC1
    N1 -->|"communicates"| NC1
    N2 -->|"synchronizes"| NC1

    %% Interactions within Consensus and Networking
    C1 -->|"notifies"| N1
    N2 -->|"informs"| C2

    %% Testing & Utilities impact on Node Client
    T5 -->|"simulatesNetwork"| NC1
    T1 -->|"tests"| NC1
    T2 -->|"CI_Builds"| NC1

    %% Click Events for Node Client/Core Application
    click NC1 "https://github.com/humanode-network/substrate/tree/master/bin/node"
    click NC2 "https://github.com/humanode-network/substrate/tree/master/client/cli"
    click NC3 "https://github.com/humanode-network/substrate/tree/master/client/service"
    click NC4 "https://github.com/humanode-network/substrate/tree/master/client/executor"
    click NC5 "https://github.com/humanode-network/substrate/tree/master/client/primitives"
    click NC6 "https://github.com/humanode-network/substrate/tree/master/client/runtime"

    %% Click Events for Runtime Module Layer
    click R1 "https://github.com/humanode-network/substrate/tree/master/frame/balances"
    click R2 "https://github.com/humanode-network/substrate/tree/master/frame/contracts"
    click R3 "https://github.com/humanode-network/substrate/tree/master/frame/democracy"
    click R4 "https://github.com/humanode-network/substrate/tree/master/frame/beefy"

    %% Click Events for Consensus Engines
    click C1 "https://github.com/humanode-network/substrate/tree/master/client/consensus/aura"
    click C2 "https://github.com/humanode-network/substrate/tree/master/client/consensus/babe"
    click C3 "https://github.com/humanode-network/substrate/tree/master/client/consensus/grandpa"

    %% Click Events for Networking Layer
    click N1 "https://github.com/humanode-network/substrate/tree/master/client/network/gossip"
    click N2 "https://github.com/humanode-network/substrate/tree/master/client/network/sync"

    %% Click Events for RPC/API Layer
    click RPC1 "https://github.com/humanode-network/substrate/tree/master/client/rpc"
    click RPC2 "https://github.com/humanode-network/substrate/tree/master/client/rpc-api"
    click RPC3 "https://github.com/humanode-network/substrate/tree/master/client/rpc-servers"

    %% Click Events for Storage and Database
    click DB1 "https://github.com/humanode-network/substrate/tree/master/client/db"
    click DB2 "https://github.com/humanode-network/substrate/tree/master/client/state-db"
    click DB3 "https://github.com/humanode-network/substrate/tree/master/primitives/database"

    %% Click Events for Testing & Utilities
    click T1 "https://github.com/humanode-network/substrate/tree/master/test-utils"
    click T2 "https://github.com/humanode-network/substrate/tree/master/scripts/ci"
    click T3 "https://github.com/humanode-network/substrate/tree/master/docker"
    click T4 "https://github.com/humanode-network/substrate/tree/master/utils"
    click T5 "https://github.com/humanode-network/substrate/tree/master/zombienet"

    %% Styles
    classDef rpc fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef node fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef runtime fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef storage fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef consensus fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef network fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef test fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
