# salimovone/watchtorrent architecture

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

- Interactive diagram: https://gitdiagram.com/salimovone/watchtorrent
- Repository: https://github.com/salimovone/watchtorrent

## Overview

WatchTorrent is a cross-platform MAUI torrent catalog, downloader, and player backed by an in-process libtorrent engine. The main user flow is search or browse catalog listings, open a torrent’s details, add its magnet to downloads, then stream a selected file through a local HTTP endpoint to VLC. TorrentReader is also a reusable catalog/search subsystem. Playback, native-engine internals, and several integrations are represented from README claims where their implementation was not sampled; the graph avoids asserting unshown call relationships.

Main entry points: [`TorrentReader/TorrentClient.cs`](https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/TorrentClient.cs) (Catalog client), [`WatchTorrent.Libtorrent/LibtorrentEngine.cs`](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent.Libtorrent/LibtorrentEngine.cs) (Libtorrent adapter), [`WatchTorrent/Services/DownloadService.cs`](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Services/DownloadService.cs) (Download coordinator), [`TorrentReader/Search/SearchProvider.cs`](https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Search/SearchProvider.cs) (Torrent search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Torrent catalog"]
  node_torrent_client["Catalog client<br/>[TorrentClient.cs]"]
  node_search_provider["Torrent search<br/>[SearchProvider.cs]"]
  node_search_transform["Search parsing"]
  node_http["Site HTTP<br/>[HttpProvider.cs]"]
  node_overview["Listing parsing"]
  node_category_providers["Category listings"]
  node_torrent_detail_provider["Torrent detail fetch"]
  node_detail_transform["Detail parsing"]
  node_cloudflare["Cloudflare clearance"]
end

subgraph group_app["App experience"]
  node_search_ui["Search UI<br/>[SearchPage.xaml.cs]"]
  node_search_vm["Search state<br/>[SearchViewModel.cs]"]
  node_discover["Discover listings"]
  node_torrent_detail_vm["Torrent detail state"]
  node_routes["Navigation and watch<br/>[Routes.cs]"]
  node_downloads_vm["Downloads UI state"]
  node_poster_service["Poster lookup<br/>[PosterService.cs]"]
end

subgraph group_engine["Torrent engine"]
  node_download_service["Download coordinator<br/>[DownloadService.cs]"]
  node_download_item["Download state<br/>[DownloadItem.cs]"]
  node_core_contract["Torrent session model<br/>[TorrentSession.cs]"]
  node_magnet["Magnet parsing<br/>[Magnet.cs]"]
  node_engine_adapter["Libtorrent adapter"]
  node_native_bridge["Native libtorrent bridge<br/>[bridge.cpp]"]
end

subgraph group_playback["Playback and sharing"]
  node_player["Player UI<br/>[PlayerPage.xaml.cs]"]
  node_player_state["Player state<br/>[PlayerViewModel.cs]"]
  node_media_server["Range stream server"]
  node_vlc["VLC playback"]
  node_watch_session["Watch-together session<br/>[WatchSession.cs]"]
end

node_user(("User"))
node_imdb["IMDb suggestions"]

node_user -->|"searches"| node_search_ui
node_search_ui -->|"uses state"| node_search_vm
node_search_vm -->|"requests results"| node_torrent_client
node_torrent_client -->|"delegates search"| node_search_provider
node_search_provider -->|"fetches HTML"| node_http
node_search_provider -->|"transforms results"| node_search_transform
node_search_transform -->|"reuses parsing"| node_overview
node_torrent_client -->|"exposes listings"| node_category_providers
node_torrent_client -->|"fetches details"| node_torrent_detail_provider
node_torrent_detail_provider -.->|"transforms detail"| node_detail_transform
node_discover -.->|"loads listings"| node_torrent_client
node_user -.->|"browses"| node_discover
node_user -.->|"opens torrent"| node_torrent_detail_vm
node_torrent_detail_vm -.->|"starts watching"| node_routes
node_routes -->|"navigates"| node_player
node_user -.->|"manages downloads"| node_downloads_vm
node_downloads_vm -.->|"controls downloads"| node_download_service
node_download_service -->|"manages sessions"| node_engine_adapter
node_download_service -->|"tracks items"| node_download_item
node_engine_adapter -->|"implements engine"| node_core_contract
node_engine_adapter -->|"parses magnet"| node_magnet
node_engine_adapter -.->|"calls native ABI"| node_native_bridge
node_routes -->|"adds shared torrent"| node_download_service
node_player -.->|"uses playback state"| node_player_state
node_player_state -.->|"requests stream"| node_media_server
node_media_server -.->|"reads torrent pieces"| node_engine_adapter
node_media_server -.->|"serves HTTP ranges"| node_vlc
node_player -.->|"coordinates viewing"| node_watch_session
node_poster_service -->|"looks up posters"| node_imdb
node_torrent_client -->|"exposes clearance"| node_cloudflare

click node_search_ui "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Views/SearchPage.xaml.cs"
click node_search_vm "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/ViewModels/SearchViewModel.cs"
click node_discover "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/ViewModels/DiscoverViewModel.cs"
click node_torrent_client "https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/TorrentClient.cs"
click node_search_provider "https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Search/SearchProvider.cs"
click node_search_transform "https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Search/SearchTransformer.cs"
click node_http "https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Http/HttpProvider.cs"
click node_overview "https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Overview/OverviewTransformer.cs"
click node_category_providers "https://github.com/salimovone/watchtorrent/tree/master/TorrentReader/Providers"
click node_torrent_detail_provider "https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Torrent/Provider/TorrentDetailProvider.cs"
click node_detail_transform "https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Torrent/Transformer/TorrentDetailTransformer.cs"
click node_torrent_detail_vm "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/ViewModels/TorrentDetailViewModel.cs"
click node_routes "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Views/Routes.cs"
click node_downloads_vm "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/ViewModels/DownloadsViewModel.cs"
click node_download_service "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Services/DownloadService.cs"
click node_download_item "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Services/DownloadItem.cs"
click node_core_contract "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent.Core/TorrentSession.cs"
click node_magnet "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent.Core/Magnet.cs"
click node_engine_adapter "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent.Libtorrent/LibtorrentEngine.cs"
click node_native_bridge "https://github.com/salimovone/watchtorrent/blob/master/native/bridge.cpp"
click node_player "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Views/PlayerPage.xaml.cs"
click node_player_state "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/ViewModels/PlayerViewModel.cs"
click node_media_server "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Services/TorrentMediaServer.cs"
click node_watch_session "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Services/WatchSession.cs"
click node_poster_service "https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Services/PosterService.cs"
click node_cloudflare "https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Http/CloudflareClearance.cs"

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_torrent_client,node_search_provider,node_search_transform,node_http,node_overview,node_category_providers,node_torrent_detail_provider,node_detail_transform,node_cloudflare,node_user toneBlue
class node_search_ui,node_search_vm,node_discover,node_torrent_detail_vm,node_routes,node_downloads_vm,node_poster_service toneAmber
class node_download_service,node_download_item,node_core_contract,node_magnet,node_engine_adapter,node_native_bridge toneMint
class node_player,node_player_state,node_media_server,node_vlc,node_watch_session toneRose
class node_imdb toneIndigo
```

## Components

### Torrent catalog

- [Catalog client](https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/TorrentClient.cs): `TorrentReader/TorrentClient.cs`
- [Torrent search](https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Search/SearchProvider.cs): `TorrentReader/Search/SearchProvider.cs`
- [Search parsing](https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Search/SearchTransformer.cs): `TorrentReader/Search/SearchTransformer.cs`
- [Site HTTP](https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Http/HttpProvider.cs): `TorrentReader/Http/HttpProvider.cs`
- [Listing parsing](https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Overview/OverviewTransformer.cs): `TorrentReader/Overview/OverviewTransformer.cs`
- [Category listings](https://github.com/salimovone/watchtorrent/tree/master/TorrentReader/Providers): `TorrentReader/Providers`
- [Torrent detail fetch](https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Torrent/Provider/TorrentDetailProvider.cs): `TorrentReader/Torrent/Provider/TorrentDetailProvider.cs`
- [Detail parsing](https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Torrent/Transformer/TorrentDetailTransformer.cs): `TorrentReader/Torrent/Transformer/TorrentDetailTransformer.cs`
- [Cloudflare clearance](https://github.com/salimovone/watchtorrent/blob/master/TorrentReader/Http/CloudflareClearance.cs): `TorrentReader/Http/CloudflareClearance.cs`

### App experience

- [Search UI](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Views/SearchPage.xaml.cs): `WatchTorrent/Views/SearchPage.xaml.cs`
- [Search state](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/ViewModels/SearchViewModel.cs): `WatchTorrent/ViewModels/SearchViewModel.cs`
- [Discover listings](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/ViewModels/DiscoverViewModel.cs): `WatchTorrent/ViewModels/DiscoverViewModel.cs`
- [Torrent detail state](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/ViewModels/TorrentDetailViewModel.cs): `WatchTorrent/ViewModels/TorrentDetailViewModel.cs`
- [Navigation and watch](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Views/Routes.cs): `WatchTorrent/Views/Routes.cs`
- [Downloads UI state](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/ViewModels/DownloadsViewModel.cs): `WatchTorrent/ViewModels/DownloadsViewModel.cs`
- [Poster lookup](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Services/PosterService.cs): `WatchTorrent/Services/PosterService.cs`

### Torrent engine

- [Download coordinator](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Services/DownloadService.cs): `WatchTorrent/Services/DownloadService.cs`
- [Download state](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Services/DownloadItem.cs): `WatchTorrent/Services/DownloadItem.cs`
- [Torrent session model](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent.Core/TorrentSession.cs): `WatchTorrent.Core/TorrentSession.cs`
- [Magnet parsing](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent.Core/Magnet.cs): `WatchTorrent.Core/Magnet.cs`
- [Libtorrent adapter](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent.Libtorrent/LibtorrentEngine.cs): `WatchTorrent.Libtorrent/LibtorrentEngine.cs`
- [Native libtorrent bridge](https://github.com/salimovone/watchtorrent/blob/master/native/bridge.cpp): `native/bridge.cpp`

### Playback and sharing

- [Player UI](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Views/PlayerPage.xaml.cs): `WatchTorrent/Views/PlayerPage.xaml.cs`
- [Player state](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/ViewModels/PlayerViewModel.cs): `WatchTorrent/ViewModels/PlayerViewModel.cs`
- [Range stream server](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Services/TorrentMediaServer.cs): `WatchTorrent/Services/TorrentMediaServer.cs`
- **VLC playback**
- [Watch-together session](https://github.com/salimovone/watchtorrent/blob/master/WatchTorrent/Services/WatchSession.cs): `WatchTorrent/Services/WatchSession.cs`

### Other components

- **User**
- **IMDb suggestions**

## Connections

- User → Search UI: searches
- Search UI → Search state: uses state (evidence: `WatchTorrent/Views/SearchPage.xaml.cs`)
- Search state → Catalog client: requests results (evidence: `WatchTorrent/ViewModels/SearchViewModel.cs`)
- Catalog client → Torrent search: delegates search (evidence: `TorrentReader/TorrentClient.cs`)
- Torrent search → Site HTTP: fetches HTML (evidence: `TorrentReader/Search/SearchProvider.cs`)
- Torrent search → Search parsing: transforms results (evidence: `TorrentReader/Search/SearchProvider.cs`)
- Search parsing → Listing parsing: reuses parsing (evidence: `TorrentReader/Search/SearchTransformer.cs`)
- Catalog client → Category listings: exposes listings (evidence: `TorrentReader/TorrentClient.cs`)
- Catalog client → Torrent detail fetch: fetches details (evidence: `TorrentReader/TorrentClient.cs`)
- Torrent detail fetch → Detail parsing: transforms detail
- Discover listings → Catalog client: loads listings
- User → Discover listings: browses
- User → Torrent detail state: opens torrent
- Torrent detail state → Navigation and watch: starts watching
- Navigation and watch → Player UI: navigates (evidence: `WatchTorrent/Views/Routes.cs`)
- User → Downloads UI state: manages downloads
- Downloads UI state → Download coordinator: controls downloads
- Download coordinator → Libtorrent adapter: manages sessions (evidence: `WatchTorrent/Services/DownloadService.cs`)
- Download coordinator → Download state: tracks items (evidence: `WatchTorrent/Services/DownloadService.cs`)
- Libtorrent adapter → Torrent session model: implements engine (evidence: `WatchTorrent.Libtorrent/LibtorrentEngine.cs`)
- Libtorrent adapter → Magnet parsing: parses magnet (evidence: `WatchTorrent.Libtorrent/LibtorrentEngine.cs`)
- Libtorrent adapter → Native libtorrent bridge: calls native ABI
- Navigation and watch → Download coordinator: adds shared torrent (evidence: `WatchTorrent/Views/Routes.cs`)
- Player UI → Player state: uses playback state
- Player state → Range stream server: requests stream
- Range stream server → Libtorrent adapter: reads torrent pieces
- Range stream server → VLC playback: serves HTTP ranges
- Player UI → Watch-together session: coordinates viewing
- Poster lookup → IMDb suggestions: looks up posters (evidence: `WatchTorrent/Services/PosterService.cs`)
- Catalog client → Cloudflare clearance: exposes clearance (evidence: `TorrentReader/TorrentClient.cs`)
