# ssvlabs/ssv architecture

> Architecture diagram of the GitHub repository ssvlabs/ssv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ssvlabs/ssv
- Repository: https://github.com/ssvlabs/ssv

## Overview

##### Core System Components
- Network Layer
- P2P Communication (network/p2p)
- Discovery Service (network/discovery)
- Stream Controller (network/streams)
- Protocol Layer (protocol/v2)
- QBFT Consensus
- Message Processing
- Runner Components
- Operator Layer
- Duty Management
- Validator Management
- Key Management
- Blockchain Integration
- Beacon Chain Client
- ETH1 Client
- Contract Interactions

##### External Interfaces
- API Gateway (api/)
- Monitoring/Metrics (monitoring/)
- Boot Nodes
- Beacon Chain
- Ethereum Network

##### Use a Multi-Layer Architecture
**┌─────────────────────────────────────────────────────────┐**
- External Layer                        │
- [Beacon Chain] [ETH Network] [Monitoring] [Boot Nodes] │
- ┤
- Interface Layer                       │
- [API Gateway] [Health Checks] [Metrics]         │
- ┤
- Core Layer                          │
- ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐  │
- Network Stack│ │QBFT Consensus│ │Operator Services │  │
- ┘ └──────────────┘ └──────────────────┘  │
- ┤
- Storage Layer                        │
- [Key Store] [Validator Store] [Message Store]        │
- ┘

- Blue: External services and interfaces
- Green: Core processing components
- Yellow: Storage and persistence
- Red: Critical consensus and validation components

Key Relationships to Show:

- Incoming beacon chain duties → Operator services
- Network messages → QBFT consensus
- Consensus decisions → Validator actions
- Metrics collection paths

##### Component Interactions
- P2P message routing between nodes
- Consensus protocol communication
- Validator duty execution flow
- Storage access patterns

Additional Elements:

##### System Boundaries
- Node instance boundary
- Network boundary
- Trust boundaries
- Consensus group boundaries

Implementation Notes:

##### Use Professional Diagramming Tools
- Lucidchart

##### Maintain Hierarchy
- Related components
- Clear separation of concerns
- Scaling points

##### Technical Details
- Protocol versions
- Key interfaces
- Critical configurations
- Performance monitoring points

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph External["External Layer"]
        BC[Beacon Chain]:::external
        EN[Ethereum Network]:::external
        MON[Monitoring]:::external
        BN[Boot Nodes]:::external
    end

    subgraph Interface["Interface Layer"]
        API[API Gateway]:::interface
        HC[Health Checks]:::interface
        MET[Metrics]:::interface
    end

    subgraph Core["Core Layer"]
        subgraph Network["Network Stack"]
            P2P[P2P Communication]:::network
            DS[Discovery Service]:::network
            SC[Stream Controller]:::network
        end

        subgraph Protocol["Protocol Components"]
            QBFT[QBFT Consensus]:::protocol
            MP[Message Processing]:::protocol
            RC[Runner Components]:::protocol
        end

        subgraph Operator["Operator Services"]
            DM[Duty Management]:::operator
            VM[Validator Management]:::operator
            KM[Key Management]:::operator
            NC[Node Core]:::operator
            IM[Identity Management]:::operator
        end

        subgraph Integration["Blockchain Integration"]
            CI[Contract Interactions]:::blockchain
            EH[Event Handler]:::blockchain
            ES[Event Syncer]:::blockchain
            BCI[Beacon Chain Integration]:::blockchain
            ETH1[ETH1 Integration]:::blockchain
        end
    end

    subgraph Storage["Storage Layer"]
        KS[Key Store]:::storage
        VS[Validator Store]:::storage
        MS[Message Store]:::storage
    end

    %% Relationships
    BC --> BCI
    EN --> ETH1
    API --> NC
    MON --> MET
    BN --> DS

    P2P --> MP
    DS --> P2P
    SC --> P2P

    QBFT --> MP
    MP --> RC
    RC --> DM

    DM --> VM
    VM --> KM
    KM --> KS

    CI --> ETH1
    EH --> ES
    ES --> NC

    NC --> VS
    NC --> MS
    IM --> KS

    %% Click Events
    click P2P "https://github.com/ssvlabs/ssv/blob/main/network/p2p/p2p.go"
    click DS "https://github.com/ssvlabs/ssv/blob/main/network/discovery/dv5_service.go"
    click SC "https://github.com/ssvlabs/ssv/blob/main/network/streams/controller.go"
    click QBFT "https://github.com/ssvlabs/ssv/tree/main/protocol/v2/qbft"
    click MP "https://github.com/ssvlabs/ssv/tree/main/protocol/v2/message"
    click RC "https://github.com/ssvlabs/ssv/tree/main/protocol/v2/ssv/runner"
    click DM "https://github.com/ssvlabs/ssv/tree/main/operator/duties"
    click VM "https://github.com/ssvlabs/ssv/tree/main/operator/validator"
    click KM "https://github.com/ssvlabs/ssv/tree/main/operator/keys"
    click API "https://github.com/ssvlabs/ssv/blob/main/api/server/server.go"
    click MET "https://github.com/ssvlabs/ssv/tree/main/monitoring/metrics"
    click BCI "https://github.com/ssvlabs/ssv/tree/main/beacon/goclient"
    click ETH1 "https://github.com/ssvlabs/ssv/tree/main/eth/executionclient"
    click KS "https://github.com/ssvlabs/ssv/tree/main/operator/keystore"
    click VS "https://github.com/ssvlabs/ssv/blob/main/registry/storage/validatorstore.go"
    click MS "https://github.com/ssvlabs/ssv/tree/main/storage/kv"
    click NC "https://github.com/ssvlabs/ssv/blob/main/operator/node.go"
    click IM "https://github.com/ssvlabs/ssv/blob/main/identity/store.go"
    click CI "https://github.com/ssvlabs/ssv/tree/main/eth/contract"
    click EH "https://github.com/ssvlabs/ssv/tree/main/eth/eventhandler"
    click ES "https://github.com/ssvlabs/ssv/tree/main/eth/eventsyncer"

    %% Styling
    classDef external fill:#68B5E8
    classDef interface fill:#95DAC1
    classDef network fill:#FD6F96
    classDef protocol fill:#FD6E6A
    classDef operator fill:#6EFD9E
    classDef blockchain fill:#B4A0E5
    classDef storage fill:#FFDB58

    %% Legend
    subgraph Legend
        L1[External Services]:::external
        L2[Interface Components]:::interface
        L3[Network Components]:::network
        L4[Protocol Components]:::protocol
        L5[Operator Services]:::operator
        L6[Blockchain Integration]:::blockchain
        L7[Storage Components]:::storage
    end
```
