# reamlabs/ream architecture

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

- Interactive diagram: https://gitdiagram.com/reamlabs/ream
- Repository: https://github.com/reamlabs/ream

## Overview

##### Main Components
- Client Binary: The primary entry point is in the “bin/ream” directory. This contains the CLI and main application logic, which orchestrates the overall system.
- Consensus Module: Located under “crates/common/consensus”, this module implements all consensus logic (e.g., beacon blocks, attestation, fork choice, deposits, slashing, and support for the Deneb fork). It is the core of the Beam Chain specification.
- Execution Engine & Executor: Found under “crates/common/execution_engine” and “crates/common/executor”, these components handle the interaction with the execution payload (including engine traits, mock engine for testing, payload processing, and transaction execution).
- Cryptography: The “crates/crypto/bls” directory contains the BLS signature scheme implementation and supporting libraries. This is critical for validating consensus messages.
- Networking: Both “crates/networking/discv5” and “crates/networking/p2p” encapsulate node discovery, bootnode configuration, and overall P2P networking, ensuring communication between nodes.
- RPC Interface: The “crates/rpc” provides the interface for remote procedure calls, which can be used by external tools or services for querying or controlling the node.
- Runtime: The “crates/runtime” module (with its own README) likely integrates various components to run the chain client in its operational context.
- Testing: The “testing/ef-tests” directory contains integration and end-to-end tests, complete with macros and utilities. Although not part of the deployment architecture, they are essential for validating the system’s behavior.

##### Relationships and Interactions
- The “bin/ream” client acts as the central orchestrator, initializing and wiring together the consensus, execution, networking, and storage components.
- The Consensus module depends on the Cryptography module (for BLS signatures) and the Storage module (for state management), and interacts with the Execution Engine during block processing.
- The Execution Engine and Executor work together to handle payload processing and transaction execution, and they interact with networking components when communicating with other nodes or external systems.
- The Networking modules (discv5 and p2p) work in tandem to facilitate peer discovery, network bootstrapping (using provided bootnodes), and data exchange, which is critical for consensus and state synchronization.
- The RPC Module exposes interfaces that let external clients query the node or trigger certain actions.
- The Runtime layer integrates these pieces ensuring that the overall system logic follows the Beam Chain specification.

##### Architectural Patterns and Design Principles
- Modularization: The project is divided into discrete “crates” that encapsulate specific functionality. This ensures isolation and makes it contributor-friendly.
- Separation of Concerns: Components like consensus, crypto, networking, and storage are decoupled, enabling easier maintenance, testing, and future extensibility.
- Layered Architecture: The design can be seen as layers (networking, consensus & execution, storage, and RPC interfaces) that mirror modern full-stack applications but tailored for blockchain technology.

##### Detailed Elements
- Clear labels for each component/module (e.g., “Client (bin/ream)”, “Consensus (crates/common/consensus)”, “Execution Engine”, “Networking – DiscV5 & P2P”, “Cryptography – BLS”, “Storage”, “RPC Interface”, “Runtime”).

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Binary"
        MAIN["Main (bin/ream/src/main.rs)"]:::client
        CLI["CLI (bin/ream/src/cli)"]:::client
    end

    subgraph "Core Components"
        CONSENSUS["Consensus (crates/common/consensus)"]:::core
        EXECUTION_ENGINE["Execution Engine (crates/common/execution_engine)"]:::core
        EXECUTOR["Executor (crates/common/executor)"]:::core
        CRYPTO["Cryptography - BLS (crates/crypto/bls)"]:::crypto
        STORAGE["Storage (crates/storage)"]:::storage
    end

    subgraph "Networking Modules"
        DISCV5["Discovery (crates/networking/discv5)"]:::network
        P2P["P2P (crates/networking/p2p)"]:::network
    end

    subgraph "External Interfaces"
        RPC["RPC Interface (crates/rpc)"]:::rpc
    end

    subgraph "Operational Layer"
        RUNTIME["Runtime (crates/runtime)"]:::runtime
    end

    subgraph "Testing"
        TESTING["Integration & E2E Testing (testing/ef-tests)"]:::testing
    end

    %% Connections between components
    MAIN -->|"orchestrates"| CONSENSUS
    CONSENSUS -->|"validates_with"| CRYPTO
    CONSENSUS -->|"processes_blocks_via"| EXECUTION_ENGINE
    EXECUTION_ENGINE -->|"executes_transactions"| EXECUTOR
    CONSENSUS -->|"persists_state_to"| STORAGE
    CONSENSUS -->|"broadcasts_to"| P2P
    MAIN -->|"communicates_with"| DISCV5
    MAIN -->|"communicates_with"| P2P
    RPC -->|"triggers_actions_on"| MAIN
    RUNTIME -->|"integrates_with"| MAIN
    RUNTIME -->|"integrates_with"| CONSENSUS
    RUNTIME -->|"integrates_with"| STORAGE
    RUNTIME -->|"integrates_with"| RPC
    TESTING -->|"tests"| MAIN
    TESTING -->|"tests"| CONSENSUS
    TESTING -->|"tests"| STORAGE
    EXECUTION_ENGINE -->|"communicates_with"| P2P
    DISCV5 -->|"feeds_peers_to"| P2P

    %% Click Events
    click MAIN "https://github.com/reamlabs/ream/blob/master/bin/ream/src/main.rs"
    click CLI "https://github.com/reamlabs/ream/tree/master/bin/ream/src/cli"
    click CONSENSUS "https://github.com/reamlabs/ream/tree/master/crates/common/consensus"
    click EXECUTION_ENGINE "https://github.com/reamlabs/ream/tree/master/crates/common/execution_engine"
    click EXECUTOR "https://github.com/reamlabs/ream/tree/master/crates/common/executor"
    click CRYPTO "https://github.com/reamlabs/ream/tree/master/crates/crypto/bls"
    click STORAGE "https://github.com/reamlabs/ream/tree/master/crates/storage"
    click DISCV5 "https://github.com/reamlabs/ream/tree/master/crates/networking/discv5"
    click P2P "https://github.com/reamlabs/ream/tree/master/crates/networking/p2p"
    click RPC "https://github.com/reamlabs/ream/tree/master/crates/rpc"
    click RUNTIME "https://github.com/reamlabs/ream/tree/master/crates/runtime"
    click TESTING "https://github.com/reamlabs/ream/tree/master/testing/ef-tests"

    %% Styles
    classDef client fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef core fill:#a1cbe6,stroke:#333,stroke-width:2px;
    classDef crypto fill:#c2f0c2,stroke:#333,stroke-width:2px;
    classDef storage fill:#f7c6c7,stroke:#333,stroke-width:2px;
    classDef network fill:#d1c4e9,stroke:#333,stroke-width:2px;
    classDef rpc fill:#ffb3ba,stroke:#333,stroke-width:2px;
    classDef runtime fill:#baffc9,stroke:#333,stroke-width:2px;
    classDef testing fill:#fdfd96,stroke:#333,stroke-width:2px;
```
