# 0xsoniclabs/sonic architecture

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

- Interactive diagram: https://gitdiagram.com/0xsoniclabs/sonic
- Repository: https://github.com/0xsoniclabs/sonic

## Overview

The Sonic project is a blockchain node and tool suite for an EVM‐compatible chain secured by the Lachesis consensus algorithm. The repository contains two main executables: the daemon (sonicd) and the tool (sonictool), along with several libraries and components that support networking, consensus, EVM processing, and smart contract execution.

##### And separate major system components
- Daemon (sonicd): This is the primary node application. It is responsible for validating, processing transactions, interacting with the network, and managing state.
- Tool (sonictool): Acts as an auxiliary tool for database initialization, generating configurations (e.g., dumpconfig), genesis creation, validator key management, and other utilities.
- Network and Consensus Layers: Notice extensive directories like “gossip”, “scc”, “evmcore”, “inter”, and “opera”. These modules handle p2p messaging (gossip protocol), consensus (Lachesis-based ordering, validator communication), block processing, and EVM state transitions.
- Configuration and Initialization: The “config” directory holds configuration structures and defaults, while “valkeystore” and “cmd” (specific credential and key components) are used for secure key management and validator operations.
- Supporting Libraries and Tools: There are several utility modules (e.g., “utils”, “logger”, “debug”, “topicsdb”) that assist with logging, debugging, database interaction, and various low-level operations.
- Testing and Integration Suites: Directories such as “tests”, “integration”, and “demo” indicate extensive testing and demo scripts to validate blockchain behavior and consensus.

##### Architectural patterns and design principles
- Modular/Layered Architecture: Separate the execution, consensus, networking, and configuration concerns. For example, the “gossip” layer handles p2p communications independently of the EVM state mutation done in “evmcore”.
- Service Segregation: The separation of responsibilities in sound packages (e.g., “sonicd” vs. “sonictool”) and clearly delineated functionalities in directories like “cmd”, “config”, and “evmcore” demonstrate a clean separation of concerns.
- Pluggable and Extensible Modules: Notice directories like “inter” and “gossip/protocols”, suggesting that Sonic may be designed for extensibility (various consensus or network protocol modules are defined).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User"]:::external

    %% Executables
    sonicd["sonicd (Node Daemon)"]:::executable
    sonictool["sonictool (Tool)"]:::executable

    User --> sonicd
    User --> sonictool

    %% Sonic Node Daemon Components
    subgraph "Sonic Node Daemon Components"
        config["Configuration & Initialization"]:::config
        gossip["Gossip Protocol (Network)"]:::network
        scc["Lachesis/SCC (Consensus)"]:::network
        inter["Inter-module Messaging"]:::network
        evmcore["EVM Execution & State Transitions"]:::evm
        topicsdb["TopicsDB (Database)"]:::db
        dbutil["DB Utilities (utils/dbutil)"]:::db
        valkeystore["Keystore & Validator Key Management"]:::keystore
    end

    sonicd -->|"uses"| config
    sonicd -->|"communicates with"| gossip
    sonicd -->|"communicates with"| scc
    sonicd -->|"communicates with"| inter
    sonicd -->|"triggers"| evmcore
    sonicd -->|"stores data in"| topicsdb
    sonicd -->|"utilizes"| dbutil
    sonicd -->|"secures with"| valkeystore

    %% Sonic Tool Components
    subgraph "Sonic Tool Components"
        configTool["Configuration & Initialization"]:::config
        valkeystoreTool["Keystore & Validator Key Management"]:::keystore
    end

    sonictool -->|"initializes via"| configTool
    sonictool -->|"manages keys using"| valkeystoreTool

    %% Supporting Modules
    subgraph "Supporting Modules"
        logger["Logging Utilities"]:::utility
        debug["Debug Tools"]:::utility
    end

    sonicd ---|"logs/errors"| logger
    sonicd ---|"debugs"| debug
    sonictool ---|"logs/errors"| logger
    sonictool ---|"debugs"| debug

    %% Testing & Integration Suites
    subgraph "Testing & Integration Suites"
        tests["Tests"]:::test
        integration["Integration"]:::test
    end

    sonicd ---|"validated by"| tests
    sonicd ---|"validated by"| integration

    %% Click Events
    click sonicd "https://github.com/0xsoniclabs/sonic/tree/main/cmd/sonicd"
    click sonictool "https://github.com/0xsoniclabs/sonic/tree/main/cmd/sonictool"
    click gossip "https://github.com/0xsoniclabs/sonic/tree/main/gossip"
    click scc "https://github.com/0xsoniclabs/sonic/tree/main/scc"
    click inter "https://github.com/0xsoniclabs/sonic/tree/main/inter"
    click evmcore "https://github.com/0xsoniclabs/sonic/tree/main/evmcore"
    click config "https://github.com/0xsoniclabs/sonic/tree/main/config"
    click configTool "https://github.com/0xsoniclabs/sonic/tree/main/config"
    click valkeystore "https://github.com/0xsoniclabs/sonic/tree/main/valkeystore"
    click valkeystoreTool "https://github.com/0xsoniclabs/sonic/tree/main/valkeystore"
    click topicsdb "https://github.com/0xsoniclabs/sonic/tree/main/topicsdb"
    click dbutil "https://github.com/0xsoniclabs/sonic/tree/main/utils/dbutil"
    click logger "https://github.com/0xsoniclabs/sonic/tree/main/logger"
    click debug "https://github.com/0xsoniclabs/sonic/tree/main/debug"
    click tests "https://github.com/0xsoniclabs/sonic/tree/main/tests"
    click integration "https://github.com/0xsoniclabs/sonic/tree/main/integration"

    %% Styles
    classDef external fill:#ffebcc,stroke:#b58900,stroke-width:2px;
    classDef executable fill:#dcedf9,stroke:#268bd2,stroke-width:2px;
    classDef config fill:#e2f0cb,stroke:#859900,stroke-width:2px;
    classDef network fill:#cce8ff,stroke:#2aa198,stroke-width:2px;
    classDef evm fill:#fdd,stroke:#dc322f,stroke-width:2px;
    classDef db fill:#fff2cc,stroke:#b58900,stroke-width:2px;
    classDef keystore fill:#d0e1f9,stroke:#268bd2,stroke-width:2px;
    classDef utility fill:#eee8d5,stroke:#586e75,stroke-width:2px;
    classDef test fill:#f3e5f5,stroke:#6a51a3,stroke-width:2px;
```
