# botwalain/wholesomecitybot architecture

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

- Interactive diagram: https://gitdiagram.com/botwalain/wholesomecitybot
- Repository: https://github.com/botwalain/wholesomecitybot

## Overview

Lucia is a Telegram auto-filter bot: users search for a movie or series in chat or private messages, receive paginated file matches, then request a file; group owners configure search and access settings. Admins and moderators also index files, manage users and groups, and operate premium plans. The README additionally describes dual-database failover, subscription checks, streaming, trending and referral features. Edges reflect shown imports/calls or README descriptions; several plugin and storage behaviors are unsampled, so their internal links are omitted.

Main entry points: [`plugins/commands.py`](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/commands.py) (Commands), [`database/users_chats_db.py`](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/database/users_chats_db.py) (User And Group Store), [`bot.py`](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/bot.py) (Bot Startup), [`database/ia_filterdb.py`](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/database/ia_filterdb.py) (File Catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_entry["Bot Startup<br/>[bot.py]"]
  node_client["Bot Client<br/>[__init__.py]"]
  node_multi["Client Pool<br/>[clients.py]"]
  node_config["Bot Configuration<br/>[info.py]"]
  node_templates["Message Templates<br/>[Script.py]"]
end

subgraph group_search["File Search"]
  node_search_flow["Search Handler<br/>[pm_filter.py]"]
  node_indexing["File Indexing<br/>[index.py]"]
  node_file_props["File Metadata<br/>[file_properties.py]"]
end

subgraph group_data["Storage And Accounts"]
  node_file_catalog[("File Catalog<br/>[ia_filterdb.py]")]
  node_user_store[("User And Group Store<br/>[users_chats_db.py]")]
  node_referrals[("Referrals<br/>[refer.py]")]
  node_trends[("Search Trends<br/>[topdb.py]")]
end

subgraph group_features["Bot Features"]
  node_commands["Commands<br/>[commands.py]"]
  node_premium["Premium Plans<br/>[Premium.py]"]
  node_settings["Group Settings<br/>[settings.py]"]
  node_subscription["Subscription Checks<br/>[fsub_helper.py]"]
  node_streaming["Streaming And Download<br/>[route.py]"]
  node_stream_helper["Download Helper<br/>[custom_dl.py]"]
  node_verification["Verification<br/>[license.py]"]
  node_channels["Channel Features<br/>[channel.py]"]
  node_broadcast["Broadcast Admin<br/>[broadcast.py]"]
  node_misc["Utility Commands<br/>[misc.py]"]
end

node_telegram_user(("Telegram User"))
node_telegram(("Telegram API"))

node_telegram_user -->|"sends requests"| node_client
node_entry -->|"starts"| node_client
node_entry -->|"initializes clients"| node_multi
node_entry -->|"loads"| node_file_catalog
node_entry -->|"loads"| node_user_store
node_entry -->|"reads settings"| node_config
node_client -->|"registers plugins"| node_commands
node_client -->|"uses API"| node_telegram
node_search_flow -->|"searches files"| node_file_catalog
node_search_flow -->|"reads settings"| node_user_store
node_search_flow -->|"formats replies"| node_templates
node_indexing -->|"indexes files"| node_file_catalog
node_commands -->|"delegates queries"| node_search_flow
node_commands -->|"checks access"| node_subscription
node_commands -->|"uses referral data"| node_referrals
node_commands -->|"uses trend data"| node_trends
node_commands -->|"manages files"| node_file_catalog
node_commands -->|"manages accounts"| node_user_store
node_commands -->|"opens settings"| node_settings
node_premium -->|"updates plans"| node_user_store
node_settings -->|"stores settings"| node_user_store
node_streaming -->|"uses downloader"| node_stream_helper
node_streaming -.->|"serves media"| node_telegram
node_file_props -->|"reads media"| node_telegram
node_verification -->|"checks account status"| node_user_store
node_channels -->|"uses file catalog"| node_file_catalog
node_broadcast -->|"loads recipients"| node_user_store
node_misc -.->|"handles commands"| node_telegram
node_config -->|"imports text"| node_templates

click node_entry "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/bot.py"
click node_client "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/Lucia/Bot/__init__.py"
click node_multi "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/Lucia/Bot/clients.py"
click node_commands "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/commands.py"
click node_search_flow "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/pm_filter.py"
click node_indexing "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/index.py"
click node_file_catalog "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/database/ia_filterdb.py"
click node_user_store "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/database/users_chats_db.py"
click node_referrals "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/database/refer.py"
click node_trends "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/database/topdb.py"
click node_premium "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/Premium.py"
click node_settings "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/settings.py"
click node_subscription "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/fsub_helper.py"
click node_streaming "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/route.py"
click node_stream_helper "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/Lucia/util/custom_dl.py"
click node_file_props "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/Lucia/util/file_properties.py"
click node_verification "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/license.py"
click node_channels "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/channel.py"
click node_broadcast "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/broadcast.py"
click node_misc "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/misc.py"
click node_config "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/info.py"
click node_templates "https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/Script.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_entry,node_client,node_multi,node_config,node_templates,node_telegram_user toneBlue
class node_search_flow,node_indexing,node_file_props toneAmber
class node_file_catalog,node_user_store,node_referrals,node_trends,node_telegram toneMint
class node_commands,node_premium,node_settings,node_subscription,node_streaming,node_stream_helper,node_verification,node_channels,node_broadcast,node_misc toneRose
```

## Components

### Bot Runtime

- [Bot Startup](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/bot.py): `bot.py`
- [Bot Client](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/Lucia/Bot/__init__.py): `Lucia/Bot/__init__.py`
- [Client Pool](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/Lucia/Bot/clients.py): `Lucia/Bot/clients.py`
- [Bot Configuration](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/info.py): `info.py`
- [Message Templates](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/Script.py): `Script.py`

### File Search

- [Search Handler](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/pm_filter.py): `plugins/pm_filter.py`
- [File Indexing](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/index.py): `plugins/index.py`
- [File Metadata](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/Lucia/util/file_properties.py): `Lucia/util/file_properties.py`

### Storage And Accounts

- [File Catalog](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/database/ia_filterdb.py): `database/ia_filterdb.py`
- [User And Group Store](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/database/users_chats_db.py): `database/users_chats_db.py`
- [Referrals](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/database/refer.py): `database/refer.py`
- [Search Trends](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/database/topdb.py): `database/topdb.py`

### Bot Features

- [Commands](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/commands.py): `plugins/commands.py`
- [Premium Plans](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/Premium.py): `plugins/Premium.py`
- [Group Settings](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/settings.py): `plugins/settings.py`
- [Subscription Checks](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/fsub_helper.py): `plugins/fsub_helper.py`
- [Streaming And Download](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/route.py): `plugins/route.py`
- [Download Helper](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/Lucia/util/custom_dl.py): `Lucia/util/custom_dl.py`
- [Verification](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/license.py): `plugins/license.py`
- [Channel Features](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/channel.py): `plugins/channel.py`
- [Broadcast Admin](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/broadcast.py): `plugins/broadcast.py`
- [Utility Commands](https://github.com/botwalain/wholesomecitybot/blob/SilentXBotz/plugins/misc.py): `plugins/misc.py`

### Other components

- **Telegram User**
- **Telegram API**

## Connections

- Telegram User → Bot Client: sends requests (evidence: `README.md`)
- Bot Startup → Bot Client: starts (evidence: `bot.py`)
- Bot Startup → Client Pool: initializes clients (evidence: `bot.py`)
- Bot Startup → File Catalog: loads (evidence: `bot.py`)
- Bot Startup → User And Group Store: loads (evidence: `bot.py`)
- Bot Startup → Bot Configuration: reads settings (evidence: `bot.py`)
- Bot Client → Commands: registers plugins (evidence: `Lucia/Bot/__init__.py`)
- Bot Client → Telegram API: uses API (evidence: `Lucia/Bot/__init__.py`)
- Search Handler → File Catalog: searches files (evidence: `plugins/pm_filter.py`)
- Search Handler → User And Group Store: reads settings (evidence: `plugins/pm_filter.py`)
- Search Handler → Message Templates: formats replies (evidence: `plugins/pm_filter.py`)
- File Indexing → File Catalog: indexes files (evidence: `plugins/index.py`)
- Commands → Search Handler: delegates queries (evidence: `plugins/commands.py`)
- Commands → Subscription Checks: checks access (evidence: `plugins/commands.py`)
- Commands → Referrals: uses referral data (evidence: `plugins/commands.py`)
- Commands → Search Trends: uses trend data (evidence: `plugins/commands.py`)
- Commands → File Catalog: manages files (evidence: `plugins/commands.py`)
- Commands → User And Group Store: manages accounts (evidence: `plugins/commands.py`)
- Commands → Group Settings: opens settings (evidence: `README.md`)
- Premium Plans → User And Group Store: updates plans (evidence: `plugins/Premium.py`)
- Group Settings → User And Group Store: stores settings (evidence: `plugins/settings.py`)
- Streaming And Download → Download Helper: uses downloader (evidence: `plugins/route.py`)
- Streaming And Download → Telegram API: serves media
- File Metadata → Telegram API: reads media (evidence: `Lucia/util/file_properties.py`)
- Verification → User And Group Store: checks account status (evidence: `plugins/license.py`)
- Channel Features → File Catalog: uses file catalog (evidence: `plugins/channel.py`)
- Broadcast Admin → User And Group Store: loads recipients (evidence: `plugins/broadcast.py`)
- Utility Commands → Telegram API: handles commands
- Bot Configuration → Message Templates: imports text (evidence: `info.py`)