# zytyan/suppbot architecture

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

- Interactive diagram: https://gitdiagram.com/zytyan/suppbot
- Repository: https://github.com/zytyan/suppbot

## Overview

suppbot is a Telegram auto-archiving bot with a web administration interface and full-text article search. Its main flow crawls article pages and magnet hashes, persists jobs, downloads torrents, processes media, then publishes files and links through Telegram; the worker owns this orchestration. Separate branches index article text for search and expose runtime/job state to administrators. Edges below follow README statements or shown calls/import references; unsampled subsystems are included at documented directory paths, with uncertain wiring omitted.

Main entry points: [`src/main.ts`](https://github.com/zytyan/suppbot/blob/main/src/main.ts) (Application startup), [`src/worker.ts`](https://github.com/zytyan/suppbot/blob/main/src/worker.ts) (Job orchestrator), [`src/store.ts`](https://github.com/zytyan/suppbot/blob/main/src/store.ts) (Archive job store), [`src/telegram.ts`](https://github.com/zytyan/suppbot/blob/main/src/telegram.ts) (Telegram publishing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Article ingestion"]
  node_crawler["Article crawler<br/>[crawler.ts]"]
  node_crawl_loop["Scheduled discovery<br/>[worker.ts]"]
  node_article_photo["Cover retrieval<br/>[article-photo.ts]"]
end

subgraph group_archive["Archiving pipeline"]
  node_job_store[("Archive job store<br/>[store.ts]")]
  node_worker["Job orchestrator<br/>[worker.ts]"]
  node_qbit["Torrent adapter<br/>[qbit.ts]"]
  node_media["Media processing<br/>[media.ts]"]
end

subgraph group_telegram["Telegram and search"]
  node_telegram_adapter["Telegram publishing<br/>[telegram.ts]"]
  node_search_service["Indexing service<br/>[search-service.ts]"]
  node_search_store[("Search index<br/>[search-store.ts]")]
  node_search_bot["Search commands<br/>[search-bot.ts]"]
  node_bot_commands["Command definitions<br/>[bot-commands.ts]"]
end

subgraph group_operations["Operations"]
  node_main["Application startup<br/>[main.ts]"]
  node_config["Configuration<br/>[config.ts]"]
  node_admin["Admin interface<br/>[admin.ts]"]
  node_runtime["Live runtime state<br/>[runtime.ts]"]
  node_admin_web["Admin page assets"]
end

node_operator(("Operator"))
node_telegram_users(("Telegram users"))
node_article_site(("Article site"))
node_telegram_api(("Telegram Bot API"))

node_operator -->|"starts service"| node_main
node_main -->|"loads config"| node_config
node_main -->|"initializes"| node_job_store
node_main -->|"starts workers"| node_worker
node_main -->|"starts crawl"| node_crawl_loop
node_main -->|"starts indexing"| node_search_service
node_main -->|"creates bot"| node_telegram_adapter
node_main -->|"starts server"| node_admin
node_crawl_loop -->|"fetches articles"| node_crawler
node_crawl_loop -->|"queues articles"| node_job_store
node_crawler -->|"fetches pages"| node_article_site
node_worker -->|"claims and updates"| node_job_store
node_worker -->|"recovers articles"| node_crawler
node_worker -.->|"downloads torrents"| node_qbit
node_worker -.->|"processes files"| node_media
node_worker -->|"publishes archive"| node_telegram_adapter
node_telegram_adapter -->|"loads cover"| node_article_photo
node_telegram_adapter -->|"sends messages"| node_telegram_api
node_telegram_users -.->|"sends updates"| node_telegram_api
node_main -->|"syncs commands"| node_bot_commands
node_main -->|"tracks runtime"| node_runtime
node_search_service -->|"fetches documents"| node_crawler
node_search_service -->|"seeds history"| node_job_store
node_search_service -->|"queues and saves"| node_search_store
node_telegram_adapter -->|"registers search"| node_search_bot
node_search_bot -->|"queries index"| node_search_store
node_search_bot -->|"adds archive links"| node_job_store
node_search_bot -->|"uses definitions"| node_bot_commands
node_admin -->|"reads and manages"| node_job_store
node_admin -->|"reads snapshot"| node_runtime
node_operator -->|"manages archives"| node_admin
node_admin -.->|"serves assets"| node_admin_web
node_runtime -->|"reports search status"| node_search_store

click node_main "https://github.com/zytyan/suppbot/blob/main/src/main.ts"
click node_config "https://github.com/zytyan/suppbot/blob/main/src/config.ts"
click node_crawler "https://github.com/zytyan/suppbot/blob/main/src/crawler.ts"
click node_crawl_loop "https://github.com/zytyan/suppbot/blob/main/src/worker.ts"
click node_article_photo "https://github.com/zytyan/suppbot/blob/main/src/article-photo.ts"
click node_job_store "https://github.com/zytyan/suppbot/blob/main/src/store.ts"
click node_worker "https://github.com/zytyan/suppbot/blob/main/src/worker.ts"
click node_qbit "https://github.com/zytyan/suppbot/blob/main/src/qbit.ts"
click node_media "https://github.com/zytyan/suppbot/blob/main/src/media.ts"
click node_telegram_adapter "https://github.com/zytyan/suppbot/blob/main/src/telegram.ts"
click node_search_service "https://github.com/zytyan/suppbot/blob/main/src/search-service.ts"
click node_search_store "https://github.com/zytyan/suppbot/blob/main/src/search-store.ts"
click node_search_bot "https://github.com/zytyan/suppbot/blob/main/src/search-bot.ts"
click node_bot_commands "https://github.com/zytyan/suppbot/blob/main/src/bot-commands.ts"
click node_admin "https://github.com/zytyan/suppbot/blob/main/src/admin.ts"
click node_runtime "https://github.com/zytyan/suppbot/blob/main/src/runtime.ts"
click node_admin_web "https://github.com/zytyan/suppbot/tree/main/web/static"

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_crawler,node_crawl_loop,node_article_photo,node_telegram_users toneBlue
class node_job_store,node_worker,node_qbit,node_media toneAmber
class node_telegram_adapter,node_search_service,node_search_store,node_search_bot,node_bot_commands,node_telegram_api toneMint
class node_main,node_config,node_admin,node_runtime,node_admin_web toneRose
class node_operator,node_article_site toneIndigo
```

## Components

### Article ingestion

- [Article crawler](https://github.com/zytyan/suppbot/blob/main/src/crawler.ts): `src/crawler.ts`
- [Scheduled discovery](https://github.com/zytyan/suppbot/blob/main/src/worker.ts): `src/worker.ts`
- [Cover retrieval](https://github.com/zytyan/suppbot/blob/main/src/article-photo.ts): `src/article-photo.ts`

### Archiving pipeline

- [Archive job store](https://github.com/zytyan/suppbot/blob/main/src/store.ts): `src/store.ts`
- [Job orchestrator](https://github.com/zytyan/suppbot/blob/main/src/worker.ts): `src/worker.ts`
- [Torrent adapter](https://github.com/zytyan/suppbot/blob/main/src/qbit.ts): `src/qbit.ts`
- [Media processing](https://github.com/zytyan/suppbot/blob/main/src/media.ts): `src/media.ts`

### Telegram and search

- [Telegram publishing](https://github.com/zytyan/suppbot/blob/main/src/telegram.ts): `src/telegram.ts`
- [Indexing service](https://github.com/zytyan/suppbot/blob/main/src/search-service.ts): `src/search-service.ts`
- [Search index](https://github.com/zytyan/suppbot/blob/main/src/search-store.ts): `src/search-store.ts`
- [Search commands](https://github.com/zytyan/suppbot/blob/main/src/search-bot.ts): `src/search-bot.ts`
- [Command definitions](https://github.com/zytyan/suppbot/blob/main/src/bot-commands.ts): `src/bot-commands.ts`

### Operations

- [Application startup](https://github.com/zytyan/suppbot/blob/main/src/main.ts): `src/main.ts`
- [Configuration](https://github.com/zytyan/suppbot/blob/main/src/config.ts): `src/config.ts`
- [Admin interface](https://github.com/zytyan/suppbot/blob/main/src/admin.ts): `src/admin.ts`
- [Live runtime state](https://github.com/zytyan/suppbot/blob/main/src/runtime.ts): `src/runtime.ts`
- [Admin page assets](https://github.com/zytyan/suppbot/tree/main/web/static): `web/static`

### Other components

- **Operator**
- **Telegram users**
- **Article site**
- **Telegram Bot API**

## Connections

- Operator → Application startup: starts service (evidence: `README.md`)
- Application startup → Configuration: loads config (evidence: `src/main.ts`)
- Application startup → Archive job store: initializes (evidence: `src/main.ts`)
- Application startup → Job orchestrator: starts workers (evidence: `src/main.ts`)
- Application startup → Scheduled discovery: starts crawl (evidence: `src/main.ts`)
- Application startup → Indexing service: starts indexing (evidence: `src/main.ts`)
- Application startup → Telegram publishing: creates bot (evidence: `src/main.ts`)
- Application startup → Admin interface: starts server (evidence: `README.md`)
- Scheduled discovery → Article crawler: fetches articles (evidence: `src/worker.ts`)
- Scheduled discovery → Archive job store: queues articles (evidence: `src/worker.ts`)
- Article crawler → Article site: fetches pages (evidence: `src/crawler.ts`)
- Job orchestrator → Archive job store: claims and updates (evidence: `src/worker.ts`)
- Job orchestrator → Article crawler: recovers articles (evidence: `src/worker.ts`)
- Job orchestrator → Torrent adapter: downloads torrents
- Job orchestrator → Media processing: processes files
- Job orchestrator → Telegram publishing: publishes archive (evidence: `src/worker.ts`)
- Telegram publishing → Cover retrieval: loads cover (evidence: `src/telegram.ts`)
- Telegram publishing → Telegram Bot API: sends messages (evidence: `src/telegram.ts`)
- Telegram users → Telegram Bot API: sends updates
- Application startup → Command definitions: syncs commands (evidence: `src/main.ts`)
- Application startup → Live runtime state: tracks runtime (evidence: `src/main.ts`)
- Indexing service → Article crawler: fetches documents (evidence: `src/search-service.ts`)
- Indexing service → Archive job store: seeds history (evidence: `src/search-service.ts`)
- Indexing service → Search index: queues and saves (evidence: `src/search-service.ts`)
- Telegram publishing → Search commands: registers search (evidence: `src/telegram.ts`)
- Search commands → Search index: queries index (evidence: `src/search-bot.ts`)
- Search commands → Archive job store: adds archive links (evidence: `src/search-bot.ts`)
- Search commands → Command definitions: uses definitions (evidence: `src/search-bot.ts`)
- Admin interface → Archive job store: reads and manages (evidence: `src/admin.ts`)
- Admin interface → Live runtime state: reads snapshot (evidence: `src/admin.ts`)
- Operator → Admin interface: manages archives (evidence: `README.md`)
- Admin interface → Admin page assets: serves assets
- Live runtime state → Search index: reports search status (evidence: `src/runtime.ts`)