# libp2p/js-libp2p architecture

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

- Interactive diagram: https://gitdiagram.com/libp2p/js-libp2p
- Repository: https://github.com/libp2p/js-libp2p

## Overview

##### Major system components
- Core Networking Stack: At the center is the main “libp2p” package, which acts as the orchestration layer tying together all the modules.
- Interface Definitions: There are dedicated packages (like “packages/interface”, “packages/interface-internal”) that define and enforce the contracts between components.
- Secure Channels / Connection Encryption: Modules such as the plaintext encrypter and the Noise protocol (among others in the “secure channels” category) are implemented to secure the communications.
- Stream Multiplexers: Packages like “stream-multiplexer-mplex” indicate support for multiplexing multiple streams over a single connection.
- Peer Discovery: Several packages (for example, “peer-discovery-bootstrap”, “peer-discovery-mdns”, and even delegated routing components) are used to find peers on the network.
- Routing and DHT: The “kad-dht” package and associated peer routing components handle distributed hash table operations and routing.
- Data Structures and Utilities: Modules like “crypto”, “peer-id”, “peer-record”, “peer-store”, “keychain”, and “utils” are focused on handling keys, identities, and other low-level data operations.
- Additional Functionalities: There are also implementations of protocols (e.g., “protocol-echo”, “protocol-perf”) and pubsub systems (“pubsub” and “pubsub-floodsub”) that provide higher-level networking patterns over the basic connectivity.

##### Determining their relationships and interactions
- Security: Place secure channel components adjacent to the transport components, showing that the underlying connection gets upgraded for encryption.
- PubSub and other protocols: Display these as higher-level protocol layers that rely on the underlying transport and encryption modules.
- Additionally, many packages (like logger, metrics, and configuration) are cross-cutting concerns that can be depicted as support components interfacing with most parts of the system.

##### Highlighting important architectural patterns and design principles
- Modularity and Pluggability: Emphasize that the design uses dependency injection and clean interfaces (by providing “interface” packages) so that every component (transport, encryption, multiplexing, discovery, routing) can be replaced or upgraded without affecting the others.
- Separation of Concerns: Each package is responsible for a single aspect of the networking stack. This clear separation makes it easier to swap individual modules.

##### Including relevant technologies and libraries
- Node.js and Browser: Note that many of these packages are built for both environments (as evidenced by separate implementations like “tls.browser.ts” or “webrtc” adaptations).
- Test and Build Infrastructure: Though not core to the runtime architecture, the presence of CI/CD workflows and test packages indicate robust automated testing and compliance verification.

