# purplei2p/i2pd architecture

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

- Interactive diagram: https://gitdiagram.com/purplei2p/i2pd
- Repository: https://github.com/purplei2p/i2pd

## Overview

##### Main Components
a. Daemon Component:
– Contains modules like HTTPServer, I2PControl, UPnP handling (found under the daemon/ folder).
– Manages the overall service lifecycle and network interactions.
b. Core Library (libi2pd):
– Implements the heart of I2P's functionality.
– Handles configuration, cryptography, network protocols (I2NP, NTCP2, SSU2), tunnel management, routing (e.g., RouterContext, RouterInfo, NetDb), and more.
c. Client Library (libi2pd_client):
– Provides APIs for client-facing interactions (e.g., BOB, SAM, SOCKS, I2PTunnel).
– Interfaces with the daemon or core library to set up sessions or tunnels.
d. Additional Components:
– Build and deployment scripts (Makefile, CMakeLists, workflows, etc.) and packaging tools.
– Documentation and internationalization files, which are support elements outside the runtime architecture.

##### Detailing the Core libi2pd Library
a. Classes and Their Roles:
– Base classes and configuration:
- Base.cpp/Base.h for fundamental characteristics.
- Config.cpp/Config.h for reading/parsing configuration files.
– Cryptography:
- Crypto.cpp/Crypto.h and related files (CryptoKey, Ed25519, Elligator) that provide encryption, key management, and signature verification.
– Networking/Protocols:
- I2NPProtocol.cpp/I2NPProtocol.h, which implement the I2P messaging protocol.
- Network-related implementations such as NTCP2 (NTCP2.cpp/NTCP2.h) and SSU2 (SSU2.cpp/SSU2.h, including related session classes like SSU2Session.cpp/SSU2Session.h and SSU2OutOfSession).
– Identity & Routing:
- Identity.cpp/Identity.h and Destination.cpp/Destination.h for representing node identities and destinations.
- Components for distributed hash tables and routing (e.g., KadDHT.cpp/KadDHT.h, RouterContext.cpp/RouterContext.h, RouterInfo.cpp/RouterInfo.h).
– Tunnel Management:
- Tunnel, TunnelConfig, TunnelGateway, TunnelPool, and related classes for managing encrypted tunnels.
– Show that many modules in libi2pd depend on a central configuration or initialization provided by Config.
– The Cryptography classes (Crypto, CryptoKey, Ed25519, Elligator) serve as a foundation for securing communications. Indicate that modules like Identity and RouterInfo leverage these routines.
– Networking classes (I2NPProtocol, NTCP2, SSU2) will interact with the tunnel management classes to send and receive encrypted data.
– Consider grouping these classes by functionality (e.g., Cryptographic layer, Protocol layer, Routing layer, Tunnel management layer).

– For example, the Daemon component passes configuration data to the libi2pd core library.
– The libi2pd library provides network services to both the daemon and the client library.
– External interfaces versus internal modules.
– Lower-level implementations (core library classes) from higher-level orchestration (daemon or client APIs).

## Diagram (Mermaid)

