# thorchain/thornode architecture

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

## Overview

##### Recognize the Project Context
- Although the file tree only shows a README.md, the README points us to the GitLab repository for thornode (https://gitlab.com/thorchain/thornode). Knowing that Thornode is part of THORChain gives context—it is likely a critical node or backend component within a decentralized liquidity network that handles cross-chain transactions.

##### And Define the Main Components
- Core Node Logic: This is where the internal processing happens. Consider subcomponents like transaction processing, block validation, and consensus logic.
- API/Interface Layer: If the node exposes endpoints for metrics, status checks, or external API calls (for monitoring or for integrated services), show these.
- Data Storage / Persistent Layer: Illustrate any databases or on-disk storage systems used for maintaining state, logs, or blockchain data.
- External Services / Integrations: Identify how the node might interact with external blockchain networks or services (e.g., external chains for cross-chain liquidity, price oracles, etc.).
- Security and Consensus Mechanisms: Include components relating to cryptographic validation, digital signatures, and consensus (if applicable, such as Byzantine fault tolerance) to show how reliability and trust are maintained.

##### Detail the Relationships and Interactions
– How incoming transactions go from the API layer to the core node logic.
– How the node interacts with peer nodes via the network module.
– How the consensus component validates blocks/transactions.
– How information is persisted into storage.
- If applicable, indicate recurring loops (e.g., periodic status updates or heartbeat messages between nodes) that reinforce the node’s operational state within the network.

##### Architectural Patterns and Design Principles
- Microservice or Modular Design: Even if all functionality runs within a single binary, conceptually separate the components (network, core logic, storage, external integration) to clarify responsibilities.
- Decentralization: Emphasize the P2P network’s role and how trust is distributed among the nodes.
- Scalability & Resilience: Optionally note any aspects of the design that aid in horizontal scaling or fault tolerance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Documentation Node
    Documentation["Documentation / Project Overview"]:::docStyle

    %% Thornode Core Subsystem
    subgraph "Thornode Node"
        direction TB
        Core["Core Node Logic<br/>(Tx Processing, Block Validation, Consensus)"]:::coreStyle
        Network["Network Communication Module<br/>(P2P Networking)"]:::networkStyle
        API["API/Interface Layer<br/>(Metrics & Status Endpoints)"]:::apiStyle
        Storage["Data Storage / Persistence"]:::storageStyle
        External["External Services / Integrations<br/>(Cross-chain, Oracles)"]:::externalStyle
        Security["Security & Consensus Mechanisms<br/>(Crypto, Digital Signatures)"]:::securityStyle
    end

    %% Connections between Documentation and Thornode
    Documentation ---|"Provides overview"| Core

    %% Internal Data Flow
    API -->|"transactions"| Core
    Network -->|"peer-communications"| Core
    Core -->|"persist_data"| Storage
    Core -->|"validate_blocks"| Security
    Security -->|"consensus_feedback"| Core
    Core -->|"cross_chain_ops"| External

    %% Additional Interaction: External interactions via Network
    Network ---|"external_P2P"| External

    %% Click Events
    click Documentation "https://github.com/thorchain/thornode/blob/master/README.md"

    %% Styles
    classDef coreStyle fill:#ffcccc,stroke:#ff0000,stroke-width:2px;
    classDef networkStyle fill:#ccffcc,stroke:#008000,stroke-width:2px;
    classDef apiStyle fill:#ccccff,stroke:#0000ff,stroke-width:2px;
    classDef storageStyle fill:#ffffcc,stroke:#aaaa00,stroke-width:2px;
    classDef externalStyle fill:#d0e6f7,stroke:#007acc,stroke-width:2px;
    classDef securityStyle fill:#fbe4d5,stroke:#ff4500,stroke-width:2px;
    classDef docStyle fill:#e6e6e6,stroke:#666666,stroke-width:2px;
```
