# Superseedr Architecture
## Overview
Superseedr is a high-performance, asynchronous BitTorrent client featuring a terminal user interface (TUI). It is built using **Rust** and **Tokio**, employing an Actor-like concurrency model to manage high-throughput networking and disk I/O without blocking the UI thread.
## High-Level Design
The application is divided into three distinct layers:
1. **Presentation Layer (`App` & `TUI`):** Handles user input, rendering, and state aggregation.
2. **Orchestration Layer (`TorrentManager`):** Manages the logic for individual torrents (peer selection, piece picking, state mutation).
3. **Network/IO Layer (`PeerSession` & Storage):** Handles raw TCP communication, BitTorrent protocol parsing, and disk operations.
## Core Components
### 1. The Application Loop (`src/app.rs` & `src/main.rs`)
The `App` struct is the central owner of the application state. It does not handle heavy lifting (downloading/hashing); instead, it acts as a controller and visualizer.
* **Responsibility:**
* Initializes the `ResourceManager` and `TcpListener`.
* Spawns `TorrentManager` tasks for each torrent.
* Aggregates metrics via a `broadcast` channel (`metrics_tx`/`rx`) to update the UI.
* Handles User Input (keyboard events) and mutates `AppState`.
* **State Management:**
* `AppState`: Contains display-optimized data (sparkline history, peer lists, throughput graphs).
* `Settings`: Configurable constraints (limits, paths).
### 2. The TUI (`src/tui.rs`)
The UI is built using `Ratatui`. It is stateless regarding logic; it simply renders the current snapshot of `AppState`.
* **Key Features:**
* **Sparklines:** Visualizes download/upload history.
* **Heatmaps:** Renders swarm availability.
* **Throttling:** Redraws are capped (e.g., 30 FPS or 60 FPS) to save CPU.
### 3. Torrent Manager (`src/torrent_manager/manager.rs`)
This is the "Brain" of a specific torrent. Each torrent runs as an isolated Tokio task (Actor).
* **Architecture Pattern: Action/Effect:**
Instead of mutating state ad-hoc, the manager uses a functional reactive pattern.
1. **Event:** An event arrives (e.g., `IncomingBlock`, `PeerConnected`).
2. **Action:** The event is converted into an `Action` enum.
3. **Update:** The `TorrentState` processes the `Action` and returns a list of **Effects** (e.g., `WriteToDisk`, `SendToPeer`).
4. **Side Effect:** The manager executes the effects asynchronously.
* **Responsibility:**
* Manages the `PieceManager` (Bitfield logic).
* Tracks all connected peers (`PeerState`).
* Handles file validation and hash checking.
* Interfaces with the DHT and Trackers.
### 4. Peer Session (`src/networking/session.rs`)
Represents a single TCP connection to a peer. It implements the BitTorrent Wire Protocol.
* **Concurrency:**
* Splits the TCP stream into a **Reader Task** and a **Writer Task**.
* **Reader Task:** Parsers raw bytes into `Message` enums and sends them to the session loop.
* **Writer Task:** Batches outgoing messages and flushes them to the TCP socket to reduce syscall overhead.
* **Congestion Control:**
* Implements a dynamic sliding window ("Adaptive Pipelining") to optimize request throughput based on peer latency.
* Uses a `Semaphore` to limit "blocks in flight".
### 5. Resource Management
* **`ResourceManager` (`src/resource_manager.rs`):** A centralized gatekeeper that limits the number of open file descriptors and active sockets (semaphores) to prevent OS resource exhaustion (e.g., `ulimit`).
* **`TokenBucket` (`src/token_bucket.rs`):** Implements global bandwidth rate limiting for downloads and uploads.
## Data Flow: Downloading a Block
The flow of data from the network to the disk demonstrates the interaction between layers:
1. **Network**: `PeerSession` Reader Task receives bytes from TCP.
2. **Protocol**: Bytes are parsed into a `Message::Piece`.
3. **Validation**: `PeerSession` verifies the block was actually requested.
4. **Command**: `PeerSession` sends `TorrentCommand::Block` to `TorrentManager`.
5. **State Update**: `TorrentManager` calculates the `Action::IncomingBlock`.
6. **Effect**: The State generates an `Effect::WriteToDisk`.
7. **IO**: `TorrentManager` acquires a write permit from `ResourceManager` and spawns a blocking task to write data to storage.
8. **Completion**: Upon success, an event is sent back to mark the piece as received.
## Concurrency Model
Superseedr relies heavily on Tokio's message-passing primitives:
* **mpsc (Multi-Producer, Single-Consumer):**
* `PeerSession` -> `TorrentManager` (Reporting data/events).
* `TorrentManager` -> `PeerSession` (Sending requests/chokes).
* `App` -> `TorrentManager` (User commands like Pause/Delete).
* **broadcast (Multi-Producer, Multi-Consumer):**
* `TorrentManager` -> `App` (Broadcasting metrics for the UI).
* `App` -> All Components (Global Shutdown signal).
* **oneshot:**
* Used for handling internal errors between Reader/Writer tasks.
## Code Map
| `src/main.rs` | CLI parsing, logging setup, panic hooks, main loop entry. |
| `src/app.rs` | Global state container, input handling, metrics aggregation. |
| `src/tui.rs` | Rendering logic using Ratatui widgets. |
| `src/torrent_manager/manager.rs` | The Actor managing a specific torrent's lifecycle. |
| `src/networking/session.rs` | TCP connection handling and BitTorrent protocol parsing. |
| `src/networking/protocol.rs` | Binary serialization/deserialization of Wire Protocol messages. |