# varbhat/exatorrent architecture

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

- Interactive diagram: https://gitdiagram.com/varbhat/exatorrent
- Repository: https://github.com/varbhat/exatorrent

## Overview

##### Project Type and Purpose
- exatorrent is a self‑hostable, full‑stack BitTorrent client.
- Backend: a single statically‑linked Go binary exposing an HTTP/REST + WebSocket API, managing torrent sessions.
- Frontend: a responsive Svelte/TypeScript web app embedded in the binary.
- Supports two deployment modes: local CLI/binary or containerized (Docker/Podman).

##### High‑Level File‑Structure Analysis
- Top‑level:
- exatorrent.go / go.mod/go.sum – the Go entrypoint and module.
- Dockerfile / Makefile / CI workflows – build, test, container scripts.
- docs/ – Markdown docs on API, config, database, usage, etc.
- internal/core: application logic
- auth, init, engine, connection, storage, cache, statsapi, WebSocket serve, CLI “get” commands.
- internal/db: data‑access layer abstraction
- Generic db.go interfaces, SQLite3 & PostgreSQL implementations for torrents, users, trackers, locks, file state, piece counts.
- internal/web: static frontend assets + Go embedding
- Svelte source (src/), package.json, build configs, web.go & web_noui.go to serve or disable UI embedding.

##### Key Components
a. User & Client
- Web Browser (UI)
- Optional CLI (exatorrent binary flags)
b. HTTP/REST + WebSocket API Layer
- Serves static UI assets
- Exposes endpoints for torrent CRUD, user auth, settings
- WebSocket for live stats & notifications
c. Core Engine
- Torrent session manager (anacrolix/torrent under the hood)
- Auth & session management
- Rate limiter, blocklist, auto‑tracker injection
- Storage & caching submodules
d. Data Store
- Configurable plug‑in to SQLite3 (default) or PostgreSQL
- Tables: torrents, users, trackers, file_state, locks, piece_counts
- Persists state across restarts
e. File Storage
- Local disk directory for torrent data + downloaded files
- ZIP / tarball generation on the fly
f. External Services
- BitTorrent network (peers, DHT, trackers)
- (Optional) external metainfo cache or trackers list URLs

##### Relationships & Data Flows
- Browser ↔ HTTP API: user actions (add torrent, auth)
- Browser ↔ WebSocket: live progress, notifications, stats
- HTTP API → Core Engine: request handling routes into engine routines
- Core Engine ↔ Data Store: read/write torrent & user state
- Core Engine ↔ File Storage: read/write torrent data, serve files/streams
- Core Engine ↔ BitTorrent P2P Network: connect to peers, exchange pieces
- Container/Docker orchestration wraps all above with port mappings (HTTP port 5000, torrent port 42069) and mounts

##### Architectural Patterns & Design Principles
- Layered (HTTP/API → Core → DB → Storage)
- Hexagonal/Ports-&‑Adapters in internal/db for RDBMS swapping
- Single binary embedding static assets for zero‑dependency deployment
- Separation of concerns: auth, storage, networking, UI are distinct modules
- Concurrency via Go routines in core/routine.go

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    Browser["Web Browser UI"]:::external
    CLI["CLI (No-UI Mode)"]:::external
    DockerHost["Docker/Podman Host"]:::external

    %% Services Layer
    subgraph "API Layer"
        HTTP["HTTP/REST API Server\n(Go net/http)"]:::service
        WS["WebSocket Server\n(RFC6455)"]:::service
    end

    subgraph "Core Engine" 
        Engine["Torrent Session Manager\n(anacrolix/torrent)"]:::service
        Auth["Authentication Module"]:::service
        Conn["Connection Management\n(Routing)"]:::service
        Stats["Stats & Live Updates API"]:::service
        Init["Core Init & Versioning"]:::service
        GetCLI["CLI “get” Commands"]:::service
        Routine["Concurrency Routines"]:::service
        StorageCore["Storage & Caching"]:::service
        Vars["Config Defaults & Vars"]:::service
    end

    %% Data Stores
    subgraph "Data Store"
        DBInterface["DB Abstraction\n(ports & adapters)"]:::service
        SQLite["SQLite3 Datastore"]:::datastore
        Postgres["PostgreSQL Datastore"]:::datastore
        FileSys["File Storage\n(Torrent Data)"]:::datastore
    end

    %% External Networks
    P2P["BitTorrent P2P Network\n(DHT/Trackers)"]:::network
    MetaCache["External Metainfo Cache"]:::network

    %% Deployment
    Container["Single Binary Container\nPorts:5000,42069\nVolume Mount"]:::deployment

    %% Flows
    Browser -->|HTTP/REST| HTTP
    Browser -->|WebSocket| WS
    CLI -->|Flags/API Calls| HTTP

    HTTP -->|"routes"| Conn
    HTTP -->|calls| Auth
    HTTP -->|calls| Engine
    WS -->|upgrades| Conn
    WS -->|push| Stats

    Conn -->|invoke| Engine
    Auth -->|validate| DBInterface
    Stats -->|read/write| DBInterface
    Engine -->|read/write| StorageCore
    Engine -->|spawn| Routine
    Engine -->|P2P I/O| P2P
    Engine -->|FS I/O| FileSys

    StorageCore -->|SQL| DBInterface
    DBInterface -->|SQLite| SQLite
    DBInterface -->|PostgreSQL| Postgres

    Engine -->|init/version| Init
    Engine -->|vars| Vars
    Engine -->|CLI get| GetCLI

    Container --> HTTP
    Container --> P2P
    Container --> FileSys

    %% Click Events
    click Browser "https://github.com/varbhat/exatorrent/tree/main/internal/web/"
    click CLI "https://github.com/varbhat/exatorrent/blob/main/internal/web/web_noui.go"
    click GetCLI "https://github.com/varbhat/exatorrent/blob/main/internal/core/get.go"
    click HTTP "https://github.com/varbhat/exatorrent/blob/main/internal/core/serve.go"
    click WS "https://github.com/varbhat/exatorrent/blob/main/internal/core/socket.go"
    click Stats "https://github.com/varbhat/exatorrent/blob/main/internal/core/statsapi.go"
    click Auth "https://github.com/varbhat/exatorrent/blob/main/internal/core/auth.go"
    click Conn "https://github.com/varbhat/exatorrent/blob/main/internal/core/connection.go"
    click Engine "https://github.com/varbhat/exatorrent/blob/main/internal/core/engine.go"
    click Init "https://github.com/varbhat/exatorrent/blob/main/internal/core/init.go"
    click Routine "https://github.com/varbhat/exatorrent/blob/main/internal/core/routine.go"
    click StorageCore "https://github.com/varbhat/exatorrent/blob/main/internal/core/storage.go"
    click DBInterface "https://github.com/varbhat/exatorrent/blob/main/internal/db/db.go"
    click SQLite "https://github.com/varbhat/exatorrent/blob/main/internal/db/sqlite3torrentdb.go"
    click Postgres "https://github.com/varbhat/exatorrent/blob/main/internal/db/psqltorrentdb.go"
    click Container "https://github.com/varbhat/exatorrent/tree/main/Dockerfile"
    click FileSys "https://github.com/varbhat/exatorrent/blob/main/internal/core/storage_cgo.go"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef service fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef datastore fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef network fill:#D8BFD8,stroke:#000,stroke-width:1px;
    classDef deployment fill:#F5F5F5,stroke:#000,stroke-width:1px;
```
