# ethereumjs/ethereumjs-monorepo architecture

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

## Overview

##### Main Components
– Core execution (e.g. @ethereumjs/vm, @ethereumjs/evm)
– Blockchain and block structure (e.g. @ethereumjs/block, @ethereumjs/blockchain)
– Transaction handling (e.g. @ethereumjs/tx)
– State management and Merkle Patricia Trees (e.g. @ethereumjs/statemanager, @ethereumjs/mpt)
– Data encoding and other utilities (e.g. @ethereumjs/rlp, @ethereumjs/util, @ethereumjs/common)
– Networking and Peer-to-Peer communication (e.g. @ethereumjs/devp2p)
– Genesis initialization (@ethereumjs/genesis)
– Wallet functionalities (@ethereumjs/wallet)
- The EthereumJS client (“@ethereumjs/client”) ties together these libraries to provide a functioning execution client.

##### Relationships and Interactions
– @ethereumjs/common provides chain and protocol parameters that many components (vm, block, statemanager, tx, evm, client, devp2p) use.
– The block and blockchain packages are interconnected and act as the “ledger layer” with links from networking and consensus.
– EVM and VM components are directly tied with the execution of transactions.
– State management and the Merkle Patricia Tree underpin storage concerns that many of these components require.

##### Architectural Patterns
- Modularity and the “building block” approach where each package has a well-defined responsibility.
- Layered architecture where lower-level primitives (data encoding, common settings, basic cryptographic or state operations) support higher-level components (blocks, client, EVM).
- That dependency injection and clear interface boundaries are key design principles here.
- The monorepo structure itself suggests a design based upon composability—the different packages integrate to form a complete execution client.

##### Relevant Technologies and Frameworks
- That some packages also have front-end components (e.g. parts of the VM that can run in a browser) although most are server/Node.js based.
- Extensive test and CI/build arrangement (with configurations, Dockerfile, and GitHub workflows) which emphasizes automation and quality.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Data/Primitives"
        Common["@ethereumjs/common"]:::primitives
        Util["@ethereumjs/util"]:::primitives
        RLP["@ethereumjs/rlp"]:::primitives
    end

    subgraph "Chain Structures"
        Block["@ethereumjs/block"]:::chain
        Blockchain["@ethereumjs/blockchain"]:::chain
        Tx["@ethereumjs/tx"]:::chain
        Genesis["@ethereumjs/genesis"]:::chain
    end

    subgraph "Execution"
        VM["@ethereumjs/vm"]:::execution
        EVM["@ethereumjs/evm"]:::execution
    end

    subgraph "State Management"
        StateManager["@ethereumjs/statemanager"]:::state
        MPT["@ethereumjs/mpt"]:::state
    end

    subgraph "Networking"
        devp2p["@ethereumjs/devp2p"]:::network
    end

    subgraph "Wallet"
        Wallet["@ethereumjs/wallet"]:::wallet
    end

    Client["@ethereumjs/client"]:::client

    %% Data/Primitives Relationships
    Util -->|"supports"| Common
    RLP -->|"encodes"| Common

    %% Common as a core dependency for many components
    Common -->|"chainParams"| Block
    Common -->|"chainParams"| Blockchain
    Common -->|"chainParams"| StateManager
    Common -->|"chainParams"| Tx
    Common -->|"chainParams"| EVM
    Common -->|"chainParams"| devp2p
    Common -->|"chainParams"| Client

    %% Chain Structures interconnections
    Genesis -->|"init"| Blockchain
    Block <-->|"ledger"| Blockchain
    Tx -->|"executes"| EVM

    %% Execution connections
    Block -->|"feeds"| VM

    %% State Management connection
    StateManager -->|"manages"| MPT

    %% High-level Client integration
    Block -->|"contributes"| Client
    Blockchain -->|"ledgers"| Client
    VM -->|"executes"| Client
    EVM -->|"executes"| Client
    StateManager -->|"state"| Client
    devp2p -->|"networking"| Client
    Wallet -->|"provides"| Client

    %% Click Events
    click VM "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/vm"
    click EVM "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/evm"
    click Block "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/block"
    click Blockchain "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/blockchain"
    click Tx "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/tx"
    click StateManager "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/statemanager"
    click MPT "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/mpt"
    click RLP "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/rlp"
    click Util "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/util"
    click Common "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/common"
    click devp2p "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/devp2p"
    click Genesis "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/genesis"
    click Wallet "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/wallet"
    click Client "https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/client"

    %% Styles
    classDef primitives fill:#D5E8D4,stroke:#82B366,stroke-width:2px;
    classDef chain fill:#FFF2CC,stroke:#D6B656,stroke-width:2px;
    classDef execution fill:#DAE8FC,stroke:#6C8EBF,stroke-width:2px;
    classDef state fill:#F8CECC,stroke:#B85450,stroke-width:2px;
    classDef network fill:#E1D5E7,stroke:#9673A6,stroke-width:2px;
    classDef wallet fill:#FFE6CC,stroke:#D79B00,stroke-width:2px;
    classDef client fill:#D5D5D5,stroke:#666,stroke-width:2px;
```
