Architecture

🇬🇧 English · 🇫🇷 Français

Architecture

                ┌──────────── hydra (Go process) ────────────┐
  browser ──────┤  front (control): Web UI (SSE), REST /api/*│
  *arr/autobrr ─┤  qBit shim /api/v2/*, routing, aggregate   │
                │  agent (data): announces + persistence     │
                └───────────────┬────────────────────┬───────┘
                                │ local JSON-RPC     │ gRPC (remote agent)
                        ┌───────┴───────┐    ┌───────┴───────┐
                        │ Typhon (Rust) │    │ Typhon (Rust) │
                        │  race engine  │    │ hoard engine  │
                        └───────────────┘    └───────────────┘

• Control plane / front (internal/api): Web UI (SSE), REST /api/*, the qBit shim /api/v2/*, category routing/placement and multi-agent aggregation. It never announces; a --front-only node has no engine.
• Data plane / agent (internal/engine + Typhon): the torrent engine plus the tracker-announce scheduler and durable persistence. Each agent announces its own engines with its own IP/egress. In the monolith the front and agent live in one process; split them with --agent-only / --front-only (Deployment Topologies).
• Typhon (typhon-engine/, Rust) is the BitTorrent core: peer wire protocol, piece picking, disk I/O, choking. One process per engine, driven over a Unix-socket JSON-RPC (or gRPC to a remote agent, TLS + token).

Why two engines?

race and hoard are the same core tuned for opposite jobs: race is aggressive and short-lived (grab a hot release fast), hoard is upload-optimized and long-lived (seed tens of thousands of torrents cheaply). They're separate processes with separate ports, resume data, and durable stores, so one can't stall the other. You can also add extra engines and shard.

Persistence

Each engine owns a SQLite durable store next to its resume data. Adds are durable immediately (a single row), so a crash before the next periodic flush doesn't lose torrents, and content-addressed .torrent blobs mean re-adds can't collide by filename. On boot the engine reloads from resume + store rather than re-hashing the disk.

See docs/ for the API reference (API.md) and the agent/front notes.