# max-niederman/centipede architecture

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

- Interactive diagram: https://gitdiagram.com/max-niederman/centipede
- Repository: https://github.com/max-niederman/centipede

## Overview

##### Main Components

a) Core Components:
- Control Plane
- Handshake Management
- Peer Authentication (Ed25519)
- Address Management/Heartbeat System
- Data Plane
- Packet Processing
- Encryption/Decryption (ChaCha20Poly1305)
- Packet Deduplication
- Worker System
- Thread-per-core Architecture
- TUN Queue Management
- UDP Socket Management

b) Package Structure (based on the file tree):
- centipede_api: API interfaces
- centipede_control: Control plane logic
- centipede_proto: Protocol definitions
- centipede_router: Routing and packet management
- centipede_worker: Worker thread implementation
- centipeded: Main daemon

##### Key Relationships to Highlight

- Bidirectional flows between peers
- Packet flow from TUN devices through the processing pipeline
- Demonstrate the worker thread architecture
- Relationship between control and data planes

##### Specific Elements

a) External Interfaces:
- Multiple UDP socket interfaces
- TUN device interfaces
- API interface (planned HTTP)

b) Processing Components:
- Packet encryption/decryption modules
- Deduplication system
- Routing logic
- Worker thread pool

c) Control Components:
- Handshake manager
- Peer authentication
- Address management
- Heartbeat system

##### Important Architectural Aspects to Emphasize

- Lock-free shared state implementation
- Thread-per-core architecture
- Multiple UDP socket sets per worker
- Packet deduplication mechanism
- Stateless user interface design
- NAT traversal capabilities

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Interfaces
    subgraph Network
        TUN[TUN Devices]:::interface
        UDP[UDP Sockets]:::interface
        API[API Interface]:::interface
    end

    %% Control Plane Layer
    subgraph ControlPlane
        CP[Control Plane]:::control
        HS[Handshake Manager]:::control
        AUTH[Authentication System]:::control
        AM[Address Management]:::control
        HB[Heartbeat System]:::control
    end

    %% Data Plane Layer
    subgraph DataPlane
        PP[Packet Processing]:::processing
        ED[Encryption/Decryption]:::security
        PD[Packet Deduplication]:::processing
        PROTO[Protocol Definitions]:::processing
        PMM[Packet Memory Management]:::processing
    end

    %% Worker System
    subgraph WorkerSystem
        WP[Worker Pool]:::worker
        TQ[TUN Queue Management]:::worker
        SM[Socket Management]:::worker
        WT[Worker Thread Implementation]:::worker
    end

    %% Configuration and Main Components
    CONF[Configuration System]:::config
    MAIN[Main Daemon]:::main
    ROUTE[Routing & Packet Management]:::routing

    %% Relationships
    TUN --> WP
    UDP --> SM
    API --> CP
    
    CP --> HS
    CP --> AUTH
    CP --> AM
    CP --> HB
    
    WP --> TQ
    WP --> SM
    WP --> WT
    
    MAIN --> CP
    MAIN --> WP
    MAIN --> CONF
    
    PP --> ED
    PP --> PD
    PP --> PROTO
    PP --> PMM
    
    ROUTE --> PP
    WP --> ROUTE

    %% Click Events
    click CP "https://github.com/max-niederman/centipede/blob/main/packages/centipede_control/src/lib.rs"
    click AUTH "https://github.com/max-niederman/centipede/blob/main/packages/centipede_proto/src/marker/auth.rs"
    click PROTO "https://github.com/max-niederman/centipede/blob/main/packages/centipede_proto/src/lib.rs"
    click PP "https://github.com/max-niederman/centipede/blob/main/packages/centipede_proto/src/packet.rs"
    click WP "https://github.com/max-niederman/centipede/blob/main/packages/centipede_worker/src/lib.rs"
    click SM "https://github.com/max-niederman/centipede/blob/main/packages/centipede_worker/src/sockets.rs"
    click ROUTE "https://github.com/max-niederman/centipede/blob/main/packages/centipede_router/src/lib.rs"
    click PMM "https://github.com/max-niederman/centipede/blob/main/packages/centipede_router/src/packet_memory.rs"
    click CONF "https://github.com/max-niederman/centipede/blob/main/packages/centipede_router/src/config.rs"
    click API "https://github.com/max-niederman/centipede/blob/main/packages/centipede_api/src/lib.rs"
    click MAIN "https://github.com/max-niederman/centipede/blob/main/packages/centipeded/src/main.rs"
    click WT "https://github.com/max-niederman/centipede/blob/main/packages/centipede_router/src/worker.rs"

    %% Styles
    classDef interface fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef control fill:#FFD700,stroke:#333,stroke-width:2px
    classDef processing fill:#90EE90,stroke:#333,stroke-width:2px
    classDef security fill:#FF6B6B,stroke:#333,stroke-width:2px
    classDef worker fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef config fill:#F0E68C,stroke:#333,stroke-width:2px
    classDef main fill:#20B2AA,stroke:#333,stroke-width:2px
    classDef routing fill:#FFA07A,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        L1[Interface]:::interface
        L2[Control]:::control
        L3[Processing]:::processing
        L4[Security]:::security
        L5[Worker]:::worker
        L6[Config]:::config
        L7[Main]:::main
        L8[Routing]:::routing
    end
```
