# aboutcircles/circles-nethermind-plugin architecture

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

- Interactive diagram: https://gitdiagram.com/aboutcircles/circles-nethermind-plugin
- Repository: https://github.com/aboutcircles/circles-nethermind-plugin

## Overview

##### Core Infrastructure Layer
- Nethermind Client (Host System)
- Lighthouse Consensus Engine
- PostgreSQL Database

##### Plugin Core Components
- BlockIndexer
- StateMachine
- Plugin Manager
Components directly above the infrastructure layer.

##### Protocol Implementation Modules
- CirclesV1 Implementation
- CirclesV2 Implementation
- CirclesV2.NameRegistry
- CirclesV2.StandardTreasury
- CirclesV2.Erc20Lift

##### Common Services Layer
- Query Engine
- RPC Module
- Event Subscription System
- Pathfinder Service

##### Data Flow Components
- Log Parser System
- Event Processing Pipeline
- Database Schema Management
- Insert Buffer

Design Guidelines:

##### Layer Organization
Top to bottom:
1. External Interface Layer (RPC/WebSocket)
2. Service Layer (Query, Pathfinder)
3. Protocol Implementation Layer
4. Core Plugin Layer
5. Infrastructure Layer

Key Interactions to Highlight:

##### Event Flow
- How blockchain events flow from Nethermind through the LogParser
- Event processing pipeline
- Database write operations

##### Query Flow
- Demonstrate RPC request handling
- Query processing through the Query Engine
- Database read operations

##### Subscription System
- WebSocket connection handling
- Real-time event notification flow

##### Protocol Processing
- How different protocol implementations process events
- Schema management and data storage

Additional Elements:

##### Notes
- Configuration requirements
- Critical dependencies
- Performance considerations

##### Version Information
- Protocol version differences
- Compatibility requirements

##### Scale Indicators
- Which components can be scaled
- Performance bottlenecks

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Infrastructure Layer
    subgraph Infrastructure
        NC[Nethermind Client]
        LCE[Lighthouse Consensus Engine]
        DB[(PostgreSQL Database)]:::database
    end

    %% Core Plugin Layer
    subgraph Core
        PM[Plugin Manager]:::core
        BI[Block Indexer]:::core
        SM[State Machine]:::core
    end

    %% Protocol Implementation Layer
    subgraph Protocols
        direction TB
        CV1[CirclesV1]:::protocol
        CV2[CirclesV2]:::protocol
        NR[NameRegistry]:::protocol
        ST[StandardTreasury]:::protocol
        EL[Erc20Lift]:::protocol
    end

    %% Common Services Layer
    subgraph Services
        direction TB
        QE[Query Engine]:::service
        RM[RPC Module]:::service
        ESS[Event Subscription System]:::service
        PS[Pathfinder Service]:::service
    end

    %% Data Flow Components
    subgraph DataFlow
        direction TB
        LP[Log Parser System]:::dataflow
        EPP[Event Processing Pipeline]:::dataflow
        DSM[Database Schema Management]:::dataflow
        IB[Insert Buffer]:::dataflow
    end

    %% Connections
    NC --> LP
    LP --> EPP
    EPP --> IB
    IB --> DB
    DSM --> DB

    PM --> BI
    PM --> SM
    BI --> LP
    SM --> EPP

    CV1 & CV2 & NR & ST & EL --> EPP
    QE --> DB
    RM --> QE
    ESS --> QE
    PS --> QE

    %% Styles
    classDef core fill:#a8d5ff
    classDef protocol fill:#ffb366
    classDef service fill:#d1b3ff
    classDef dataflow fill:#90EE90
    classDef database fill:#f2f2f2

    %% Click Events
    click PM "https://github.com/aboutcircles/circles-nethermind-plugin/blob/dev/Circles.Index/Plugin.cs"
    click BI "https://github.com/aboutcircles/circles-nethermind-plugin/blob/dev/Circles.Index/BlockIndexer.cs"
    click SM "https://github.com/aboutcircles/circles-nethermind-plugin/blob/dev/Circles.Index/StateMachine.cs"
    click CV1 "https://github.com/aboutcircles/circles-nethermind-plugin/tree/dev/Circles.Index.CirclesV1/"
    click CV2 "https://github.com/aboutcircles/circles-nethermind-plugin/tree/dev/Circles.Index.CirclesV2/"
    click NR "https://github.com/aboutcircles/circles-nethermind-plugin/tree/dev/Circles.Index.CirclesV2.NameRegistry/"
    click ST "https://github.com/aboutcircles/circles-nethermind-plugin/tree/dev/Circles.Index.CirclesV2.StandardTreasury/"
    click EL "https://github.com/aboutcircles/circles-nethermind-plugin/tree/dev/Circles.Index.CirclesV2.Erc20Lift/"
    click QE "https://github.com/aboutcircles/circles-nethermind-plugin/tree/dev/Circles.Index.Query/"
    click RM "https://github.com/aboutcircles/circles-nethermind-plugin/blob/dev/Circles.Index.Rpc/CirclesRpcModule.cs"
    click ESS "https://github.com/aboutcircles/circles-nethermind-plugin/blob/dev/Circles.Index.Rpc/CirclesSubscription.cs"
    click PS "https://github.com/aboutcircles/circles-nethermind-plugin/blob/dev/Circles.Pathfinder/V2Pathfinder.cs"
    click LP "https://github.com/aboutcircles/circles-nethermind-plugin/blob/dev/Circles.Index.Common/ILogParser.cs"
    click IB "https://github.com/aboutcircles/circles-nethermind-plugin/blob/dev/Circles.Index.Common/InsertBuffer.cs"
    click DB "https://github.com/aboutcircles/circles-nethermind-plugin/blob/dev/Circles.Index.Postgres/PostgresDb.cs"
    click DSM "https://github.com/aboutcircles/circles-nethermind-plugin/blob/dev/Circles.Index.Common/DatabaseSchema.cs"
```
