# paritytech/substrate architecture

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

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

## Overview

##### Project type and purpose
- This is a monorepo SDK (“Polkadot SDK”) that merges three blockchain‑framework repositories (Cumulus, Substrate, Polkadot).
- It provides everything needed to build a blockchain node: runtime modules (FRAME pallets), client libraries (networking, consensus, storage, executor), node binaries, CLI tools, RPC servers, offchain workers, key management, and developer utilities.

##### File structure
- Top‑level groupings:
- bin/ → executable templates and production nodes (node‑template, node, chain‑spec tools).
- client/ → client‑side Rust crates: consensus protocols, networking stack, RPC API/backend, service orchestration, transaction pool, executor, keystore, offchain.
- frame/ → FRAME pallets (runtime modules) packaged as individual Cargo crates.
- primitives/ → shared types, runtime‑interface, cryptography, core blockchain primitives.
- utils/, scripts/, docker/ → developer tools, CI/CD pipelines, container definitions, monitoring setup.
- docs/ → contribution guidelines, design docs, style guide.

##### Key README insight
- The README simply announces the monorepo consolidation; no internal architecture docs.

- Node Binary (e.g. bin/node-template, bin/node) – entry point
- Service Layer (client/service) – orchestrator, task manager, chain‑ops
- Consensus Engines (client/consensus/{aura,babe,grandpa,beefy,…})
- Networking Stack (client/network + client/network‑gossip + client/network‑sync + client/network‑transactions + libp2p transport)
- Transaction Pool (client/transaction-pool)
- Block Builder & Mempool
- Executor (client/executor, client/executor/wasmtime) – runs WASM/native runtime
- Runtime Modules (frame/*) compiled to WASM and linked natively
- State Storage (client/db, client/state-db, primitives/state-machine)
- RPC Layer (client/rpc-api + client/rpc-servers + rpc-spec-v2)
- Offchain Workers & APIs (client/offchain)
- Keystore (client/keystore)
- Telemetry & Metrics (client/telemetry + Prometheus / Grafana containers)
- Developer Tools (subkey, chain-spec-builder, utils/*)

- CLI / RPC requests → Service Layer
- Service → Transaction Pool → Consensus → Block Builder
- Service → Executor (WASM/native) → State Storage
- Networking ↔ Service: broadcast/receive blocks & transactions
- Offchain Workers → Offchain DB / HTTP endpoints
- Service → RPC Layer → External clients
- Service → Telemetry → Prometheus → Grafana

c. Architectural patterns & principles
- Layered architecture (Entry → Service → Components → Storage)
- Plugin‑style modularity (FRAME pallets loaded into runtime)
- Separation of concerns (consensus / network / storage / execution / API)
- Cargo workspaces and crate‑per‑component for strict boundaries

d. Key technologies & libraries
- Rust + Cargo workspaces
- WebAssembly (WASM) for runtime
- libp2p for P2P transport
- Tokio for async
- ParityDB / RocksDB / custom DB backend
- Prometheus + Grafana for metrics
- Docker / Docker Compose for local test networks

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Layer
    subgraph "Entry Layer"
        NB["Node Binary (bin/node-template, bin/node)"]:::entry
        Tools["Developer Tools & CLI (bin, utils, scripts)"]:::tools
    end

    %% Service Layer
    subgraph "Service Layer"
        Service["Service Layer (client/service)"]:::service
    end

    %% Core Components
    subgraph "Core Components"
        Consensus["Consensus Engines (client/consensus)"]:::consensus
        Networking["Networking Stack (client/network, network-gossip, network/sync, network/transactions)"]:::network
        TransactionPool["Transaction Pool (client/transaction-pool)"]:::txpool
        BlockBuilder["Block Builder & Mempool (client/block-builder)"]:::txpool
        Executor["Executor (client/executor, executor/wasmtime)"]:::executor
        Runtime["Runtime Modules (frame/)"]:::runtime
        Offchain["Offchain Workers & APIs (client/offchain)"]:::offchain
        Keystore["Keystore (client/keystore)"]:::keystore
        RPC["RPC Layer (client/rpc-api, rpc-servers, rpc, rpc-spec-v2)"]:::rpc
        Telemetry["Telemetry & Metrics (client/telemetry, prometheus, grafana)"]:::telemetry
    end

    %% Storage Layer
    subgraph "Storage Layer"
        StateStorage["State Storage (client/db, state-db, primitives/state-machine)"]:::storage
    end

    %% Relationships
    NB -->|starts| Service
    Tools -->|invoke| Service
    Service -->|enqueue txs| TransactionPool
    TransactionPool -->|provides blocks| Consensus
    Consensus -->|builds blocks| BlockBuilder
    Service -->|executes runtime| Executor
    Executor -->|reads/writes| StateStorage
    Runtime -->|loaded by| Executor
    Networking <-->|"broadcast/receive"| Service
    Service -->|serves| RPC
    Service -->|handles offchain| Offchain
    Service -->|accesses keys| Keystore
    Service -->|records metrics| Telemetry

    %% Click Events
    click NB "https://github.com/paritytech/substrate/tree/master/bin/node-template/"
    click Tools "https://github.com/paritytech/substrate/tree/master/utils/"
    click Service "https://github.com/paritytech/substrate/tree/master/client/service/"
    click Consensus "https://github.com/paritytech/substrate/tree/master/client/consensus/"
    click Networking "https://github.com/paritytech/substrate/tree/master/client/network/"
    click TransactionPool "https://github.com/paritytech/substrate/tree/master/client/transaction-pool/"
    click BlockBuilder "https://github.com/paritytech/substrate/tree/master/client/block-builder/"
    click Executor "https://github.com/paritytech/substrate/tree/master/client/executor/"
    click Runtime "https://github.com/paritytech/substrate/tree/master/frame/"
    click StateStorage "https://github.com/paritytech/substrate/tree/master/client/db/"
    click RPC "https://github.com/paritytech/substrate/tree/master/client/rpc-api/"
    click Offchain "https://github.com/paritytech/substrate/tree/master/client/offchain/"
    click Keystore "https://github.com/paritytech/substrate/tree/master/client/keystore/"
    click Telemetry "https://github.com/paritytech/substrate/tree/master/client/telemetry/"

    %% Styles
    classDef entry fill:#E0BBE4,stroke:#957DAD,color:#000;
    classDef tools fill:#D291BC,stroke:#83677B,color:#000;
    classDef service fill:#FFDFD3,stroke:#FFB7B2,color:#000;
    classDef consensus fill:#C1E1C1,stroke:#88B04B,color:#000;
    classDef network fill:#A0CED9,stroke:#017E8A,color:#000;
    classDef txpool fill:#FCEEAD,stroke:#F9A620,color:#000;
    classDef executor fill:#FFAB76,stroke:#FF6F3C,color:#000;
    classDef runtime fill:#FFDDC1,stroke:#FFB347,color:#000;
    classDef offchain fill:#B5EAEA,stroke:#55A3A3,color:#000;
    classDef keystore fill:#FFDAC1,stroke:#FF9E80,color:#000;
    classDef rpc fill:#B5EAD7,stroke:#86C2A2,color:#000;
    classDef telemetry fill:#E5FCC2,stroke:#B5E655,color:#000;
    classDef storage fill:#ECECEC,stroke:#B0B0B0,color:#000;
```
