# kamui-fin/dream architecture

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

- Interactive diagram: https://gitdiagram.com/kamui-fin/dream
- Repository: https://github.com/kamui-fin/dream

## Overview

##### Main Components
- DHT Service (Dream DHT): This corresponds to the dream-dht binary and is implemented under the src/dht directory (modules like compact.rs, context.rs, kademlia.rs, etc.). Its main role is to serve as a decentralized tracker for peer discovery.
- BitTorrent Engine (Dream Torrent): Implemented largely within src/bittorrent.rs, src/tracker.rs, and supported through peer management modules (src/peer/manager.rs, session.rs, stats.rs). This component handles the downloading/uploading of video segments between peers.
- HTTP Streaming Server: A component within the dream-torrent service that provides HTTP streaming to video players, ensuring on-demand video playback.
- Command-Line Interface (dream-cli): Located in src/bin/cli.rs, this tool allows users to upload, search, and stream videos seamlessly.
- External Dependencies: An ElasticSearch server (per the README instructions) acts as a bootstrap or indexing service to aid in video discovery.

##### Out Relationships and Interactions
- The CLI (dream-cli) acts as the entry point for user commands (e.g., upload, stream). It triggers functions within the BitTorrent engine.
- The BitTorrent engine fetches metadata from and communicates with the DHT network to obtain peer information and manage downloads/uploads.
- There is a clear interaction line between the BitTorrent engine and the HTTP server, with the engine providing video data on-demand to the HTTP service.
- The DHT service operates as a separate always-on service that continuously maintains the distributed network information.
- External ElasticSearch is used for video indexing—it communicates with the BitTorrent engine (or bootstrap node) to support search capabilities.

##### Architectural Patterns and Design Principles
- Modularity: The project is broken down into logical modules (dht, bittorrent, peer, tracker, stream, etc.) for separation of concerns.
- Service Separation: The three main services (DHT, BitTorrent engine, HTTP server) are loosely coupled but work in concert.
- Command-Driven: The CLI component facilitates direct user interaction with the system’s backend.
- Decentralization: Emphasize the peer-to-peer and distributed nature of the architecture, particularly in the design of the DHT-based decentralized tracker.

##### Relevant Technologies and Frameworks
- Rust (core implementation language)
- BitTorrent Protocol and Kademlia DHT (for P2P sharing/tracking)
- HTTP (for on-demand video streaming)
- ElasticSearch (external dependency for search/indexing)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Internal Services"
        A["DHT Service (dream-dht)\n(Decentralized Tracker using Kademlia)"]:::internal
        B["BitTorrent Engine (dream-torrent)\n(Peer-to-peer video sharing)"]:::internal
        C["HTTP Streaming Server\n(On-demand video streaming)"]:::internal
        D["Command-Line Interface (dream-cli)\n(User Commands)"]:::cli
    end

    E["External ElasticSearch\n(Video Indexing and Search)"]:::external

    D -->|"issues_commands"| B
    B -->|"fetches_peer_data"| A
    B -->|"supplies_video_data"| C
    B -->|"indexes_video_info"| E

    click A "https://github.com/kamui-fin/dream/tree/main/src/dht/"
    click A "https://github.com/kamui-fin/dream/blob/main/src/bin/dht.rs"
    click B "https://github.com/kamui-fin/dream/blob/main/src/bittorrent.rs"
    click B "https://github.com/kamui-fin/dream/blob/main/src/tracker.rs"
    click B "https://github.com/kamui-fin/dream/blob/main/src/metafile.rs"
    click B "https://github.com/kamui-fin/dream/blob/main/src/piece.rs"
    click B "https://github.com/kamui-fin/dream/blob/main/src/peer/manager.rs"
    click B "https://github.com/kamui-fin/dream/blob/main/src/peer/session.rs"
    click B "https://github.com/kamui-fin/dream/blob/main/src/peer/stats.rs"
    click C "https://github.com/kamui-fin/dream/blob/main/src/stream.rs"
    click D "https://github.com/kamui-fin/dream/blob/main/src/bin/cli.rs"

    classDef internal fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef cli fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
