# ikatson/rqbit architecture

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

- Interactive diagram: https://gitdiagram.com/ikatson/rqbit
- Repository: https://github.com/ikatson/rqbit

## Overview

##### Main Components
- Core Application Binary & Libraries:
- The main binary is located in crates/rqbit, while the primary library code lives in crates/librqbit.
- Complementary libraries provide various core functionalities. For instance, crates/librqbit-core contains torrent utilities (magnet, file info, hash/peer ID generation) and crates/bencode handles Bencode serialization/deserialization.

- Network and Protocol Modules:
- Distributed Hash Table (DHT): Implemented in crates/dht to provide peer discovery and enhance magnet link usage.
- Peer-to-Peer Communication: The peer_binary_protocol crate implements the protocol for interacting with other peers.
- Tracker Communications: The tracker_comms crate deals with both HTTP and UDP tracker interactions.
- UPnP: There are two related crates – crates/upnp for UPnP port forwarding and crates/upnp-serve for the integrated UPnP media server that advertises torrents to LAN devices.
- Cryptographic and Buffer Utilities: Modules such as crates/sha1w (for SHA1 checksumming) and crates/buffers support low-level operations.

- Web and HTTP API Components:
- HTTP API: The API exposes endpoints for torrent control (uploading, starting, pausing, stats, etc.) and in the README you see examples such as /torrents, /dht/stats, and /web/.
- Web UI: Implemented under crates/librqbit/webui; this serves as the frontend for managing torrents.

- Desktop Application:
- A separate desktop directory (with Tauri configuration and Rust backend in desktop/src-tauri) wraps the Web UI for a native desktop experience on platforms like Windows, OSX, and Linux.

##### Relationships and Interactions
- The CLI and API Server (crates/rqbit) is the entry point and orchestrates torrent-related activities by calling functions from the core libraries (librqbit, librqbit-core, bencode, etc.).
- Torrent files, magnet links, and command line arguments flow into the core engine, triggering network communication with peers, trackers, and DHT operations.
- The HTTP API and Web UI interface together: the HTTP server is the backend for both the web interface (served on http://localhost:3030/web/) and the desktop app, which essentially wraps this web layer.
- Specialized network protocols (peer, tracker, UPnP) are loosely coupled to the core downloading logic, with clearly defined responsibilities (e.g., requesting pieces, managing connections, verifying pieces via the SHA1 wrapper).

##### Architectural Patterns and Design Principles
- Modular Design: The project is divided into multiple crates—each handling a specific functionality (bencode, DHT, peer protocol, storage, etc.)—which promotes separation of concerns and maintainability.
- Layered Architecture: At the lowest layer, you have protocol handling and low-level data structures; above that is the core torrent management library; and at the top, you have the CLI/API and UI layers.
- Integration of External Services: UPnP for port forwarding and the media server for streaming to external devices are cleanly integrated as separate services.
- Reuse and Extensibility: The design allows both using rqbit as an application and as a library for further extension.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        user("User Input"):::user
    end

    %% Interface Layer
    subgraph "Interface Layer"
        cli("CLI/API Server"):::interface
        http("HTTP API"):::interface
        web("Web UI"):::interface
        desktop("Desktop App"):::interface
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        core("Core Library"):::core
        torrent("Torrent Utilities"):::core
        bencode("Bencode Serialization/Deserialization"):::core
    end

    %% Utility Modules
    subgraph "Utility Modules"
        sha1("SHA1 Utility"):::utility
        buffers("Buffer Utilities"):::utility
    end

    %% Network Modules
    subgraph "Network Modules"
        dht("DHT Module"):::network
        p2p("Peer-to-Peer Protocol"):::network
        tracker("Tracker Communications"):::network
        upnp("UPnP Port Forwarding"):::network
        upnpServe("UPnP Media Server"):::network
    end

    %% Connections from User to Interfaces
    user -->|"triggers"| cli
    user -->|"triggers"| http
    user -->|"triggers"| desktop

    %% Connections from Interfaces to Core Engine
    cli -->|"calls"| core
    http -->|"calls"| core

    %% Web UI relationship with HTTP API and Desktop
    http -->|"serves"| web
    desktop -->|"wraps"| web

    %% Connections from Core Engine to its components
    core -->|"uses"| torrent
    core -->|"uses"| bencode
    core -->|"calls"| dht
    core -->|"calls"| p2p
    core -->|"calls"| tracker
    core -->|"calls"| upnp
    core -->|"calls"| upnpServe
    core -->|"uses"| sha1
    core -->|"uses"| buffers

    %% Styles
    classDef user fill:#ccf2ff,stroke:#005073,stroke-width:2px;
    classDef interface fill:#c9daf8,stroke:#0b5394,stroke-width:2px;
    classDef core fill:#ffe599,stroke:#bf9000,stroke-width:2px;
    classDef utility fill:#ead1dc,stroke:#9900cc,stroke-width:2px;
    classDef network fill:#d9ead3,stroke:#38761d,stroke-width:2px;

    %% Click Events
    click cli "https://github.com/ikatson/rqbit/blob/main/crates/rqbit/src/main.rs"
    click core "https://github.com/ikatson/rqbit/blob/main/crates/librqbit/src/lib.rs"
    click torrent "https://github.com/ikatson/rqbit/blob/main/crates/librqbit_core/src/lib.rs"
    click bencode "https://github.com/ikatson/rqbit/blob/main/crates/bencode/src/lib.rs"
    click dht "https://github.com/ikatson/rqbit/blob/main/crates/dht/src/lib.rs"
    click p2p "https://github.com/ikatson/rqbit/blob/main/crates/peer_binary_protocol/src/lib.rs"
    click tracker "https://github.com/ikatson/rqbit/blob/main/crates/tracker_comms/src/lib.rs"
    click upnp "https://github.com/ikatson/rqbit/blob/main/crates/upnp/src/lib.rs"
    click upnpServe "https://github.com/ikatson/rqbit/blob/main/crates/upnp-serve/src/lib.rs"
    click sha1 "https://github.com/ikatson/rqbit/blob/main/crates/sha1w/src/lib.rs"
    click buffers "https://github.com/ikatson/rqbit/blob/main/crates/buffers/src/lib.rs"
    click http "https://github.com/ikatson/rqbit/blob/main/crates/librqbit/src/http_api/mod.rs"
    click web "https://github.com/ikatson/rqbit/tree/main/crates/librqbit/webui"
    click desktop "https://github.com/ikatson/rqbit/blob/main/desktop/src-tauri/main.rs"
```