```mermaid
flowchart TD 
    subgraph "Daemon"
        D_HTTPServer["HTTPServer"]:::daemon
        D_I2PControl["I2PControl"]:::daemon
        D_UPnP["UPnP"]:::daemon
        D_UnixDaemon["UnixDaemon/i2pd"]:::daemon
    end

    subgraph "Core Library (libi2pd)"
        subgraph "Configuration & Base"
            CL_Base["Base"]:::core
            CL_Config["Config"]:::core
        end
        subgraph "Cryptography"
            CL_Crypto["Crypto"]:::core
            CL_CryptoKey["CryptoKey"]:::core
            CL_Ed25519["Ed25519"]:::core
            CL_Elligator["Elligator"]:::core
        end
        subgraph "Networking/Protocols"
            CL_I2NP["I2NPProtocol"]:::core
            CL_NTCP2["NTCP2"]:::core
            CL_SSU2["SSU2"]:::core
            CL_SSU2Session["SSU2Session"]:::core
            CL_SSU2OOS["SSU2OutOfSession"]:::core
        end
        subgraph "Identity & Routing"
            CL_Identity["Identity"]:::core
            CL_Destination["Destination"]:::core
            CL_KadDHT["KadDHT"]:::core
            CL_RouterContext["RouterContext"]:::core
            CL_RouterInfo["RouterInfo"]:::core
        end
        subgraph "Tunnel Management"
            CL_Tunnel["Tunnel"]:::core
            CL_TunnelConfig["TunnelConfig"]:::core
            CL_TunnelGateway["TunnelGateway"]:::core
            CL_TunnelPool["TunnelPool"]:::core
        end
    end

    subgraph "Client Library (libi2pd_client)"
        CLIB_BOB["BOB"]:::client
        CLIB_I2CP["I2CP"]:::client
        CLIB_I2PService["I2PService"]:::client
        CLIB_I2PTunnel["I2PTunnel"]:::client
        CLIB_SAM["SAM"]:::client
        CLIB_SOCKS["SOCKS"]:::client
        CLIB_HTTPProxy["HTTPProxy"]:::client
        CLIB_AddressBook["AddressBook"]:::client
        CLIB_UDPTunnel["UDPTunnel"]:::client
        CLIB_MatchedDest["MatchedDestination"]:::client
        CLIB_ClientContext["ClientContext"]:::client
    end

    subgraph "Wrapper API (libi2pd_wrapper)"
        W_API_GO["api.go"]:::wrapper
        W_CAPI["capi.cpp"]:::wrapper
    end

    subgraph "Build & Deployment"
        BUILD_Makefile["Makefile"]:::build
        BUILD_CMake["CMakeLists.txt"]:::build
        BUILD_Docker["Dockerfile"]:::build
    end

    subgraph "Documentation & Internationalization"
        DOC_Readme["README.md"]:::doc
        DOC_Docs["docs/README.md"]:::doc
        DOC_I18n["i18n files"]:::doc
    end

    %% Relationships between Daemon and Core Library
    D_HTTPServer -->|"calls"| CL_Config
    D_I2PControl -->|"calls"| CL_Config
    D_UPnP -->|"initializes"| CL_Config
    D_UnixDaemon -->|"starts"| D_HTTPServer

    %% Core Library internal relationships
    CL_Config -->|"configures"| CL_Base

    CL_Crypto -->|"provides"| CL_CryptoKey
    CL_Crypto -->|"provides"| CL_Ed25519
    CL_Crypto -->|"provides"| CL_Elligator

    CL_Crypto -->|"secures"| CL_I2NP
    CL_Crypto -->|"secures"| CL_Identity
    CL_Crypto -->|"secures"| CL_RouterInfo

    CL_I2NP -->|"communicates_with"| CL_NTCP2
    CL_I2NP -->|"communicates_with"| CL_SSU2
    CL_SSU2 -->|"manages"| CL_SSU2Session
    CL_SSU2 -->|"handles"| CL_SSU2OOS

    CL_I2NP -->|"uses_tunnels"| CL_Tunnel

    CL_Identity -->|"references"| CL_Config
    CL_RouterInfo -->|"references"| CL_Config

    CL_KadDHT -->|"routes_with"| CL_RouterContext
    CL_RouterContext -->|"supports"| CL_RouterInfo

    CL_Tunnel -->|"managed_by"| CL_TunnelConfig
    CL_Tunnel -->|"uses_gateway"| CL_TunnelGateway
    CL_Tunnel -->|"aggregated_in"| CL_TunnelPool

    %% Interactions between main components
    CLIB_BOB ---|"interfaces_with"| CL_Config
    CLIB_I2PService ---|"interfaces_with"| CL_Config
    CLIB_I2CP ---|"uses"| CL_I2NP
    CLIB_I2PTunnel ---|"establishes"| CL_Tunnel
    CLIB_SAM ---|"utilizes"| CL_Identity
    CLIB_SOCKS ---|"utilizes"| CL_Identity

    W_API_GO ---|"wraps"| CL_Config
    W_CAPI ---|"wraps"| CL_I2NP

    D_I2PControl ---|"communicates_with"| CLIB_I2PService

    %% Peripheral relationships
    BUILD_Makefile -.-> D_UnixDaemon
    DOC_Readme -.-> D_I2PControl

    %% Click Events
    click D_HTTPServer "https://github.com/purplei2p/i2pd/blob/openssl/daemon/HTTPServer.cpp"
    click D_I2PControl "https://github.com/purplei2p/i2pd/blob/openssl/daemon/I2PControl.cpp"
    click D_UPnP "https://github.com/purplei2p/i2pd/blob/openssl/daemon/UPnP.cpp"
    click D_UnixDaemon "https://github.com/purplei2p/i2pd/blob/openssl/daemon/UnixDaemon.cpp"

    click CL_Base "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/Base.cpp"
    click CL_Config "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/Config.cpp"
    click CL_Crypto "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/Crypto.cpp"
    click CL_CryptoKey "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/CryptoKey.cpp"
    click CL_Ed25519 "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/Ed25519.cpp"
    click CL_Elligator "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/Elligator.cpp"
    click CL_I2NP "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/I2NPProtocol.cpp"
    click CL_NTCP2 "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/NTCP2.cpp"
    click CL_SSU2 "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/SSU2.cpp"
    click CL_SSU2Session "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/SSU2Session.cpp"
    click CL_SSU2OOS "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/SSU2OutOfSession.cpp"
    click CL_Identity "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/Identity.cpp"
    click CL_Destination "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/Destination.cpp"
    click CL_KadDHT "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/KadDHT.cpp"
    click CL_RouterContext "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/RouterContext.cpp"
    click CL_RouterInfo "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/RouterInfo.cpp"
    click CL_Tunnel "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/Tunnel.cpp"
    click CL_TunnelConfig "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/TunnelConfig.cpp"
    click CL_TunnelGateway "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/TunnelGateway.cpp"
    click CL_TunnelPool "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd/TunnelPool.cpp"

    click CLIB_BOB "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_client/BOB.cpp"
    click CLIB_I2CP "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_client/I2CP.cpp"
    click CLIB_I2PService "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_client/I2PService.cpp"
    click CLIB_I2PTunnel "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_client/I2PTunnel.cpp"
    click CLIB_SAM "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_client/SAM.cpp"
    click CLIB_SOCKS "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_client/SOCKS.cpp"
    click CLIB_HTTPProxy "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_client/HTTPProxy.cpp"
    click CLIB_AddressBook "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_client/AddressBook.cpp"
    click CLIB_UDPTunnel "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_client/UDPTunnel.cpp"
    click CLIB_MatchedDest "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_client/MatchedDestination.cpp"
    click CLIB_ClientContext "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_client/ClientContext.cpp"

    click W_API_GO "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_wrapper/api.go"
    click W_CAPI "https://github.com/purplei2p/i2pd/blob/openssl/libi2pd_wrapper/capi.cpp"

    click BUILD_Makefile "https://github.com/purplei2p/i2pd/tree/openssl/Makefile"
    click BUILD_CMake "https://github.com/purplei2p/i2pd/blob/openssl/build/CMakeLists.txt"
    click BUILD_Docker "https://github.com/purplei2p/i2pd/tree/openssl/contrib/docker/Dockerfile"

    click DOC_Readme "https://github.com/purplei2p/i2pd/blob/openssl/README.md"
    click DOC_Docs "https://github.com/purplei2p/i2pd/blob/openssl/docs/README.md"

    classDef daemon fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef core fill:#D5F5E3,stroke:#145A32,stroke-width:2px;
    classDef client fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef wrapper fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef build fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef doc fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
```
