# libp2p/universal-connectivity architecture

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

## Overview

- js‑peer: A browser chat peer built with Next.js and TypeScript, containing a rich UI built from React components.
- go‑peer: A Go‑based chat peer offering native binary support.
- rust‑peer: A chat peer written in Rust that also provides command‑line interactivity (with Docker support).

##### Main components
- Peer Types: Represent the three separate implementations (js‑peer, go‑peer, rust‑peer). Each is a chat peer participating in the same decentralized network.
- Underlying Networking Layer: All peers use libp2p for establishing connectivity via various transport protocols (WebTransport, WebRTC (and WebRTC‑direct), QUIC, TCP). Additionally, the GossipSub protocol is used for decentralized PubSub messaging.
- User Interface: The js‑peer package includes extensive frontend components (React components for chat, alerts, lists, etc.) running on Next.js.
- Auxiliary Components: Highlight support files such as Dockerfiles, configuration files (e.g. Docker-compose if applicable, CI workflows from GitHub Actions), and build scripts that indicate deployment environments.

##### Relationships and Interactions
- UI to Peer Process: In the js‑peer branch, indicate how the Next.js frontend interacts with its underlying peer communication functionality via calls to libp2p libraries.
- Cross‑Technology Interoperability: Although written in different languages, all peers share a similar protocol stack. Emphasize the uniformity provided by libp2p and the GossipSub protocol; note how these protocols abstract over differences in underlying language implementations.

##### Architectural Patterns and Design Principles
- Modular & Pluggable Components: Each language implementation is self‑contained with its own dependencies and runtime environment. The shared use of libp2p means that the architecture follows a plug‑and‑play model for peer connectivity.

##### Relevant Technologies
- js‑peer: Next.js, React, Node.js, TypeScript, Tailwind CSS.
- go‑peer: Go (with its built‑in support for concurrency), Docker for containerization.
- rust‑peer: Rust, Cargo for dependency management.
- Under the hood: libp2p for peer connectivity and GossipSub for message brokering across a decentralized network.
- CI/CD pipelines: GitHub workflows for various language builds (notice references to build‑go-peer-docker.yaml, go‑ci.yml, rust‑ci.yml, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U["User"]:::auxiliary

    %% JS Peer Subgraph
    subgraph "JS Peer (Next.js/TypeScript)"
        A["UI Components (Next.js/React)"]:::jsPeer
        B["Next.js Pages"]:::jsPeer
        C["Libp2p Integration"]:::jsPeer
    end

    %% Go Peer Subgraph
    subgraph "Go Peer (Go-Based Native Binary)"
        D["Core Chat Functionality"]:::goPeer
        E["Docker Support"]:::goPeer
    end

    %% Rust Peer Subgraph
    subgraph "Rust Peer (Rust-Based CLI)"
        F["Core Chat & Protocols"]:::rustPeer
        G["Docker Support"]:::rustPeer
    end

    %% Libp2p Network Layer Subgraph
    subgraph "Libp2p Network Layer"
        H["libp2p & GossipSub (Connectivity & PubSub)"]:::network
        I["Transport Protocols: WebTransport,WebRTC,QUIC,TCP"]:::network
    end

    %% Auxiliary Components Subgraph
    subgraph "Auxiliary Components"
        J["CI/CD Workflows"]:::auxiliary
        K["Project Configs"]:::auxiliary
    end

    %% Connections from User to JS Peer UI
    U -->|"initiates"| A
    U -->|"navigates"| B

    %% Connections within JS Peer
    A -->|"sendsMessage"| C
    B -->|"loadsPage"| C

    %% Peer connectivity to Libp2p Network Layer
    C -->|"connectsTo"| H
    D -->|"joinsNetwork"| H
    F -->|"joinsNetwork"| H

    %% Network propagation back to peers
    H -->|"propagatesTo"| C
    H -->|"propagatesTo"| D
    H -->|"propagatesTo"| F

    %% CI/CD influence on peers (indicative)
    J -->|"triggersBuild"| D
    J -->|"triggersBuild"| F

    %% Click Events for Component Mappings
    click A "https://github.com/libp2p/universal-connectivity/tree/main/js-peer/src/components"
    click B "https://github.com/libp2p/universal-connectivity/tree/main/js-peer/src/pages"
    click C "https://github.com/libp2p/universal-connectivity/blob/main/js-peer/src/lib/libp2p.ts"
    click D "https://github.com/libp2p/universal-connectivity/blob/main/go-peer/main.go"
    click E "https://github.com/libp2p/universal-connectivity/tree/main/go-peer/Dockerfile"
    click F "https://github.com/libp2p/universal-connectivity/blob/main/rust-peer/src/main.rs"
    click G "https://github.com/libp2p/universal-connectivity/tree/main/rust-peer/Dockerfile"
    click J "https://github.com/libp2p/universal-connectivity/tree/main/.github/workflows"
    click K "https://github.com/libp2p/universal-connectivity/blob/main/README.md"

    %% Directory Click Events
    click A "https://github.com/libp2p/universal-connectivity/tree/main/js-peer"
    click D "https://github.com/libp2p/universal-connectivity/tree/main/go-peer"
    click F "https://github.com/libp2p/universal-connectivity/tree/main/rust-peer"

    %% Styling Definitions
    classDef jsPeer fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef goPeer fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef rustPeer fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef network fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
