# ergoplatform/ergo architecture

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

- Interactive diagram: https://gitdiagram.com/ergoplatform/ergo
- Repository: https://github.com/ergoplatform/ergo

## Overview

##### Main Components
- Node Core & Consensus: Represent the central “ergo-core” module that implements network communication, block propagation, consensus algorithms (including Autolykos2 as the memory-hard PoW), block validation, and synchronization. Include components like the NodeViewSynchronizer, network peer management, and block/message processing.
- State Management & Persistence: Include the persistent authenticated AVL+ tree implementation (from the “avldb” module) along with LDB (LevelDB) stores used to manage the UTXO set and blockchain history.
- HTTP API & User Interface: Capture the API routes and HTTP services (e.g., BlockchainApiRoute, WalletApiRoute, SwaggerRoute, etc.) exposed by the node. This component connects the back-end blockchain logic with front-end panels (UI files in resources/panel).
- Configuration & Bootstrapping: Note components for node bootstrapping (e.g., options to load UTXO snapshots, use of NiPoPoW for headers sync, and stateless modes) that are configured via the provided configuration files.

##### Relationships and Data Flow
- The Node Core communicates bidirectionally with the P2P network to exchange blocks and transactions.
- Incoming blocks are processed by the consensus layer, which then updates the UTXO state using the persistent AVL+ tree from the avldb module.
- The Wallet module interacts with the blockchain state (via the node view) to sign, verify, and broadcast transactions.
- HTTP API components provide external access to blockchain data and wallet functionalities; they serve both RESTful endpoints and Swagger documentation.
- The configuration files (under src/main/resources and CI scripts) and Dockerfiles are used in deployment to initialize, configure, and run the node.

##### Architectural Patterns and Design Principles
- Modular Design: The separation between “avldb”, “ergo-core”, and “ergo-wallet” illustrates a design focused on modularity so that only the components required for a given deployment are used.
- Separation of Concerns: Networking, consensus, state management, and wallet functionalities are separated into different modules with dedicated responsibilities.
- Event-Driven / Reactive Components: Many components (e.g., NodeViewSynchronizer, message serializations, network handlers) are implemented to work asynchronously within an actor-model framework (likely with frameworks like Akka).
- Extensibility: The repository’s structure (with CI/CD, multiple configuration files, and numerous tests) supports continuous deployment, integration, and contributes to maintainability.

##### Detail Technologies, Frameworks, and Libraries
- Primary Language & Build Tool: Scala with sbt for building the project.
- Persistence: Use of LevelDB (embedded via LDBKVStore and related classes) for managing versioned data structures.
- Cryptography & Consensus: Custom implementations of Autolykos2 (memory-hard PoW) and cryptographic libraries used in the scorex and ergo-core modules.
- Networking: P2P messaging and Web API components built on HTTP libraries (and likely Akka HTTP).
- Testing and CI/CD: Use of Travis, GitHub workflows, and Docker to validate builds and run integration tests.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Configuration & Bootstrapping"
        Config["Configuration Files\n(application.conf, devnet.conf, mainnet.conf, node1, node2, nodeTestnet)"]:::config
    end

    subgraph "Core Modules"
        ErgoCore["Ergo-Core & Consensus\n(NodeViewSynchronizer, Autolykos2, block/message processing)"]:::core
        State["State Management & Persistence\n(Authenticated AVL+ Tree, LevelDB Stores)"]:::storage
    end

    subgraph "Application Modules"
        Wallet["Wallet & Transaction Handling\n(Signing, Verification, TX Building)"]:::wallet
        HTTPAPI["HTTP API Layer\n(BlockchainApiRoute, WalletApiRoute, SwaggerRoute)"]:::api
        UI["User Interface Panel\n(static resources: index.html, JS, CSS)"]:::ui
    end

    Config -->|"Bootstraps"| ErgoCore
    ErgoCore -->|"UpdatesUTXOstate"| State
    Wallet -->|"SendsTransactions"| ErgoCore
    ErgoCore -->|"NotifiesWallet"| Wallet
    HTTPAPI -->|"FetchesBlockchainData"| ErgoCore
    HTTPAPI -->|"ExecutesWalletOps"| Wallet
    UI -->|"SendsUserRequests"| HTTPAPI

    click Config "https://github.com/ergoplatform/ergo/tree/master/src/main/resources"
    click ErgoCore "https://github.com/ergoplatform/ergo/tree/master/ergo-core/src/main/scala/org/ergoplatform"
    click State "https://github.com/ergoplatform/ergo/blob/master/avldb/src/main/scala/scorex/crypto/authds/avltree/batch/VersionedLDBAVLStorage.scala"
    click Wallet "https://github.com/ergoplatform/ergo/tree/master/ergo-wallet/src/main/scala/org/ergoplatform/wallet"
    click HTTPAPI "https://github.com/ergoplatform/ergo/tree/master/ergo-core/src/main/scala/org/ergoplatform/http/api"
    click UI "https://github.com/ergoplatform/ergo/tree/master/src/main/resources/panel"

    classDef core fill:#a2d9ce,stroke:#1abc9c,stroke-width:2px;
    classDef storage fill:#a9cce3,stroke:#3498db,stroke-width:2px;
    classDef wallet fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
    classDef api fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
    classDef ui fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef config fill:#d5dbdb,stroke:#95a5a6,stroke-width:2px;
```
