# yourok/torrserver architecture

> Architecture diagram of the GitHub repository yourok/torrserver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yourok/torrserver
- Repository: https://github.com/yourok/torrserver
- Video tour (about a minute): https://gitdiagram.com/yourok/torrserver/video

## Overview

TorrServer is a server for adding and managing torrents, caching their pieces, and serving media over HTTP without first downloading complete files. The main workflow runs from a browser or API client through the web/API layer to the torrent engine and its cache, then streams requested media to the client. The product also exposes a web UI, Torznab search, optional DLNA and GStreamer support, and an MCP interface; Telegram and filesystem-based torrent input are additional entry points. Some subsystem wiring is inferred from documented capabilities and module boundaries; unsampled handlers are not modeled as direct calls.

Main entry points: [`server/web/api/route.go`](https://github.com/yourok/torrserver/blob/master/server/web/api/route.go) (HTTP API), [`server/torr/torrent.go`](https://github.com/yourok/torrserver/blob/master/server/torr/torrent.go) (Torrent management), [`server/web/server.go`](https://github.com/yourok/torrserver/blob/master/server/web/server.go) (HTTP server), [`server/torr/btserver.go`](https://github.com/yourok/torrserver/blob/master/server/torr/btserver.go) (Torrent engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interfaces"]
  node_web_ui["Web UI<br/>[index.jsx]"]
end

subgraph group_http["Server interfaces"]
  node_web_server["HTTP server<br/>[server.go]"]
  node_api["HTTP API<br/>[route.go]"]
  node_pages["Web pages<br/>[route.go]"]
  node_mcp["MCP endpoint<br/>[server.go]"]
  node_torrent_api["Torrent API<br/>[torrents.go]"]
  node_play_api["Playback API<br/>[play.go]"]
  node_stream_api["Stream API<br/>[stream.go]"]
end

subgraph group_torrent["Torrent streaming"]
  node_engine["Torrent engine<br/>[btserver.go]"]
  node_torrent_model["Torrent management<br/>[torrent.go]"]
  node_piece_cache[("Piece cache<br/>[storage.go]")]
  node_torrent_fs["Torrent filesystem<br/>[torrfs.go]"]
end

subgraph group_state["Configuration state"]
  node_settings["Settings<br/>[settings.go]"]
  node_settings_db[("Settings storage<br/>[db.go]")]
end

subgraph group_integrations["Optional integrations"]
  node_search["Torznab search<br/>[torznab.go]"]
  node_rutor["RuTor search<br/>[rutor.go]"]
  node_dlna["DLNA server<br/>[dlna.go]"]
  node_gstreamer["GStreamer remux<br/>[service.go]"]
  node_telegram["Telegram bot<br/>[server.go]"]
  node_upload["Telegram uploads<br/>[manager.go]"]
  node_bonjour["Bonjour discovery<br/>[bonjour.go]"]
end

node_browser(("Browser user"))
node_media(("Media client"))
node_telegram_user(("Telegram user"))
node_mcp_client(("MCP client"))

node_browser -->|"uses"| node_web_ui
node_web_ui -->|"requests"| node_api
node_web_server -->|"mounts"| node_pages
node_web_server -->|"mounts"| node_api
node_web_server -->|"mounts"| node_mcp
node_api -->|"dispatches"| node_torrent_api
node_api -->|"dispatches"| node_play_api
node_api -->|"dispatches"| node_stream_api
node_torrent_api -->|"manages"| node_torrent_model
node_play_api -->|"selects media"| node_torrent_model
node_stream_api -->|"serves stream"| node_engine
node_engine -->|"reads and writes"| node_piece_cache
node_torrent_model -->|"manages torrents"| node_engine
node_engine -->|"exposes files"| node_torrent_fs
node_media -->|"requests stream"| node_stream_api
node_settings -->|"persists"| node_settings_db
node_api -->|"updates settings"| node_settings
node_mcp_client -->|"uses tools"| node_mcp
node_mcp -->|"manages torrents"| node_torrent_model
node_search -.->|"queries"| node_rutor
node_torrent_api -.->|"searches indexers"| node_search
node_web_server -.->|"starts optionally"| node_dlna
node_dlna -.->|"serves torrent media"| node_engine
node_stream_api -.->|"remuxes optionally"| node_gstreamer
node_telegram_user -->|"uses"| node_telegram
node_telegram -->|"manages torrents"| node_torrent_model
node_telegram -->|"queues uploads"| node_upload
node_upload -->|"reads torrent files"| node_torrent_model
node_web_server -.->|"starts optionally"| node_bonjour

click node_web_ui "https://github.com/yourok/torrserver/blob/master/web/src/components/App/index.jsx"
click node_web_server "https://github.com/yourok/torrserver/blob/master/server/web/server.go"
click node_api "https://github.com/yourok/torrserver/blob/master/server/web/api/route.go"
click node_pages "https://github.com/yourok/torrserver/blob/master/server/web/pages/route.go"
click node_mcp "https://github.com/yourok/torrserver/blob/master/server/mcp/server.go"
click node_torrent_api "https://github.com/yourok/torrserver/blob/master/server/web/api/torrents.go"
click node_play_api "https://github.com/yourok/torrserver/blob/master/server/web/api/play.go"
click node_stream_api "https://github.com/yourok/torrserver/blob/master/server/web/api/stream.go"
click node_engine "https://github.com/yourok/torrserver/blob/master/server/torr/btserver.go"
click node_torrent_model "https://github.com/yourok/torrserver/blob/master/server/torr/torrent.go"
click node_piece_cache "https://github.com/yourok/torrserver/blob/master/server/torr/storage/torrstor/storage.go"
click node_torrent_fs "https://github.com/yourok/torrserver/blob/master/server/torrfs/torrfs.go"
click node_settings "https://github.com/yourok/torrserver/blob/master/server/settings/settings.go"
click node_settings_db "https://github.com/yourok/torrserver/blob/master/server/settings/db.go"
click node_search "https://github.com/yourok/torrserver/blob/master/server/torznab/torznab.go"
click node_rutor "https://github.com/yourok/torrserver/blob/master/server/rutor/rutor.go"
click node_dlna "https://github.com/yourok/torrserver/blob/master/server/dlna/dlna.go"
click node_gstreamer "https://github.com/yourok/torrserver/blob/master/server/gstreamer/service.go"
click node_telegram "https://github.com/yourok/torrserver/blob/master/server/tgbot/server.go"
click node_upload "https://github.com/yourok/torrserver/blob/master/server/tgbot/upload/manager.go"
click node_bonjour "https://github.com/yourok/torrserver/blob/master/server/bonjour/bonjour.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_ui,node_browser,node_media,node_telegram_user,node_mcp_client toneBlue
class node_web_server,node_api,node_pages,node_mcp,node_torrent_api,node_play_api,node_stream_api toneAmber
class node_engine,node_torrent_model,node_piece_cache,node_torrent_fs toneMint
class node_settings,node_settings_db toneRose
class node_search,node_rutor,node_dlna,node_gstreamer,node_telegram,node_upload,node_bonjour toneIndigo
```

## Components

### User interfaces

- [Web UI](https://github.com/yourok/torrserver/blob/master/web/src/components/App/index.jsx): `web/src/components/App/index.jsx`

### Server interfaces

- [HTTP server](https://github.com/yourok/torrserver/blob/master/server/web/server.go): `server/web/server.go`
- [HTTP API](https://github.com/yourok/torrserver/blob/master/server/web/api/route.go): `server/web/api/route.go`
- [Web pages](https://github.com/yourok/torrserver/blob/master/server/web/pages/route.go): `server/web/pages/route.go`
- [MCP endpoint](https://github.com/yourok/torrserver/blob/master/server/mcp/server.go): `server/mcp/server.go`
- [Torrent API](https://github.com/yourok/torrserver/blob/master/server/web/api/torrents.go): `server/web/api/torrents.go`
- [Playback API](https://github.com/yourok/torrserver/blob/master/server/web/api/play.go): `server/web/api/play.go`
- [Stream API](https://github.com/yourok/torrserver/blob/master/server/web/api/stream.go): `server/web/api/stream.go`

### Torrent streaming

- [Torrent engine](https://github.com/yourok/torrserver/blob/master/server/torr/btserver.go): `server/torr/btserver.go`
- [Torrent management](https://github.com/yourok/torrserver/blob/master/server/torr/torrent.go): `server/torr/torrent.go`
- [Piece cache](https://github.com/yourok/torrserver/blob/master/server/torr/storage/torrstor/storage.go): `server/torr/storage/torrstor/storage.go`
- [Torrent filesystem](https://github.com/yourok/torrserver/blob/master/server/torrfs/torrfs.go): `server/torrfs/torrfs.go`

### Configuration state

- [Settings](https://github.com/yourok/torrserver/blob/master/server/settings/settings.go): `server/settings/settings.go`
- [Settings storage](https://github.com/yourok/torrserver/blob/master/server/settings/db.go): `server/settings/db.go`

### Optional integrations

- [Torznab search](https://github.com/yourok/torrserver/blob/master/server/torznab/torznab.go): `server/torznab/torznab.go`
- [RuTor search](https://github.com/yourok/torrserver/blob/master/server/rutor/rutor.go): `server/rutor/rutor.go`
- [DLNA server](https://github.com/yourok/torrserver/blob/master/server/dlna/dlna.go): `server/dlna/dlna.go`
- [GStreamer remux](https://github.com/yourok/torrserver/blob/master/server/gstreamer/service.go): `server/gstreamer/service.go`
- [Telegram bot](https://github.com/yourok/torrserver/blob/master/server/tgbot/server.go): `server/tgbot/server.go`
- [Telegram uploads](https://github.com/yourok/torrserver/blob/master/server/tgbot/upload/manager.go): `server/tgbot/upload/manager.go`
- [Bonjour discovery](https://github.com/yourok/torrserver/blob/master/server/bonjour/bonjour.go): `server/bonjour/bonjour.go`

### Other components

- **Browser user**
- **Media client**
- **Telegram user**
- **MCP client**

## Connections

- Browser user → Web UI: uses
- Web UI → HTTP API: requests
- HTTP server → Web pages: mounts
- HTTP server → HTTP API: mounts
- HTTP server → MCP endpoint: mounts
- HTTP API → Torrent API: dispatches
- HTTP API → Playback API: dispatches
- HTTP API → Stream API: dispatches
- Torrent API → Torrent management: manages
- Playback API → Torrent management: selects media
- Stream API → Torrent engine: serves stream
- Torrent engine → Piece cache: reads and writes
- Torrent management → Torrent engine: manages torrents
- Torrent engine → Torrent filesystem: exposes files
- Media client → Stream API: requests stream
- Settings → Settings storage: persists
- HTTP API → Settings: updates settings
- MCP client → MCP endpoint: uses tools
- MCP endpoint → Torrent management: manages torrents
- Torznab search → RuTor search: queries
- Torrent API → Torznab search: searches indexers
- HTTP server → DLNA server: starts optionally
- DLNA server → Torrent engine: serves torrent media
- Stream API → GStreamer remux: remuxes optionally
- Telegram user → Telegram bot: uses
- Telegram bot → Torrent management: manages torrents
- Telegram bot → Telegram uploads: queues uploads
- Telegram uploads → Torrent management: reads torrent files
- HTTP server → Bonjour discovery: starts optionally