# xiaoqvan/xqanimebot architecture

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

- Interactive diagram: https://gitdiagram.com/xiaoqvan/xqanimebot
- Repository: https://github.com/xiaoqvan/xqanimebot

## Overview

这是一个接入 TDLib 的动漫管理与自动收录机器人插件：启动后轮询多个 RSS 源，合并过滤条目并排队处理种子；随后匹配动漫及集数、下载并发布视频，必要时请求管理员补充或确认信息。机器人也提供动漫搜索、Bangumi 账户绑定和管理命令。分组涵盖消息入口、收录处理、元数据与持久化、下载和外部服务。README 为空；未采样的模块仅按目录和入口注册信息概括，未推断其内部调用。

Main entry points: [`anime/animeHandlers.ts`](https://github.com/xiaoqvan/xqanimebot/blob/main/anime/animeHandlers.ts) (Anime processing), [`index.ts`](https://github.com/xiaoqvan/xqanimebot/blob/main/index.ts) (Plugin handlers), [`database/query.ts`](https://github.com/xiaoqvan/xqanimebot/blob/main/database/query.ts) (Database queries), [`anime/rss/index.ts`](https://github.com/xiaoqvan/xqanimebot/blob/main/anime/rss/index.ts) (RSS aggregation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Bot entry"]
  node_plugin["Plugin handlers<br/>[index.ts]"]
  node_commands["Bot commands"]
  node_callbacks["Callback handler<br/>[index.ts]"]
end

subgraph group_ingest["Anime ingestion"]
  node_anime_runtime["Anime runtime<br/>[index.ts]"]
  node_rss_aggregator["RSS aggregation<br/>[index.ts]"]
  node_task_manager["Task queue"]
  node_item_handler["RSS item handling<br/>[rssItemHandler.ts]"]
  node_anime_handlers["Anime processing<br/>[animeHandlers.ts]"]
  node_admin_prompts["Admin prompts<br/>[adminPrompts.ts]"]
end

subgraph group_catalog["Catalog and state"]
  node_anime_search["Anime lookup<br/>[get.ts]"]
  node_matching["Episode matching<br/>[matcher.ts]"]
  node_db_queries["Database queries<br/>[query.ts]"]
  node_db_writes["Database writes"]
end

subgraph group_integrations["External integrations"]
  node_rss_sources["RSS source fetchers"]
  node_mongo[("MongoDB")]
  node_bangumi["Bangumi service"]
  node_telegram["Telegram / TDLib"]
  node_qb_download["Torrent operations<br/>[download.ts]"]
  node_qb_client["qBittorrent client<br/>[client.ts]"]
end

node_telegram_user(("Telegram user"))
node_rss_network(("RSS feeds"))

node_telegram_user -->|"sends commands"| node_plugin
node_plugin -->|"dispatches commands"| node_commands
node_plugin -->|"dispatches updates"| node_callbacks
node_plugin -->|"starts runtime"| node_anime_runtime
node_anime_runtime -->|"polls feeds"| node_rss_aggregator
node_rss_aggregator -->|"fetches feeds"| node_rss_sources
node_rss_network -->|"provides items"| node_rss_sources
node_rss_aggregator -->|"reads blacklist"| node_db_queries
node_task_manager -->|"checks duplicates"| node_db_queries
node_task_manager -->|"dispatches items"| node_item_handler
node_item_handler -->|"processes item"| node_anime_handlers
node_anime_handlers -->|"searches metadata"| node_anime_search
node_anime_handlers -->|"matches episode"| node_matching
node_anime_handlers -->|"saves records"| node_db_writes
node_anime_handlers -->|"manages torrent"| node_qb_download
node_anime_handlers -->|"requests review"| node_admin_prompts
node_admin_prompts -->|"sends prompts"| node_telegram
node_anime_handlers -->|"publishes video"| node_telegram
node_callbacks -->|"handles callbacks"| node_telegram
node_commands -->|"searches catalog"| node_db_queries
node_db_queries -->|"queries collections"| node_mongo
node_db_writes -->|"writes collections"| node_mongo
node_qb_download -->|"uses API client"| node_qb_client
node_qb_client -.-> node_mongo

click node_plugin "https://github.com/xiaoqvan/xqanimebot/blob/main/index.ts"
click node_commands "https://github.com/xiaoqvan/xqanimebot/tree/main/cmd"
click node_callbacks "https://github.com/xiaoqvan/xqanimebot/blob/main/CallbackQuery/index.ts"
click node_anime_runtime "https://github.com/xiaoqvan/xqanimebot/blob/main/anime/index.ts"
click node_rss_aggregator "https://github.com/xiaoqvan/xqanimebot/blob/main/anime/rss/index.ts"
click node_rss_sources "https://github.com/xiaoqvan/xqanimebot/tree/main/anime/rss"
click node_task_manager "https://github.com/xiaoqvan/xqanimebot/blob/main/anime/AnimeProcessorManager.ts"
click node_item_handler "https://github.com/xiaoqvan/xqanimebot/blob/main/anime/rssItemHandler.ts"
click node_anime_handlers "https://github.com/xiaoqvan/xqanimebot/blob/main/anime/animeHandlers.ts"
click node_admin_prompts "https://github.com/xiaoqvan/xqanimebot/blob/main/anime/adminPrompts.ts"
click node_anime_search "https://github.com/xiaoqvan/xqanimebot/blob/main/anime/get.ts"
click node_matching "https://github.com/xiaoqvan/xqanimebot/blob/main/utils/matcher.ts"
click node_db_queries "https://github.com/xiaoqvan/xqanimebot/blob/main/database/query.ts"
click node_db_writes "https://github.com/xiaoqvan/xqanimebot/tree/main/database"
click node_qb_download "https://github.com/xiaoqvan/xqanimebot/blob/main/qBittorrent/download.ts"
click node_qb_client "https://github.com/xiaoqvan/xqanimebot/blob/main/qBittorrent/client.ts"

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_commands,node_callbacks,node_telegram_user toneBlue
class node_anime_runtime,node_rss_aggregator,node_task_manager,node_item_handler,node_anime_handlers,node_admin_prompts toneAmber
class node_anime_search,node_matching,node_db_queries,node_db_writes toneMint
class node_rss_sources,node_mongo,node_bangumi,node_telegram,node_qb_download,node_qb_client toneRose
class node_rss_network toneIndigo
```

## Components

### Bot entry

- [Plugin handlers](https://github.com/xiaoqvan/xqanimebot/blob/main/index.ts): `index.ts`
- [Bot commands](https://github.com/xiaoqvan/xqanimebot/tree/main/cmd): `cmd`
- [Callback handler](https://github.com/xiaoqvan/xqanimebot/blob/main/CallbackQuery/index.ts): `CallbackQuery/index.ts`

### Anime ingestion

- [Anime runtime](https://github.com/xiaoqvan/xqanimebot/blob/main/anime/index.ts): `anime/index.ts`
- [RSS aggregation](https://github.com/xiaoqvan/xqanimebot/blob/main/anime/rss/index.ts): `anime/rss/index.ts`
- [Task queue](https://github.com/xiaoqvan/xqanimebot/blob/main/anime/AnimeProcessorManager.ts): `anime/AnimeProcessorManager.ts`
- [RSS item handling](https://github.com/xiaoqvan/xqanimebot/blob/main/anime/rssItemHandler.ts): `anime/rssItemHandler.ts`
- [Anime processing](https://github.com/xiaoqvan/xqanimebot/blob/main/anime/animeHandlers.ts): `anime/animeHandlers.ts`
- [Admin prompts](https://github.com/xiaoqvan/xqanimebot/blob/main/anime/adminPrompts.ts): `anime/adminPrompts.ts`

### Catalog and state

- [Anime lookup](https://github.com/xiaoqvan/xqanimebot/blob/main/anime/get.ts): `anime/get.ts`
- [Episode matching](https://github.com/xiaoqvan/xqanimebot/blob/main/utils/matcher.ts): `utils/matcher.ts`
- [Database queries](https://github.com/xiaoqvan/xqanimebot/blob/main/database/query.ts): `database/query.ts`
- [Database writes](https://github.com/xiaoqvan/xqanimebot/tree/main/database): `database`

### External integrations

- [RSS source fetchers](https://github.com/xiaoqvan/xqanimebot/tree/main/anime/rss): `anime/rss`
- **MongoDB**
- **Bangumi service**
- **Telegram / TDLib**
- [Torrent operations](https://github.com/xiaoqvan/xqanimebot/blob/main/qBittorrent/download.ts): `qBittorrent/download.ts`
- [qBittorrent client](https://github.com/xiaoqvan/xqanimebot/blob/main/qBittorrent/client.ts): `qBittorrent/client.ts`

### Other components

- **Telegram user**
- **RSS feeds**

## Connections

- Telegram user → Plugin handlers: sends commands
- Plugin handlers → Bot commands: dispatches commands
- Plugin handlers → Callback handler: dispatches updates
- Plugin handlers → Anime runtime: starts runtime
- Anime runtime → RSS aggregation: polls feeds
- RSS aggregation → RSS source fetchers: fetches feeds
- RSS feeds → RSS source fetchers: provides items
- RSS aggregation → Database queries: reads blacklist
- Task queue → Database queries: checks duplicates
- Task queue → RSS item handling: dispatches items
- RSS item handling → Anime processing: processes item
- Anime processing → Anime lookup: searches metadata
- Anime processing → Episode matching: matches episode
- Anime processing → Database writes: saves records
- Anime processing → Torrent operations: manages torrent
- Anime processing → Admin prompts: requests review
- Admin prompts → Telegram / TDLib: sends prompts
- Anime processing → Telegram / TDLib: publishes video
- Callback handler → Telegram / TDLib: handles callbacks
- Bot commands → Database queries: searches catalog
- Database queries → MongoDB: queries collections
- Database writes → MongoDB: writes collections
- Torrent operations → qBittorrent client: uses API client
- qBittorrent client → MongoDB