# hiero-ledger/hiero-block-node architecture

> Architecture diagram of the GitHub repository hiero-ledger/hiero-block-node, 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/hiero-ledger/hiero-block-node
- Repository: https://github.com/hiero-ledger/hiero-block-node

## Overview

- server – the main block node implementation (core service and API exposure)
- simulator – a local test environment to simulate block stream data
- common – a shared module for utilities, constants, and common types
- suites – e2e tests for verifying functionality
- tools – command line utilities for managing and processing block stream files

##### Main Components
a. Block Node Server:
– Contains the core application (e.g., BlockNodeApp, Server, configuration modules).
– Handles block consumption, stream mediation, persistence, verification, and health monitoring.
b. Simulator:
– A separate module to mimic block stream input.
– Interfaces with the server for testing and simulation.
c. Common Utilities:
– Contains shared classes (e.g., hashing utilities, file utilities, constants) that support both the server and simulator.
d. Messaging & Communication:
– Modules and packages related to messaging (consumer/producer and notifiers) which coordinate block notifications and events.
e. Persistence & Storage:
– Responsible for archiving blocks, reading and writing blocks (e.g., local file persistence, compression, storage path resolution).
f. Verification:
– Handles block and signature verification.
g. Operational & Deployment Artifacts:
– Dockerfiles, Helm charts, and configuration files that indicate containerized deployment.
h. Test Suites & Tools:
– Automated tests (suites) and command line tools (tools) for working with block stream files.

##### Mapping the Relationships
a. Data Flow:
– Blocks are received from external block stream sources (or simulated by the Simulator module).
– The Server module consumes these streams, processes block data, routes them through the verification, persistence, and notification components.
– The Messaging submodule likely facilitates asynchronous communication between producers/consumers.
b. Internal Interactions:
– The configuration and logging modules initialize and monitor the system.
– Persistence components work together to store block data reliably.
– Notifiers and metrics modules expose operational insights.
– Verification components check block integrity before further processing.
c. External & Deployment Layers:
– Docker and Helm charts indicate that the system is containerized.
– APIs exposed by the server connect to external clients or other microservices within the Hiero ecosystem.

##### Architectural Patterns & Design Principles
a. Modular Design:
– Each module (server, simulator, common, etc.) is clearly separated for distinct responsibilities.
b. Dependency Injection:
– Multiple “InjectionModule” files suggest use of dependency injection for flexible module configuration.
c. Layered Architecture:
– There’s a clear separation between core processing (block handling, persistence, verification), configuration/logging, and external interfaces (APIs, Docker deployments).
d. Testing:
– The suites folder contains thorough end-to-end and integration tests, reinforcing a design focused on resiliency.

##### Technologies, Frameworks, and Tools
a. Java 21 as the main programming language.
b. Gradle for project build and dependency management.
c. Docker and Helm charts for container orchestration and deployment.
d. gRPC (as seen in the “grpc” directories) for service communication.
e. Libraries that handle streaming, file compression and storage (e.g., ZstdCompression, NoOp implementations for different storage strategies).

##### Additional Elements to Emphasize
c. If possible, add annotations for important design decisions (like dependency injection or the separation between synchronous and asynchronous processing).

## Diagram (Mermaid)

```mermaid
flowchart TD
    ext["External Block Stream"]:::support
    sim["Simulator"]:::support
    comm["Common Utilities"]:::support

    subgraph "Block Node Server"
        SERVER["Server Core"]:::core
        BC["Block Consumption"]:::core
        VER["Verification"]:::core
        PER["Persistence & Storage"]:::core
        MSG["Messaging & Notification"]:::core
        HM["Health Monitoring & Metrics"]:::core

        SERVER -->|"init"| BC
        BC -->|"verify"| VER
        VER -->|"store"| PER
        PER -->|"notify"| MSG
        MSG -->|"report"| HM
    end

    ext -->|"ingest"| BC
    sim -->|"simulate"| BC
    comm -->|"shared"| SERVER
    comm -->|"shared"| sim

    subgraph "Operational & Deployment Artifacts"
        docker["Docker Deployment"]:::deploy
        helm["Helm Charts"]:::deploy
    end

    docker -->|"deploys"| SERVER
    helm -->|"deploys"| SERVER

    e2e["E2E Test Suites"]:::support
    tools["Command Line Tools"]:::support

    e2e -->|"tests"| SERVER
    tools -->|"manage"| SERVER

    click SERVER "https://github.com/hiero-ledger/hiero-block-node/tree/main/block-node/server"
    click sim "https://github.com/hiero-ledger/hiero-block-node/tree/main/simulator"
    click comm "https://github.com/hiero-ledger/hiero-block-node/tree/main/common"
    click MSG "https://github.com/hiero-ledger/hiero-block-node/tree/main/block-node/messaging"
    click PER "https://github.com/hiero-ledger/hiero-block-node/tree/main/block-node/base/src/main/java/org/hiero/block/server/persistence"
    click VER "https://github.com/hiero-ledger/hiero-block-node/tree/main/block-node/base/src/main/java/org/hiero/block/server/verification"
    click docker "https://github.com/hiero-ledger/hiero-block-node/tree/main/block-node/server/docker"
    click helm "https://github.com/hiero-ledger/hiero-block-node/tree/main/charts"
    click e2e "https://github.com/hiero-ledger/hiero-block-node/tree/main/suites"
    click tools "https://github.com/hiero-ledger/hiero-block-node/tree/main/tools"

    classDef core fill:#dae8fc,stroke:#6c8ebf,stroke-width:2px;
    classDef support fill:#daf7a6,stroke:#a3d55d,stroke-width:2px;
    classDef deploy fill:#f9d4b4,stroke:#e98d59,stroke-width:2px;
```
