# anysda/torrcast architecture

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

- Interactive diagram: https://gitdiagram.com/anysda/torrcast
- Repository: https://github.com/anysda/torrcast

## Overview

torrcast finds a requested film, series, or anime, selects a playable release, and streams it to a Chromecast. The principal path begins at the CLI, Telegram, or Home Assistant; search and release selection lead into playback, which manages torrent access, stream preparation, and receiver control. Supporting branches cover episode continuation, read-ahead caching, and format conversion. The source index and excerpts establish composition and some calls, while the README documents user-facing behavior; links for unsampled internals are therefore shown as unverified where needed.

Main entry points: [`torrcast/usecases/worker.py`](https://github.com/anysda/torrcast/blob/master/torrcast/usecases/worker.py) (Playback worker), [`torrcast/runtime/wire_search.py`](https://github.com/anysda/torrcast/blob/master/torrcast/runtime/wire_search.py) (Search and selection), [`torrcast/adapters/stream_pack/packer.py`](https://github.com/anysda/torrcast/blob/master/torrcast/adapters/stream_pack/packer.py) (HLS stream packer), [`torrcast/cli/main.py`](https://github.com/anysda/torrcast/blob/master/torrcast/cli/main.py) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands<br/>[main.py]"]
  node_telegram["Telegram bot<br/>[bot.py]"]
  node_ha["Home Assistant bridge<br/>[main.py]"]
end

subgraph group_discovery["Discovery and choice"]
  node_search["Search and selection<br/>[wire_search.py]"]
  node_catalogue["Release catalogue"]
  node_release_rank["Release ranking<br/>[rank_releases.py]"]
  node_name_rules["Title matching<br/>[alt_query.py]"]
end

subgraph group_playback["Playback runtime"]
  node_worker["Playback worker<br/>[worker.py]"]
  node_episode_loop["Episode continuation<br/>[worker_loop.py]"]
  node_torrent["Torrent service<br/>[torr_server.py]"]
  node_torrent_port["Torrent engine port<br/>[torrent_engine.py]"]
end

subgraph group_delivery["Stream delivery"]
  node_chromecast["Chromecast receiver"]
  node_http_stream["HTTP HLS server<br/>[hls_server.py]"]
  node_pack["HLS stream packer<br/>[packer.py]"]
  node_recode["Format conversion<br/>[recoder.py]"]
end

subgraph group_support["Playback support"]
  node_read_ahead["Read-ahead cache<br/>[warm_file.py]"]
  node_state[("Playback state")]
  node_wiki["Film information<br/>[wiki_articles.py]"]
end

node_viewer(("Viewer"))
node_tv(("Chromecast TV"))

node_viewer -->|"requests playback"| node_cli
node_viewer -->|"sends title"| node_telegram
node_viewer -->|"starts playback"| node_ha
node_cli -.->|"starts selection"| node_search
node_telegram -->|"invokes commands"| node_cli
node_ha -->|"searches titles"| node_search
node_search -->|"queries releases"| node_catalogue
node_search -.->|"ranks choices"| node_release_rank
node_search -.->|"forms title queries"| node_name_rules
node_search -.->|"loads film details"| node_wiki
node_search -.->|"starts playback"| node_worker
node_worker -->|"uses torrent service"| node_torrent_port
node_torrent_port -.->|"implemented by"| node_torrent
node_worker -.->|"runs episode loop"| node_episode_loop
node_episode_loop -->|"adds torrent"| node_torrent_port
node_worker -.->|"connects receiver"| node_chromecast
node_worker -.->|"loads configuration"| node_state
node_worker -.->|"prepares stream"| node_pack
node_pack -.->|"converts when needed"| node_recode
node_pack -.->|"publishes HLS"| node_http_stream
node_http_stream -->|"serves video"| node_tv
node_chromecast -->|"controls playback"| node_tv
node_worker -.->|"warms media"| node_read_ahead

click node_cli "https://github.com/anysda/torrcast/blob/master/torrcast/cli/main.py"
click node_telegram "https://github.com/anysda/torrcast/blob/master/tgbot/bot.py"
click node_ha "https://github.com/anysda/torrcast/blob/master/hass/main.py"
click node_search "https://github.com/anysda/torrcast/blob/master/torrcast/runtime/wire_search.py"
click node_catalogue "https://github.com/anysda/torrcast/blob/master/torrcast/adapters/prowlarr/torrent_catalogue.py"
click node_release_rank "https://github.com/anysda/torrcast/blob/master/torrcast/usecases/rank/rank_releases.py"
click node_name_rules "https://github.com/anysda/torrcast/blob/master/torrcast/domain/alt_query.py"
click node_worker "https://github.com/anysda/torrcast/blob/master/torrcast/usecases/worker.py"
click node_episode_loop "https://github.com/anysda/torrcast/blob/master/torrcast/usecases/worker_loop.py"
click node_torrent "https://github.com/anysda/torrcast/blob/master/torrcast/adapters/torrserver/torr_server.py"
click node_torrent_port "https://github.com/anysda/torrcast/blob/master/torrcast/ports/torrent_engine.py"
click node_chromecast "https://github.com/anysda/torrcast/blob/master/torrcast/adapters/chromecast/cast/chromecast_receiver.py"
click node_http_stream "https://github.com/anysda/torrcast/blob/master/torrcast/adapters/http_server/hls_server.py"
click node_pack "https://github.com/anysda/torrcast/blob/master/torrcast/adapters/stream_pack/packer.py"
click node_recode "https://github.com/anysda/torrcast/blob/master/torrcast/adapters/recode/recoder.py"
click node_read_ahead "https://github.com/anysda/torrcast/blob/master/torrcast/adapters/stream_pack/warm_file.py"
click node_state "https://github.com/anysda/torrcast/blob/master/torrcast/adapters/filesystem/state/file_state_store.py"
click node_wiki "https://github.com/anysda/torrcast/blob/master/torrcast/adapters/wiki/wiki_articles.py"

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_cli,node_telegram,node_ha,node_viewer toneBlue
class node_search,node_catalogue,node_release_rank,node_name_rules toneAmber
class node_worker,node_episode_loop,node_torrent,node_torrent_port toneMint
class node_chromecast,node_http_stream,node_pack,node_recode toneRose
class node_read_ahead,node_state,node_wiki,node_tv toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/anysda/torrcast/blob/master/torrcast/cli/main.py): `torrcast/cli/main.py`
- [Telegram bot](https://github.com/anysda/torrcast/blob/master/tgbot/bot.py): `tgbot/bot.py`
- [Home Assistant bridge](https://github.com/anysda/torrcast/blob/master/hass/main.py): `hass/main.py`

### Discovery and choice

- [Search and selection](https://github.com/anysda/torrcast/blob/master/torrcast/runtime/wire_search.py): `torrcast/runtime/wire_search.py`
- [Release catalogue](https://github.com/anysda/torrcast/blob/master/torrcast/adapters/prowlarr/torrent_catalogue.py): `torrcast/adapters/prowlarr/torrent_catalogue.py`
- [Release ranking](https://github.com/anysda/torrcast/blob/master/torrcast/usecases/rank/rank_releases.py): `torrcast/usecases/rank/rank_releases.py`
- [Title matching](https://github.com/anysda/torrcast/blob/master/torrcast/domain/alt_query.py): `torrcast/domain/alt_query.py`

### Playback runtime

- [Playback worker](https://github.com/anysda/torrcast/blob/master/torrcast/usecases/worker.py): `torrcast/usecases/worker.py`
- [Episode continuation](https://github.com/anysda/torrcast/blob/master/torrcast/usecases/worker_loop.py): `torrcast/usecases/worker_loop.py`
- [Torrent service](https://github.com/anysda/torrcast/blob/master/torrcast/adapters/torrserver/torr_server.py): `torrcast/adapters/torrserver/torr_server.py`
- [Torrent engine port](https://github.com/anysda/torrcast/blob/master/torrcast/ports/torrent_engine.py): `torrcast/ports/torrent_engine.py`

### Stream delivery

- [Chromecast receiver](https://github.com/anysda/torrcast/blob/master/torrcast/adapters/chromecast/cast/chromecast_receiver.py): `torrcast/adapters/chromecast/cast/chromecast_receiver.py`
- [HTTP HLS server](https://github.com/anysda/torrcast/blob/master/torrcast/adapters/http_server/hls_server.py): `torrcast/adapters/http_server/hls_server.py`
- [HLS stream packer](https://github.com/anysda/torrcast/blob/master/torrcast/adapters/stream_pack/packer.py): `torrcast/adapters/stream_pack/packer.py`
- [Format conversion](https://github.com/anysda/torrcast/blob/master/torrcast/adapters/recode/recoder.py): `torrcast/adapters/recode/recoder.py`

### Playback support

- [Read-ahead cache](https://github.com/anysda/torrcast/blob/master/torrcast/adapters/stream_pack/warm_file.py): `torrcast/adapters/stream_pack/warm_file.py`
- [Playback state](https://github.com/anysda/torrcast/blob/master/torrcast/adapters/filesystem/state/file_state_store.py): `torrcast/adapters/filesystem/state/file_state_store.py`
- [Film information](https://github.com/anysda/torrcast/blob/master/torrcast/adapters/wiki/wiki_articles.py): `torrcast/adapters/wiki/wiki_articles.py`

### Other components

- **Viewer**
- **Chromecast TV**

## Connections

- Viewer → CLI commands: requests playback
- Viewer → Telegram bot: sends title
- Viewer → Home Assistant bridge: starts playback
- CLI commands → Search and selection: starts selection
- Telegram bot → CLI commands: invokes commands (evidence: `tgbot/bot.py`)
- Home Assistant bridge → Search and selection: searches titles
- Search and selection → Release catalogue: queries releases (evidence: `torrcast/runtime/wire_search.py`)
- Search and selection → Release ranking: ranks choices
- Search and selection → Title matching: forms title queries
- Search and selection → Film information: loads film details
- Search and selection → Playback worker: starts playback
- Playback worker → Torrent engine port: uses torrent service (evidence: `torrcast/usecases/worker.py`)
- Torrent engine port → Torrent service: implemented by
- Playback worker → Episode continuation: runs episode loop (evidence: `torrcast/usecases/worker.py`)
- Episode continuation → Torrent engine port: adds torrent (evidence: `torrcast/usecases/worker_loop.py`)
- Playback worker → Chromecast receiver: connects receiver
- Playback worker → Playback state: loads configuration
- Playback worker → HLS stream packer: prepares stream
- HLS stream packer → Format conversion: converts when needed
- HLS stream packer → HTTP HLS server: publishes HLS
- HTTP HLS server → Chromecast TV: serves video
- Chromecast receiver → Chromecast TV: controls playback
- Playback worker → Read-ahead cache: warms media
