# vxdxk/vdk-torrent-client architecture

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

- Interactive diagram: https://gitdiagram.com/vxdxk/vdk-torrent-client
- Repository: https://github.com/vxdxk/vdk-torrent-client

## Overview

##### Project type and purpose
- This is a standalone, command‐line BitTorrent client written in Rust from scratch.
- It consists of two crates:
– **bencode**: A library for encoding/decoding data in the Bencode format.
– **torrent-client**: The application crate with modules to parse CLI arguments, interact with trackers, manage peers, orchestrate downloads/uploads, and write data to disk.

##### File structure
Top‐level
- .github/workflows/* – CI workflows (not part of runtime)
- Cargo.toml / Cargo.lock – workspace and dependency configuration
- README.md – high‐level description
bencode/
- src/lib.rs – core Bencode encode/decode functionality (parsing dictionaries, lists, integers, byte strings)
torrent-client/
- src/main.rs – entry point: parse CLI, initialize the client
- src/cli/ – argument parsing (torrent file path, download directory, options)
- src/client/ – core orchestration logic (spawning workers, managing download state)
- src/tracker/ – HTTP/UDP tracker protocol client, contact tracker, parse peer list
- src/peer/ – peer connection management, handshake, piece message exchange
- src/file/ – piece/block storage, disk IO, reassembly, integrity checks
- src/util/ – shared helpers (bitfield handling, timing, logging)

##### Available documentation
- The README simply states “torrent client written from scratch.”

##### Core components
a. **CLI Interface**
– Parses user input (torrent .torrent file, destination path, options)
– Triggers the client orchestration
b. **Torrent Client Orchestrator**
– Coordinates between tracker module and peer module
– Maintains global download state, piece availability, retry logic
c. **Tracker Module**
– Opens HTTP/UDP connection to tracker URLs from the .torrent metadata
– Sends “announce” requests, parses Bencoded responses (list of peers)
– Uses the **bencode** library
d. **Peer Module**
– Manages TCP connections to peers returned by trackers
– Handles handshake, bitfield exchange, message pipeline (request, piece, keep-alive)
– May spawn worker threads/tasks for each peer
e. **File Module**
– Writes/reads raw blocks to disk (piece management)
– On piece completion, verifies SHA-1 hash from .torrent metadata
f. **Bencode Library (bencode crate)**
– Shared by tracker (response parsing) and possibly for reading .torrent files
g. **Utility Module**
– Common utilities (bitfield operations, timeouts, logging)

##### Relationships and interactions
- User ➔ CLI
- CLI ➔ Orchestrator
- Orchestrator ➔ Tracker Module ➔ Network (Tracker Servers)
- Tracker Module ➔ Bencode Library ➔ Parsed Peer List ➔ Orchestrator
- Orchestrator ➔ Peer Module ➔ Network (Peer TCP connections)
- Peer Module ⇄ File Module (read/write blocks)
- File Module ➔ Orchestrator (piece completion events)

##### Architectural patterns and design principles
- Modularization by responsibility (CLI, orchestration, tracker, peer, file, util)
- Separation of concerns: encoding/decoding in its own crate (bencode)
- Asynchronous or multi‑threaded worker model for peers (concurrency)
- Pluggable I/O and network abstractions (could replace TCP with any async transport)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External user
    User(["User"]):::external

    %% bencode crate
    subgraph "bencode crate"
        BE(["Bencode Library\n(lib.rs)"]):::crate
    end

    %% torrent-client crate
    subgraph "torrent-client crate"
        Main(["Application Entry Point\n(main.rs)"]):::module
        subgraph "Modules"
            CLI(["CLI Interface\n(mod.rs)"]):::module
            Orchestrator(["Orchestrator\n(client/mod.rs)"]):::module
            Worker(["Worker\n(client/worker.rs)"]):::module
            Tracker(["Tracker Module\n(tracker/mod.rs)"]):::module
            PeerMgr(["Peer Module\n(peer/mod.rs)"]):::module
            PeerConn(["Peer Connection\n(connection.rs)"]):::module
            FileMod(["File Module\n(mod.rs)"]):::module
            Util(["Utility Module\n(mod.rs)"]):::module
        end
    end

    %% External systems
    TrackerServers(["Tracker Servers"]):::external
    PeerNetwork(["Peer Network"]):::external

    %% Connections
    User -->|"cli input"| CLI
    CLI -->|"initializes"| Main
    Main -->|"parse args"| CLI
    CLI -->|"start orchestrator"| Orchestrator

    Orchestrator -->|"announce"| Tracker
    Tracker -->|"Bencode parse"| BE
    Tracker -->|"peer list"| Orchestrator
    Tracker -->|"HTTP/UDP announce"| TrackerServers

    Orchestrator -->|"spawn peer tasks"| Worker
    Worker -->|"manage peers"| PeerMgr
    PeerMgr -->|"spawn connection"| PeerConn
    PeerConn -->|"TCP handshake & messages"| PeerNetwork

    PeerMgr -->|"read/write blocks"| FileMod
    FileMod -->|"piece complete events"| Orchestrator

    %% Utility usage
    Util -.-> Tracker
    Util -.-> PeerMgr
    Util -.-> FileMod
    Util -.-> Orchestrator

    %% Click events
    click CLI "https://github.com/vxdxk/vdk-torrent-client/blob/master/torrent-client/src/cli/mod.rs"
    click Orchestrator "https://github.com/vxdxk/vdk-torrent-client/blob/master/torrent-client/src/client/mod.rs"
    click Worker "https://github.com/vxdxk/vdk-torrent-client/blob/master/torrent-client/src/client/worker.rs"
    click Tracker "https://github.com/vxdxk/vdk-torrent-client/blob/master/torrent-client/src/tracker/mod.rs"
    click PeerMgr "https://github.com/vxdxk/vdk-torrent-client/blob/master/torrent-client/src/peer/mod.rs"
    click PeerConn "https://github.com/vxdxk/vdk-torrent-client/blob/master/torrent-client/src/peer/connection.rs"
    click FileMod "https://github.com/vxdxk/vdk-torrent-client/blob/master/torrent-client/src/file/mod.rs"
    click BE "https://github.com/vxdxk/vdk-torrent-client/blob/master/bencode/src/lib.rs"
    click Util "https://github.com/vxdxk/vdk-torrent-client/blob/master/torrent-client/src/util/mod.rs"
    click Main "https://github.com/vxdxk/vdk-torrent-client/blob/master/torrent-client/src/main.rs"

    %% Styles
    classDef crate fill:#D6EAF8,stroke:#21618C,color:#1B4F72;
    classDef module fill:#D5F5E3,stroke:#196F3D,color:#145A32;
    classDef external fill:#FADBD8,stroke:#C0392B,color:#7B241C;
```
