# limechain/fruzhin architecture

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

## Overview

##### Main Components
- Node & Bootstrap: At the entry point is Main.java that initializes and wires the node services.
- Chain Manager: Packages under “com.limechain.chain” and “com.limechain/chain/spec” contain the logic for chain specs, genesis configuration (including reading from the genesis folder), and maintaining chain state.
- Consensus Engines: Multiple consensus modules exist:
– The “consensus/babe” package for block production and slot coordination.
– “consensus/grandpa” handling finality proofs.
– “consensus/beefy” for additional finality and vote aggregation.
- Networking: Several layers of network protocols are implemented (look under “network”, “network/protocol”, and “network/kad”). These handle peer discovery, connection management, message encoding/decoding, block announcement, syncing, and light client message protocols.
- Sync Module: The “sync” packages provide both full sync and warp sync mechanisms. These interact with the chain state and network to update the node with new blocks.
- RPC & PubSub: Under “rpc” packages, you find both the server and client implementations to support public API methods (chain, state, system, offchain, and author endpoints) and subscribe to updates.
- Runtime and Host API: “runtime” packages implement the WASM runtime, its memory management, host APIs, and version handling. This is key for executing runtime logic and smart contract-like operations.
- Storage & Trie: The “storage” and “trie” packages handle block storage, state persistence, and efficient lookup via trie data structures.
- CLI and Configuration: The “cli” package offers a command-line interface, while the “config” packages load system settings and host configurations.
- Monitoring and Utilities: Integration with “prometheus” supports metrics, and there are many utility and exception packages for managing errors, encoding/decoding, scales, and asynchronous tasks.

##### Establish Relationships and Interactions
- The Main Node component creates a NodeService that wires together:
- Chain Manager – for processing and validating block headers and chain specification files.
- Consensus engines (Babe, Grandpa, Beefy) that manage consensus state and block finalization.
- Sync module that drives block execution and synchronization with the peer network.
- Networking protocols interface with the Consensus and Sync modules to receive new blocks, disseminate messages (block announcements, votes, sync requests), and maintain peer connections.
- The RPC subsystem exposes data from the Chain Manager, Consensus state, and Storage layer so that external clients (or the node operator via CLI) can query the system.
- The Runtime subsystem, with its host API modules, interacts with the Storage layer and State management to execute WASM code.
- Storage/Trie components are used throughout the system to persist chain and state data, maintaining a consistent view required by syncing and runtime evaluations.
- Monitoring via Prometheus gathers metrics across node components.

##### Architectural Patterns and Technical Stack
- Modular design: Each functional area (chain, consensus, network, runtime, storage) is clearly separated into its own package.
- Layered architecture: Low-level storage/trie components feed into higher-level chain and runtime modules.
- Service orchestration: The NodeService coordinates startup and lifecycle management of consensus engines, network, and RPC components.
- Exception handling and asynchronous programming: The extensive exception and async utility packages indicate attention to reliability and concurrent processing.
- Use of Gradle builds, Docker deployment (with a provided Dockerfile), and extensive testing under “src/test” further support modern development practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Node Initialization (Main & NodeService)"]:::node
    I["CLI & Config"]:::cli
    B["Chain Manager"]:::chain
    C1["Babe Engine"]:::consensus
    C2["Grandpa Engine"]:::consensus
    C3["Beefy Engine"]:::consensus
    D["Sync Module"]:::sync
    E["Networking"]:::network
    F["RPC & PubSub"]:::rpc
    G["Runtime & Host API"]:::runtime
    H["Storage & Trie"]:::storage
    J["Monitoring"]:::monitoring
    K["Utilities & Exception Handling"]:::util

    %% Node Initialization and CLI
    I -->|"configures"| A

    %% Wiring core services from Node Initialization
    A -->|"initializes"| B
    A -->|"initializes"| C1
    A -->|"initializes"| C2
    A -->|"initializes"| C3
    A -->|"initializes"| D

    %% Networking interactions with consensus and sync
    E -->|"communicates"| C1
    E -->|"communicates"| C2
    E -->|"communicates"| C3
    E -->|"communicates"| D

    %% Chain Manager and Consensus updating Storage
    B -->|"writes to"| H
    C1 -->|"updates"| H
    C2 -->|"updates"| H
    C3 -->|"updates"| H
    D -->|"syncs with"| H

    %% RPC querying core modules
    F -->|"queries"| B
    F -->|"queries"| C1
    F -->|"queries"| C2
    F -->|"queries"| C3
    F -->|"queries"| H

    %% Runtime reads from Storage
    G -->|"reads from"| H

    %% Monitoring collects metrics from key modules
    J -->|"monitors"| A
    J -->|"monitors"| D

    %% Common dependency on Utilities
    A ---|"uses"| K
    B ---|"uses"| K
    C1 ---|"uses"| K
    C2 ---|"uses"| K
    C3 ---|"uses"| K
    D ---|"uses"| K
    E ---|"uses"| K
    F ---|"uses"| K
    G ---|"uses"| K
    H ---|"uses"| K
    I ---|"uses"| K
    J ---|"uses"| K

    %% Class Definitions for Colors
    classDef node fill:#ccf,stroke:#333,stroke-width:2px;
    classDef cli fill:#cce,stroke:#333,stroke-width:2px;
    classDef chain fill:#cfc,stroke:#333,stroke-width:2px;
    classDef consensus fill:#fcf,stroke:#333,stroke-width:2px;
    classDef sync fill:#cff,stroke:#333,stroke-width:2px;
    classDef network fill:#ffc,stroke:#333,stroke-width:2px;
    classDef rpc fill:#fcc,stroke:#333,stroke-width:2px;
    classDef runtime fill:#fc9,stroke:#333,stroke-width:2px;
    classDef storage fill:#9cf,stroke:#333,stroke-width:2px;
    classDef monitoring fill:#f9c,stroke:#333,stroke-width:2px;
    classDef util fill:#eee,stroke:#333,stroke-width:2px;

    %% Click Events
    click A "https://github.com/limechain/fruzhin/blob/dev/src/main/java/com/limechain/Main.java"
    click A "https://github.com/limechain/fruzhin/blob/dev/src/main/java/com/limechain/NodeService.java"
    click B "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/chain"
    click B "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/chain/spec"
    click C1 "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/consensus/babe"
    click C2 "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/consensus/grandpa"
    click C3 "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/consensus/beefy"
    click D "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/sync"
    click D "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/sync/fullsync"
    click D "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/sync/warpsync"
    click E "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/network"
    click E "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/network/protocol"
    click E "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/network/kad"
    click F "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/rpc"
    click F "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/rpc/methods"
    click F "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/rpc/pubsub"
    click F "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/rpc/server"
    click F "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/rpc/subscriptions"
    click G "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/runtime/hostapi"
    click H "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/storage"
    click H "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/trie"
    click I "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/cli"
    click I "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/config"
    click J "https://github.com/limechain/fruzhin/blob/dev/src/main/java/com/limechain/prometheus/PrometheusServer.java"
    click K "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/utils"
    click K "https://github.com/limechain/fruzhin/tree/dev/src/main/java/com/limechain/exception"
```
