# erlantzcalvo/torrent-client architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Node.js-based, command-line torrent client implemented from scratch.
- Its goal is educational: illustrate how a BitTorrent peer downloads files by handling .torrent parsing, tracker communication, peer handshakes, messaging, piece/block management, and file I/O.

##### File‐Structure Analysis
- Top-level entry: index.js – orchestrates the end-to-end torrent download.
- bencoding/ – implements the Bencode encoder/decoder for .torrent parsing.
- connection/ – handles tracker announces (announceRequester.js), peer connections (peer.js), and low-level BitTorrent messages (message.js).
- managers/ – download-manager.js drives the download workflow (piece/block scheduling, reassembly, verification).
- structures/ – priorityQueue.js and queue.js support scheduling and block-request ordering.
- torrent/ – pieces.js (piece-level bookkeeping) and torrentInfo.js (metadata, info-hash generation).
- logger/ – simple logging abstraction.
- utils.js and constants.js – share helper functions and protocol constants.

##### README Insights
- Describes six logical stages: parsing, info-hashing, file pre-setup, tracker announce, peer handshake/messaging, piece-by-piece downloading.
- Highlights core technologies: Node.js, TCP sockets, SHA-1, HTTP GET for tracker.

a. Main Components
- CLI/Orchestrator (index.js)
- Bencoder Module (decoder.js, encoder.js)
- Torrent Metadata (torrentInfo.js)
- Tracker Client (announceRequester.js)
- Peer Manager (peer.js + message.js)
- Download Manager (download-manager.js)
- Data Structures (priorityQueue, queue)
- File I/O Layer (fs APIs)
- Logger Utility
- External Services: Tracker (HTTP), Peers (TCP)
b. Relationships & Data Flow
1. CLI → Bencoder: parse .torrent → JSON
2. TorrentInfo → compute info-hash → pass to Tracker Client
3. Tracker Client ↔ Tracker HTTP endpoint: announce request/response → list of peers
4. Peer Manager ↔ each Peer (TCP): handshake → message exchange
5. Download Manager uses Data Structures to schedule block requests → Peer Manager sends Request → receives Piece → verifies SHA-1 → reassembles pieces
6. Download Manager → File I/O: write blocks to disk (resume support on restart)
7. Logger: cross-cutting, logs events in all modules
c. Architectural Patterns & Principles
- Modular layering: parsing, networking, scheduling, persistence
- Producer-consumer queues for block requests
- Single responsibility per module
- Event-driven asynchronous I/O
d. Key Technologies & Libraries
- Node.js built-in net (TCP) and http modules
- Crypto (SHA-1)
- Bencode algorithm implemented in bencoding/
- Native fs for file writes and resume logic

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    Tracker["Tracker HTTP"]:::external
    Peers["Peers (TCP)"]:::external

    %% Metadata & Parsing Layer
    subgraph "Metadata & Parsing"
        CLI["CLI/Orchestrator"]:::internal
        BencoderDecoder["Bencoder Decoder"]:::internal
        BencoderEncoder["Bencoder Encoder"]:::internal
        BencoderIndex["Bencoder Index"]:::internal
        TorrentInfo["Torrent Metadata"]:::internal
        Pieces["Piece Bookkeeping"]:::internal
    end

    %% Networking & Protocol Layer
    subgraph "Networking & Protocol"
        TrackerClient["Tracker Client"]:::internal
        PeerManager["Peer Manager"]:::internal
        MessageHandler["Message Handler"]:::internal
    end

    %% Scheduling & State Management Layer
    subgraph "Scheduling & State Management"
        DownloadManager["Download Manager"]:::internal
        PriorityQueue["Priority Queue"]:::datastruct
        FIFOQueue["FIFO Queue"]:::datastruct
    end

    %% Persistence & I/O Layer
    subgraph "Persistence & I/O"
        FileIO["File I/O (fs APIs)"]:::internal
    end

    %% Shared Utilities & Constants
    Constants["Protocol Constants"]:::internal
    Utils["Shared Utilities"]:::internal

    %% Logger
    Logger["Logger Utility"]:::internal

    %% Data Flows
    CLI -->|"parse .torrent"| BencoderDecoder
    BencoderDecoder --> BencoderIndex
    BencoderEncoder --> BencoderIndex
    BencoderIndex -->|"parsed metadata"| TorrentInfo
    TorrentInfo -->|"compute info-hash"| TrackerClient

    TrackerClient -->|"announce request"| Tracker
    Tracker -->|"announce response (peers list)"| TrackerClient
    TrackerClient -->|"peers list"| PeerManager

    PeerManager -->|"handshake"| Peers
    Peers -->|"handshake response"| PeerManager
    PeerManager --> MessageHandler
    MessageHandler --> PeerManager

    DownloadManager --> PriorityQueue
    DownloadManager --> FIFOQueue
    DownloadManager -->|"request piece"| PeerManager
    PeerManager -->|"piece data"| DownloadManager
    DownloadManager -->|"verify SHA-1"| Utils
    DownloadManager --> FileIO

    %% Resume logic (read before write)
    FileIO -->|"read for resume"| DownloadManager

    %% Cross-cutting Utilities
    CLI --> Logger
    BencoderDecoder --> Logger
    BencoderEncoder --> Logger
    BencoderIndex --> Logger
    TorrentInfo --> Logger
    TrackerClient --> Logger
    PeerManager --> Logger
    MessageHandler --> Logger
    DownloadManager --> Logger
    FileIO --> Logger
    Utils --> Logger
    Constants --> Logger

    %% Click Events
    click CLI "https://github.com/erlantzcalvo/torrent-client/blob/main/index.js"
    click BencoderDecoder "https://github.com/erlantzcalvo/torrent-client/blob/main/bencoding/decoder.js"
    click BencoderEncoder "https://github.com/erlantzcalvo/torrent-client/blob/main/bencoding/encoder.js"
    click BencoderIndex "https://github.com/erlantzcalvo/torrent-client/blob/main/bencoding/index.js"
    click TorrentInfo "https://github.com/erlantzcalvo/torrent-client/blob/main/torrent/torrentInfo.js"
    click Pieces "https://github.com/erlantzcalvo/torrent-client/blob/main/torrent/pieces.js"
    click TrackerClient "https://github.com/erlantzcalvo/torrent-client/blob/main/connection/announceRequester.js"
    click PeerManager "https://github.com/erlantzcalvo/torrent-client/blob/main/connection/peer.js"
    click MessageHandler "https://github.com/erlantzcalvo/torrent-client/blob/main/connection/message.js"
    click DownloadManager "https://github.com/erlantzcalvo/torrent-client/blob/main/managers/download-manager.js"
    click PriorityQueue "https://github.com/erlantzcalvo/torrent-client/blob/main/structures/priorityQueue.js"
    click FIFOQueue "https://github.com/erlantzcalvo/torrent-client/blob/main/structures/queue.js"
    click Logger "https://github.com/erlantzcalvo/torrent-client/blob/main/logger/logger.js"
    click Constants "https://github.com/erlantzcalvo/torrent-client/blob/main/constants.js"
    click Utils "https://github.com/erlantzcalvo/torrent-client/blob/main/utils.js"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef external fill:#A9DFBF,stroke:#196F3D,color:#1B2631;
    classDef datastruct fill:#F9E79F,stroke:#B7950B,color:#1B2631;
```
