# weebzone/surf-tg architecture

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

- Interactive diagram: https://gitdiagram.com/weebzone/surf-tg
- Repository: https://github.com/weebzone/surf-tg

## Overview

Surf-TG indexes media from authorized Telegram channels and serves it through a web application for search, download, and video streaming; authenticated administrators can also manage playlist folders and files. Channel messages are indexed into MongoDB, while browsing and streaming resolve Telegram messages and retrieve byte ranges through Telegram clients. The README also documents multi-channel indexing, thumbnails, configurable themes, and optional multi-client download scaling. Several route and startup sections were not sampled, so only visible or documented relationships are shown.

Main entry points: [`bot/server/stream_routes.py`](https://github.com/weebzone/surf-tg/blob/main/bot/server/stream_routes.py) (Web routes), [`bot/helper/database.py`](https://github.com/weebzone/surf-tg/blob/main/bot/helper/database.py) (Database operations), [`bot/helper/index.py`](https://github.com/weebzone/surf-tg/blob/main/bot/helper/index.py) (Channel indexing), [`bot/telegram/plugins/start.py`](https://github.com/weebzone/surf-tg/blob/main/bot/telegram/plugins/start.py) (Bot commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Telegram indexing"]
  node_plugin["Bot commands<br/>[start.py]"]
  node_indexer["Channel indexing<br/>[index.py]"]
  node_clients["Telegram clients<br/>[clients.py]"]
end

subgraph group_web["Web application"]
  node_routes["Web routes<br/>[stream_routes.py]"]
  node_templates["Page rendering<br/>[render_template.py]"]
  node_views["Web templates"]
  node_playlist["Playlist management<br/>[chats.py]"]
  node_search["Media search<br/>[search.py]"]
end

subgraph group_media["Media delivery"]
  node_stream["Range streaming<br/>[custom_dl.py]"]
  node_properties["File properties<br/>[file_properties.py]"]
  node_thumbnail["Thumbnail handling<br/>[thumbnail.py]"]
end

subgraph group_state["Storage and helpers"]
  node_database["Database operations<br/>[database.py]"]
  node_cache["Index cache<br/>[cache.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_parser["Token parsing<br/>[parser.py]"]
  node_mediahelper["Media detection<br/>[media.py]"]
  node_size["Size formatting<br/>[file_size.py]"]
  node_exceptions["Media errors<br/>[exceptions.py]"]
end

node_visitor(("Browser visitor"))
node_channel(("Channel operator"))
node_telegram["Telegram"]
node_mongo[("MongoDB")]

node_channel -->|"sends channel files"| node_plugin
node_plugin -->|"indexes messages"| node_indexer
node_plugin -->|"stores indexed files"| node_database
node_indexer -->|"fetches messages"| node_telegram
node_indexer -->|"reads and stores"| node_database
node_indexer -->|"reads and saves"| node_cache
node_indexer -->|"formats sizes"| node_size
node_visitor -->|"requests pages or media"| node_routes
node_routes -->|"renders pages"| node_templates
node_templates -->|"loads templates"| node_views
node_routes -->|"reads and updates"| node_database
node_routes -->|"builds playlist views"| node_playlist
node_routes -->|"searches channel files"| node_search
node_routes -->|"dispatches media requests"| node_stream
node_routes -.->|"serves thumbnails"| node_thumbnail
node_routes -.->|"uses indexed files"| node_indexer
node_search -->|"searches stored files"| node_database
node_playlist -->|"manages playlist data"| node_database
node_stream -->|"resolves file metadata"| node_properties
node_stream -->|"retrieves file bytes"| node_telegram
node_properties -->|"fetches message media"| node_telegram
node_properties -->|"detects media"| node_mediahelper
node_templates -->|"validates file links"| node_properties
node_clients -->|"parses bot tokens"| node_parser
node_clients -->|"starts worker bots"| node_telegram
node_plugin -->|"checks channel settings"| node_config
node_database -->|"gets connection settings"| node_config
node_database -->|"persists playlist and indexes"| node_mongo
node_stream -->|"raises media errors"| node_exceptions

click node_plugin "https://github.com/weebzone/surf-tg/blob/main/bot/telegram/plugins/start.py"
click node_indexer "https://github.com/weebzone/surf-tg/blob/main/bot/helper/index.py"
click node_clients "https://github.com/weebzone/surf-tg/blob/main/bot/telegram/clients.py"
click node_routes "https://github.com/weebzone/surf-tg/blob/main/bot/server/stream_routes.py"
click node_templates "https://github.com/weebzone/surf-tg/blob/main/bot/server/render_template.py"
click node_views "https://github.com/weebzone/surf-tg/tree/main/bot/server/template"
click node_playlist "https://github.com/weebzone/surf-tg/blob/main/bot/helper/chats.py"
click node_search "https://github.com/weebzone/surf-tg/blob/main/bot/helper/search.py"
click node_stream "https://github.com/weebzone/surf-tg/blob/main/bot/server/custom_dl.py"
click node_properties "https://github.com/weebzone/surf-tg/blob/main/bot/server/file_properties.py"
click node_thumbnail "https://github.com/weebzone/surf-tg/blob/main/bot/helper/thumbnail.py"
click node_database "https://github.com/weebzone/surf-tg/blob/main/bot/helper/database.py"
click node_cache "https://github.com/weebzone/surf-tg/blob/main/bot/helper/cache.py"
click node_config "https://github.com/weebzone/surf-tg/blob/main/bot/config.py"
click node_parser "https://github.com/weebzone/surf-tg/blob/main/bot/helper/parser.py"
click node_mediahelper "https://github.com/weebzone/surf-tg/blob/main/bot/helper/media.py"
click node_size "https://github.com/weebzone/surf-tg/blob/main/bot/helper/file_size.py"
click node_exceptions "https://github.com/weebzone/surf-tg/blob/main/bot/helper/exceptions.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_plugin,node_indexer,node_clients,node_visitor toneBlue
class node_routes,node_templates,node_views,node_playlist,node_search,node_mongo toneAmber
class node_stream,node_properties,node_thumbnail toneMint
class node_database,node_cache,node_config,node_parser,node_mediahelper,node_size,node_exceptions toneRose
class node_channel,node_telegram toneIndigo
```

## Components

### Telegram indexing

- [Bot commands](https://github.com/weebzone/surf-tg/blob/main/bot/telegram/plugins/start.py): `bot/telegram/plugins/start.py`
- [Channel indexing](https://github.com/weebzone/surf-tg/blob/main/bot/helper/index.py): `bot/helper/index.py`
- [Telegram clients](https://github.com/weebzone/surf-tg/blob/main/bot/telegram/clients.py): `bot/telegram/clients.py`

### Web application

- [Web routes](https://github.com/weebzone/surf-tg/blob/main/bot/server/stream_routes.py): `bot/server/stream_routes.py`
- [Page rendering](https://github.com/weebzone/surf-tg/blob/main/bot/server/render_template.py): `bot/server/render_template.py`
- [Web templates](https://github.com/weebzone/surf-tg/tree/main/bot/server/template): `bot/server/template`
- [Playlist management](https://github.com/weebzone/surf-tg/blob/main/bot/helper/chats.py): `bot/helper/chats.py`
- [Media search](https://github.com/weebzone/surf-tg/blob/main/bot/helper/search.py): `bot/helper/search.py`

### Media delivery

- [Range streaming](https://github.com/weebzone/surf-tg/blob/main/bot/server/custom_dl.py): `bot/server/custom_dl.py`
- [File properties](https://github.com/weebzone/surf-tg/blob/main/bot/server/file_properties.py): `bot/server/file_properties.py`
- [Thumbnail handling](https://github.com/weebzone/surf-tg/blob/main/bot/helper/thumbnail.py): `bot/helper/thumbnail.py`

### Storage and helpers

- [Database operations](https://github.com/weebzone/surf-tg/blob/main/bot/helper/database.py): `bot/helper/database.py`
- [Index cache](https://github.com/weebzone/surf-tg/blob/main/bot/helper/cache.py): `bot/helper/cache.py`
- [Runtime configuration](https://github.com/weebzone/surf-tg/blob/main/bot/config.py): `bot/config.py`
- [Token parsing](https://github.com/weebzone/surf-tg/blob/main/bot/helper/parser.py): `bot/helper/parser.py`
- [Media detection](https://github.com/weebzone/surf-tg/blob/main/bot/helper/media.py): `bot/helper/media.py`
- [Size formatting](https://github.com/weebzone/surf-tg/blob/main/bot/helper/file_size.py): `bot/helper/file_size.py`
- [Media errors](https://github.com/weebzone/surf-tg/blob/main/bot/helper/exceptions.py): `bot/helper/exceptions.py`

### Other components

- **Browser visitor**
- **Channel operator**
- **Telegram**
- **MongoDB**

## Connections

- Channel operator → Bot commands: sends channel files (evidence: `README.md`)
- Bot commands → Channel indexing: indexes messages (evidence: `bot/telegram/plugins/start.py`)
- Bot commands → Database operations: stores indexed files (evidence: `bot/telegram/plugins/start.py`)
- Channel indexing → Telegram: fetches messages (evidence: `bot/helper/index.py`)
- Channel indexing → Database operations: reads and stores (evidence: `bot/helper/index.py`)
- Channel indexing → Index cache: reads and saves (evidence: `bot/helper/index.py`)
- Channel indexing → Size formatting: formats sizes (evidence: `bot/helper/index.py`)
- Browser visitor → Web routes: requests pages or media (evidence: `README.md`)
- Web routes → Page rendering: renders pages (evidence: `bot/server/stream_routes.py`)
- Page rendering → Web templates: loads templates (evidence: `bot/server/render_template.py`)
- Web routes → Database operations: reads and updates (evidence: `bot/server/stream_routes.py`)
- Web routes → Playlist management: builds playlist views (evidence: `bot/server/stream_routes.py`)
- Web routes → Media search: searches channel files (evidence: `bot/server/stream_routes.py`)
- Web routes → Range streaming: dispatches media requests (evidence: `bot/server/stream_routes.py`)
- Web routes → Thumbnail handling: serves thumbnails (evidence: `bot/server/stream_routes.py`)
- Web routes → Channel indexing: uses indexed files (evidence: `bot/server/stream_routes.py`)
- Media search → Database operations: searches stored files (evidence: `bot/helper/search.py`)
- Playlist management → Database operations: manages playlist data (evidence: `bot/helper/chats.py`)
- Range streaming → File properties: resolves file metadata (evidence: `bot/server/custom_dl.py`)
- Range streaming → Telegram: retrieves file bytes
- File properties → Telegram: fetches message media (evidence: `bot/server/file_properties.py`)
- File properties → Media detection: detects media (evidence: `bot/server/file_properties.py`)
- Page rendering → File properties: validates file links (evidence: `bot/server/render_template.py`)
- Telegram clients → Token parsing: parses bot tokens (evidence: `bot/telegram/clients.py`)
- Telegram clients → Telegram: starts worker bots (evidence: `bot/telegram/clients.py`)
- Bot commands → Runtime configuration: checks channel settings (evidence: `bot/telegram/plugins/start.py`)
- Database operations → Runtime configuration: gets connection settings (evidence: `bot/helper/database.py`)
- Database operations → MongoDB: persists playlist and indexes (evidence: `bot/helper/database.py`)
- Range streaming → Media errors: raises media errors (evidence: `bot/server/custom_dl.py`)
