# humanode-network/humanode architecture

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

## Overview

##### Main components of the system
- Node/Peer Component: Represented by the “humanode-peer” crate. This is the entry point that launches the node process (via the CLI) and integrates with the consensus and networking layers.
- Blockchain Runtime: The “humanode-runtime” crate contains runtime logic, state transition functions, and the definitions of various on-chain modules (pallets). Also include the assorted pallets (for bioauth, currency swaps, vesting, token claims, bootnodes, etc.) as subcomponents.
- RPC/API Layer: The “humanode-rpc” crate provides an API layer exposing node functionalities to external clients. It covers standard RPC endpoints and custom endpoints related to bioauth, cryptography, and other blockchain operations.
- Supporting and Utility Crates: There are many crates providing cryptographic utilities (crypto-utils, eip191-crypto, eip712-*), key management, and precompiled contracts (precompile-bioauth, precompile-native-currency, etc.), which are essential for specialized operations such as interfacing with EVM or for bridging operations.
- External Tools & Scripts: Also include the CI/CD workflows (.github), containerization (docker subfolder), and test utilities (utils/e2e-tests, util bioauth-test-tools) which support continuous integration, deployment, and testing.

##### Relationships and interactions
- The Node/Peer component initializes the blockchain node using Substrate’s runtime framework and interacts with the networking and consensus layers.
- It calls into the Runtime, which is built from multiple pallets. Each pallet (for example, pallet-bioauth, pallet-currency-swap, pallet-token-claims, etc.) handles specific on-chain logic such as authentication, token operations, or validator interactions.
- The RPC layer acts as an external interface to the Node, handling queries and transactions by communicating with the underlying runtime.
- Supporting utility crates (crypto, precompiles, primitives) provide common functions and data structures used by both the RPC and runtime components.
- Development and deployment tools (Dockerfiles, GitHub workflows, tests) encapsulate the environment setup and execution flows.