##### Final Elements
- Clear labels for each main component (e.g., “Libp2p Core”, “Transport – TCP”, “Secure Channel – Noise”, “Stream Multiplexer – mplex”, “Peer Discovery – mDNS”, “DHT – kad-dht”, “Utility – Peer-Store”, etc.).
- Detail notes on how interface boundaries allow for swapping and upgrading (as seen in the modular architecture).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core and Interfaces
    subgraph "Core and Interfaces"
        LP("Libp2p Core"):::core
        IF1("Interface Definitions (Public)"):::interface
        IF2("Interface Definitions (Internal)"):::interface
    end

    %% Transport Layer
    subgraph "Transport Layer"
        T1("TCP Transport"):::transport
        T2("WebSockets Transport"):::transport
        T3("WebRTC Transport"):::transport
        T4("WebTransport"):::transport
        T5("Circuit Relay"):::transport
        T6("Memory Transport"):::transport
    end

    %% Security Channels
    subgraph "Security Channels"
        SEC1("Plaintext Encrypter"):::security
        SEC2("TLS Encrypter"):::security
    end
    SEC_AGGR("Secure Channel (Aggregator)"):::security

    %% Stream Multiplexer
    subgraph "Stream Multiplexer"
        SMX("Stream Multiplexer (mplex)"):::multiplexer
    end

    %% Peer Discovery
    subgraph "Peer Discovery"
        PD1("Bootstrap Discovery"):::discovery
        PD2("mDNS Discovery"):::discovery
    end

    %% Routing and DHT
    subgraph "Routing and DHT"
        DHT("Kad-DHT & Routing"):::routing
    end

    %% Utilities
    subgraph "Data Structures and Utilities"
        U1("Cryptography"):::utility
        U2("Peer ID"):::utility
        U3("Peer Record"):::utility
        U4("Peer Store"):::utility
        U5("Keychain"):::utility
        U6("General Utilities"):::utility
    end

    %% Additional Protocols
    subgraph "Additional Protocols"
        P1("Protocol Echo"):::protocol
        P2("Protocol Perf"):::protocol
        P3("Protocol DCUTR"):::protocol
        P4("Protocol Fetch"):::protocol
        P5("Protocol Identify"):::protocol
        P6("Protocol Ping"):::protocol
        P7("Protocol AutoNAT"):::protocol
        PS1("PubSub"):::protocol
        PS2("PubSub Floodsub"):::protocol
    end

    %% Cross-Cutting Concerns
    subgraph "Cross–Cutting Concerns"
        CC1("Logger"):::crosscut
        CC2("Metrics (Devtools)"):::crosscut
        CC3("Metrics (OpenTelemetry)"):::crosscut
        CC4("Metrics (Prometheus)"):::crosscut
        CC5("Metrics (Simple)"):::crosscut
    end

    %% Interconnections
    %% Core <-> Interfaces
    LP ---|"usesInterface"| IF1
    LP ---|"usesInterface"| IF2

    %% Transports to Security Aggregator (all transports connect)
    T1 ---|"upgrades"| SEC_AGGR
    T2 ---|"upgrades"| SEC_AGGR
    T3 ---|"upgrades"| SEC_AGGR
    T4 ---|"upgrades"| SEC_AGGR
    T5 ---|"upgrades"| SEC_AGGR
    T6 ---|"upgrades"| SEC_AGGR

    %% Also show security modules contributing to the aggregator
    SEC1 ---|"merges"| SEC_AGGR
    SEC2 ---|"merges"| SEC_AGGR

    %% Security aggregator to Stream Multiplexer to Libp2p Core
    SEC_AGGR ---|"channels"| SMX
    SMX ---|"feeds"| LP

    %% Peer Discovery connections to Libp2p Core and Peer Store
    PD1 ---|"discovers"| LP
    PD2 ---|"discovers"| LP
    PD1 ---|"updates"| U4
    PD2 ---|"updates"| U4

    %% Routing connects to Libp2p Core and updates Peer Store
    DHT ---|"routesTo"| LP
    DHT ---|"updates"| U4

    %% Utilities support Libp2p Core
    U1 ---|"supports"| LP
    U2 ---|"supports"| LP
    U3 ---|"supports"| LP
    U4 ---|"supports"| LP
    U5 ---|"supports"| LP
    U6 ---|"supports"| LP

    %% Additional Protocols rely on the Libp2p Core
    P1 ---|"runsOn"| LP
    P2 ---|"runsOn"| LP
    P3 ---|"runsOn"| LP
    P4 ---|"runsOn"| LP
    P5 ---|"runsOn"| LP
    P6 ---|"runsOn"| LP
    P7 ---|"runsOn"| LP
    PS1 ---|"runsOn"| LP
    PS2 ---|"runsOn"| LP

    %% Cross-Cutting Concerns interface with Libp2p Core
    CC1 ---|"logs"| LP
    CC2 ---|"monitors"| LP
    CC3 ---|"monitors"| LP
    CC4 ---|"monitors"| LP
    CC5 ---|"monitors"| LP

    %% Click Events
    click LP "https://github.com/libp2p/js-libp2p/tree/main/packages/libp2p/"
    click IF1 "https://github.com/libp2p/js-libp2p/tree/main/packages/interface/"
    click IF2 "https://github.com/libp2p/js-libp2p/tree/main/packages/interface-internal/"
    click T1 "https://github.com/libp2p/js-libp2p/tree/main/packages/transport-tcp/"
    click T2 "https://github.com/libp2p/js-libp2p/tree/main/packages/transport-websockets/"
    click T3 "https://github.com/libp2p/js-libp2p/tree/main/packages/transport-webrtc/"
    click T4 "https://github.com/libp2p/js-libp2p/tree/main/packages/transport-webtransport/"
    click T5 "https://github.com/libp2p/js-libp2p/tree/main/packages/transport-circuit-relay-v2/"
    click T6 "https://github.com/libp2p/js-libp2p/tree/main/packages/transport-memory/"
    click SEC1 "https://github.com/libp2p/js-libp2p/tree/main/packages/connection-encrypter-plaintext/"
    click SEC2 "https://github.com/libp2p/js-libp2p/tree/main/packages/connection-encrypter-tls/"
    click SMX "https://github.com/libp2p/js-libp2p/tree/main/packages/stream-multiplexer-mplex/"
    click PD1 "https://github.com/libp2p/js-libp2p/tree/main/packages/peer-discovery-bootstrap/"
    click PD2 "https://github.com/libp2p/js-libp2p/tree/main/packages/peer-discovery-mdns/"
    click DHT "https://github.com/libp2p/js-libp2p/tree/main/packages/kad-dht/"
    click U1 "https://github.com/libp2p/js-libp2p/tree/main/packages/crypto/"
    click U2 "https://github.com/libp2p/js-libp2p/tree/main/packages/peer-id/"
    click U3 "https://github.com/libp2p/js-libp2p/tree/main/packages/peer-record/"
    click U4 "https://github.com/libp2p/js-libp2p/tree/main/packages/peer-store/"
    click U5 "https://github.com/libp2p/js-libp2p/tree/main/packages/keychain/"
    click U6 "https://github.com/libp2p/js-libp2p/tree/main/packages/utils/"
    click P1 "https://github.com/libp2p/js-libp2p/tree/main/packages/protocol-echo/"
    click P2 "https://github.com/libp2p/js-libp2p/tree/main/packages/protocol-perf/"
    click P3 "https://github.com/libp2p/js-libp2p/tree/main/packages/protocol-dcutr/"
    click P4 "https://github.com/libp2p/js-libp2p/tree/main/packages/protocol-fetch/"
    click P5 "https://github.com/libp2p/js-libp2p/tree/main/packages/protocol-identify/"
    click P6 "https://github.com/libp2p/js-libp2p/tree/main/packages/protocol-ping/"
    click P7 "https://github.com/libp2p/js-libp2p/tree/main/packages/protocol-autonat/"
    click PS1 "https://github.com/libp2p/js-libp2p/tree/main/packages/pubsub/"
    click PS2 "https://github.com/libp2p/js-libp2p/tree/main/packages/pubsub-floodsub/"
    click CC1 "https://github.com/libp2p/js-libp2p/tree/main/packages/logger/"
    click CC2 "https://github.com/libp2p/js-libp2p/tree/main/packages/metrics-devtools/"
    click CC3 "https://github.com/libp2p/js-libp2p/tree/main/packages/metrics-opentelemetry/"
    click CC4 "https://github.com/libp2p/js-libp2p/tree/main/packages/metrics-prometheus/"
    click CC5 "https://github.com/libp2p/js-libp2p/tree/main/packages/metrics-simple/"

    %% Styles
    classDef core fill:#ffdddd,stroke:#990000,stroke-width:2px;
    classDef interface fill:#ddeeff,stroke:#003399,stroke-width:2px;
    classDef transport fill:#ddffdd,stroke:#006600,stroke-width:2px;
    classDef security fill:#fff0cc,stroke:#cc6600,stroke-width:2px;
    classDef multiplexer fill:#e0ffff,stroke:#008888,stroke-width:2px;
    classDef discovery fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef routing fill:#ffddee,stroke:#990099,stroke-width:2px;
    classDef utility fill:#e6f7ff,stroke:#0055aa,stroke-width:2px;
    classDef protocol fill:#f0e6ff,stroke:#663399,stroke-width:2px;
    classDef crosscut fill:#f2f2f2,stroke:#666666,stroke-width:2px;
```
