# farcasterxyz/snapchain architecture

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

## Overview

##### Main Components

a) Core System Components:
- Consensus Engine (/src/consensus)
- Network Layer (/src/network)
- Storage System (/src/storage)
- Mempool (/src/mempool)
- Core Business Logic (/src/core)
- External Connectors (/src/connectors)

b) Data Flow Components:
- Protocol Buffers Interface (/src/proto)
- RPC Services
- Admin Interface
- Blockchain Events Integration

**┌─ External Interface Layer ─────────────────────┐**
- Admin Server                                 │
- gRPC Interface                              │
- Protocol Buffers                            │
- Network Layer ──────────────────────────────┐ │
- P2P Gossip Protocol                        │ │
- RPC Extensions                             │ │
- Server Implementation                      │ │
- Core Processing Layer ────────────────────┐ │ │
- Consensus Engine                        │ │ │
- Message Validation                      │ │ │
- Mempool Management                      │ │ │
- Storage Layer ─────────────────────────┐ │ │ │
- RocksDB Backend                      │ │ │ │
- Merkle Trie Implementation           │ │ │ │
- Block Store                          │ │ │ │
- Account Store                        │ │ │ │
- ┘

##### Key Relationships to Highlight

- Bidirectional communication between Network Layer and External Interface
- Data flow from Network Layer through Consensus to Storage
- Demonstrate how the Mempool interacts with both Consensus and Network layers
- Integration with blockchain events through connectors

##### Implementation Details

- RocksDB as the underlying database
- Protocol Buffers for serialization
- gRPC for API communication
- Merkle trie for state management
- P2P gossip protocol for network communication

##### Specific Elements

**□ Rectangles: Core services**
**○ Circles: External interfaces**
**◇ Diamonds: Decision points**
**⬡ Hexagons: Storage components**

**→ Synchronous calls**
**⇢ Asynchronous communication**
**⇄ Bidirectional data flow**

##### Additional Notes

- A clear indication of the 10,000 TPS throughput target
- How the system scales horizontally
- Configuration management points
- Test coverage points

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef external fill:#A0D8EF
    classDef network fill:#87CEEB
    classDef core fill:#90EE90
    classDef storage fill:#FFD700
    classDef consensus fill:#DDA0DD
    classDef monitoring fill:#D3D3D3

    subgraph ExternalLayer["External Interface Layer"]
        AdminServer["Admin Server"]
        GRPC["gRPC Interface"]
        Proto["Protocol Buffers"]
    end

    subgraph NetworkLayer["Network Layer"]
        P2P["P2P Gossip Protocol"]
        RPC["RPC Extensions"]
        Server["Server Implementation"]
    end

    subgraph CoreLayer["Core Processing Layer"]
        ConsensusEngine["Consensus Engine"]
        Validation["Message Validation"]
        Mempool["Mempool Management"]
    end

    subgraph StorageLayer["Storage Layer"]
        RocksDB["RocksDB Backend"]
        MerkleTrie["Merkle Trie"]
        BlockStore["Block Store"]
        AccountStore["Account Store"]
    end

    subgraph Monitoring["Monitoring & Integration"]
        Metrics["Metrics Collection"]
        BlockchainEvents["Blockchain Events"]
        PerfTest["Performance Testing"]
    end

    %% Connections
    AdminServer --> Server
    GRPC --> Server
    Proto --> GRPC
    
    P2P --> ConsensusEngine
    RPC --> ConsensusEngine
    Server --> P2P
    
    ConsensusEngine --> Mempool
    ConsensusEngine --> Validation
    Mempool --> RocksDB
    
    Validation --> BlockStore
    Validation --> AccountStore
    
    BlockStore --> RocksDB
    AccountStore --> RocksDB
    MerkleTrie --> RocksDB
    
    BlockchainEvents --> ConsensusEngine
    Metrics --> Server
    Metrics --> ConsensusEngine
    PerfTest --> Server

    %% Styles
    class AdminServer,GRPC,Proto external
    class P2P,RPC,Server network
    class ConsensusEngine,Validation,Mempool core
    class RocksDB,MerkleTrie,BlockStore,AccountStore storage
    class Metrics,BlockchainEvents,PerfTest monitoring

    %% Click events
    click AdminServer "https://github.com/farcasterxyz/snapchain/blob/main/src/network/admin_server.rs"
    click RPC "https://github.com/farcasterxyz/snapchain/blob/main/src/network/rpc_extensions.rs"
    click P2P "https://github.com/farcasterxyz/snapchain/blob/main/src/network/gossip.rs"
    click ConsensusEngine "https://github.com/farcasterxyz/snapchain/tree/main/src/consensus/"
    click Mempool "https://github.com/farcasterxyz/snapchain/tree/main/src/mempool/"
    click Validation "https://github.com/farcasterxyz/snapchain/blob/main/src/core/validations.rs"
    click RocksDB "https://github.com/farcasterxyz/snapchain/blob/main/src/storage/db/rocksdb.rs"
    click MerkleTrie "https://github.com/farcasterxyz/snapchain/blob/main/src/storage/trie/merkle_trie.rs"
    click BlockStore "https://github.com/farcasterxyz/snapchain/blob/main/src/storage/store/block.rs"
    click AccountStore "https://github.com/farcasterxyz/snapchain/tree/main/src/storage/store/account/"
    click Proto "https://github.com/farcasterxyz/snapchain/tree/main/src/proto/"
    click BlockchainEvents "https://github.com/farcasterxyz/snapchain/tree/main/src/connectors/onchain_events/"
    click PerfTest "https://github.com/farcasterxyz/snapchain/tree/main/src/perf/"
    click Metrics "https://github.com/farcasterxyz/snapchain/blob/main/src/utils/statsd_wrapper.rs"
```