##### Important architectural patterns/design principles
- Modularity: The system is separated into many Rust crates, each encapsulating a particular function. This supports independent development, clear interfaces, and reuse.
- Layering: There is a clear separation between the network/peer layer, the runtime (which itself is modular via pallets), and the API layer. Dependencies are clearly factored.
- Interoperability: Several components handle cross-chain or web3–style operations (EVM integration, EIP protocols) and should be depicted as interfacing with external systems or protocols.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Substrate Framework
    SF["Substrate Framework (Rust)"]:::substrate

    %% Node/Peer Layer
    subgraph "Node/Peer Layer"
        HP["Humanode Peer"]:::forked
    end

    %% Blockchain Runtime Layer
    subgraph "Blockchain Runtime"
        HRT["Humanode Runtime"]:::forked
        %% Runtime Pallets
        PBA["Pallet: Bioauth"]:::forked
        PCS["Pallet: Currency Swap"]:::forked
        PVE["Pallet: Vesting"]:::forked
        PTC["Pallet: Token Claims"]:::forked
        PBN["Pallet: Bootnodes"]:::forked
        PCP["Pallet: Chain Properties"]:::forked
        PEA["Pallet: EVM Accounts Mapping"]:::forked
    end

    %% RPC/API Layer
    subgraph "RPC/API Layer"
        HRPC["Humanode RPC"]:::rpc
    end

    %% Supporting Utilities
    subgraph "Supporting Utilities"
        subgraph "Crypto Utilities"
            CU1["crypto-utils"]:::utils
            CU2["eip191-crypto"]:::utils
            CU3["eip712-account-claim"]:::utils
            CU4["eip712-common"]:::utils
            CU5["eip712-token-claim"]:::utils
        end
        subgraph "Precompiled Contracts"
            PC1["precompile-bioauth"]:::utils
            PC2["precompile-native-currency"]:::utils
            PC3["precompile-bls12381"]:::utils
            PC4["precompile-evm-accounts-mapping"]:::utils
            PC5["precompile-evm-to-native-swap"]:::utils
            PC6["precompile-utils"]:::utils
        end
    end

    %% External Tools & Scripts
    subgraph "External Tools & Scripts"
        EXT1["CI/CD & Workflows"]:::external
        EXT2["Containerization"]:::external
        EXT3["Test Utilities"]:::external
    end

    %% Relationships
    HRPC -->|"requests"| HP
    HP -->|"initiates"| HRT
    HP -->|"uses"| SF
    HRT -->|"implements"| PBA
    HRT -->|"implements"| PCS
    HRT -->|"implements"| PVE
    HRT -->|"implements"| PTC
    HRT -->|"implements"| PBN
    HRT -->|"implements"| PCP
    HRT -->|"implements"| PEA
    HRT <-->|"utilizes"| CU1
    HRT <-->|"utilizes"| CU2
    HRT <-->|"utilizes"| CU3
    HRT <-->|"utilizes"| CU4
    HRT <-->|"utilizes"| CU5
    HRT <-->|"leverages"| PC1
    HRT <-->|"leverages"| PC2
    HRT <-->|"leverages"| PC3
    HRT <-->|"leverages"| PC4
    HRT <-->|"leverages"| PC5
    HRT <-->|"leverages"| PC6
    EXT1 --- HP
    EXT1 --- HRT
    EXT1 --- HRPC
    EXT2 --- HP
    EXT2 --- HRT
    EXT3 --- HP
    EXT3 --- HRT

    %% Click Events
    click HP "https://github.com/humanode-network/humanode/tree/master/crates/humanode-peer"
    click HRT "https://github.com/humanode-network/humanode/tree/master/crates/humanode-runtime"
    click PBA "https://github.com/humanode-network/humanode/tree/master/crates/pallet-bioauth"
    click PCS "https://github.com/humanode-network/humanode/tree/master/crates/pallet-currency-swap"
    click PVE "https://github.com/humanode-network/humanode/tree/master/crates/pallet-vesting"
    click PTC "https://github.com/humanode-network/humanode/tree/master/crates/pallet-token-claims"
    click PBN "https://github.com/humanode-network/humanode/tree/master/crates/pallet-bootnodes"
    click PCP "https://github.com/humanode-network/humanode/tree/master/crates/pallet-chain-properties"
    click PEA "https://github.com/humanode-network/humanode/tree/master/crates/pallet-evm-accounts-mapping"
    click HRPC "https://github.com/humanode-network/humanode/tree/master/crates/humanode-rpc"
    click CU1 "https://github.com/humanode-network/humanode/tree/master/crates/crypto-utils"
    click CU2 "https://github.com/humanode-network/humanode/tree/master/crates/eip191-crypto"
    click CU3 "https://github.com/humanode-network/humanode/tree/master/crates/eip712-account-claim"
    click CU4 "https://github.com/humanode-network/humanode/tree/master/crates/eip712-common"
    click CU5 "https://github.com/humanode-network/humanode/tree/master/crates/eip712-token-claim"
    click PC1 "https://github.com/humanode-network/humanode/tree/master/crates/precompile-bioauth"
    click PC2 "https://github.com/humanode-network/humanode/tree/master/crates/precompile-native-currency"
    click PC3 "https://github.com/humanode-network/humanode/tree/master/crates/precompile-bls12381"
    click PC4 "https://github.com/humanode-network/humanode/tree/master/crates/precompile-evm-accounts-mapping"
    click PC5 "https://github.com/humanode-network/humanode/tree/master/crates/precompile-evm-to-native-swap"
    click PC6 "https://github.com/humanode-network/humanode/tree/master/crates/precompile-utils"
    click EXT1 "https://github.com/humanode-network/humanode/blob/master/.github"
    click EXT2 "https://github.com/humanode-network/humanode/tree/master/docker"
    click EXT3 "https://github.com/humanode-network/humanode/tree/master/utils/e2e-tests"

    %% Styles
    classDef substrate fill:#D6EAF8, stroke:#2874A6,stroke-width:2px;
    classDef forked fill:#F9E79F, stroke:#B7950B,stroke-width:2px;
    classDef rpc fill:#FAD7A0, stroke:#D35400,stroke-width:2px;
    classDef utils fill:#D2B4DE, stroke:#6C3483,stroke-width:2px;
    classDef external fill:#F5B7B1, stroke:#922B21,stroke-width:2px;
```
