# hiddify/hiddify-telegram-bot architecture

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

- Interactive diagram: https://gitdiagram.com/hiddify/hiddify-telegram-bot
- Repository: https://github.com/hiddify/hiddify-telegram-bot

## Overview

1. This repository is a Python-based Telegram bot system for managing Hiddify panels. The architecture is split into two user-facing bots plus support services for panel access, persistence, scheduling, and deployment.

2. The main runtime entrypoint is `hiddifyTelegramBot.py`, which likely boots the overall application and coordinates bot startup. The codebase is organized as a set of modules rather than a single monolith, with clear separation between admin features, end-user features, and shared infrastructure.

3. There are two distinct bot subsystems: `AdminBot/` and `UserBot/`. Each has its own `bot.py`, `content.py`, `markups.py`, `templates.py`, and JSON message/command/button definitions. That structure suggests the project supports two different Telegram personas with different menus, localized text, and interaction flows.

4. The `AdminBot` side is the control plane. From the README and filenames, it handles panel administration tasks such as adding/removing users, editing user details, searching users, viewing statistics, selling configs, and generating backups. The `UserBot` side is the customer-facing plane, likely focused on subscription lookup, config display, and user self-service actions.

5. Shared logic lives in `Shared/common.py`, which is the likely boundary for code reused by both bots. This is where cross-cutting concerns such as helpers, role checks, formatting, or shared Telegram/UI utilities would be centralized to avoid duplication between admin and user flows.

6. The Hiddify panel integration is isolated in `Utils/api.py` and `Utils/serverInfo.py`. This layer is the bridge to the external Hiddify system and server metrics, so architecture-wise it represents the main outbound dependency: bot actions translate into panel API calls and status queries rather than direct business logic inside the handlers.

7. Persistence is handled by `Database/dbManager.py`. That module is the repository’s state boundary and likely stores bot configuration, panel metadata, user mappings, language settings, and other operational records needed across restarts. The presence of a dedicated database layer indicates the bots are not stateless.

8. Background automation is implemented under `Cronjob/`, with `backup.py`, `backupBot.py`, and `reminder.py`. This is the asynchronous side of the system: scheduled backups, automatic delivery of backups or notifications, and reminder workflows run separately from the interactive Telegram update loop.

9. The repository also contains `config.py`, `version.py`, and the `*_templates.py` / JSON files that define content and translations. That points to a configuration-and-content-driven design, where runtime behavior is parameterized by admin setup and user-facing text is externalized for English/Persian support.

10. Operationally, the shell scripts (`install.sh`, `update.sh`, `restart.sh`, `uninstall.sh`) and `crontab.py` show that the project is intended to be installed and managed on a server, likely as a long-running service with scheduled jobs. `update.py` suggests in-place upgrade support, while log retrieval in the README implies file-based operational logging.

11. From an architecture diagram perspective, the key flows are: Telegram users interact with either admin or user bot → handlers route through shared helpers and content templates → bot logic calls the Hiddify API layer and/or database → scheduled cron jobs run backup and reminder workflows independently → deployment scripts manage lifecycle and updates.

12. The main external boundary is Telegram itself on the inbound side and the Hiddify panel on the outbound side. Everything else in the repo supports mediation between those two systems: message routing, localization, configuration, persistence, and scheduled automation.

Main entry points: [`AdminBot/bot.py`](https://github.com/hiddify/hiddify-telegram-bot/blob/main/AdminBot/bot.py) (Admin bot), [`UserBot/bot.py`](https://github.com/hiddify/hiddify-telegram-bot/blob/main/UserBot/bot.py) (User bot), [`Database/dbManager.py`](https://github.com/hiddify/hiddify-telegram-bot/blob/main/Database/dbManager.py) (Database), [`Shared/common.py`](https://github.com/hiddify/hiddify-telegram-bot/blob/main/Shared/common.py) (Common core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bots["Bots"]
  node_admin_bot["Admin bot<br/>telegram control plane<br/>[bot.py]"]
  node_admin_content["Admin content<br/>ui content<br/>[content.py]"]
  node_admin_markups["Admin markups<br/>ui layouts<br/>[markups.py]"]
  node_admin_templates["Admin templates<br/>message templates<br/>[templates.py]"]
  node_user_bot["User bot<br/>telegram client plane<br/>[bot.py]"]
  node_user_content["User content<br/>ui content<br/>[content.py]"]
  node_user_markups["User markups<br/>ui layouts<br/>[markups.py]"]
  node_user_templates["User templates<br/>message templates<br/>[templates.py]"]
end

subgraph group_shared["Shared Core"]
  node_entrypoint["Main app<br/>runtime entrypoint"]
  node_common["Common core<br/>shared helpers<br/>[common.py]"]
  node_api["Hiddify API<br/>panel integration<br/>[api.py]"]
  node_server_info["Server info<br/>metrics bridge<br/>[serverInfo.py]"]
  node_utils["Utilities<br/>helper library<br/>[utils.py]"]
  node_db[("Database<br/>persistence layer<br/>[dbManager.py]")]
  node_config["Config<br/>[config.py]"]
end

subgraph group_ops["Operations"]
  node_cron_backup["Backups<br/>scheduled jobs<br/>[backup.py]"]
  node_cron_backup_bot["Backup bot<br/>automation worker<br/>[backupBot.py]"]
  node_cron_reminder["Reminders<br/>scheduled jobs<br/>[reminder.py]"]
  node_crontab["Crontab<br/>scheduler setup<br/>[crontab.py]"]
  node_update["Updater<br/>deployment script<br/>[update.py]"]
end

node_entrypoint -->|"starts"| node_admin_bot
node_entrypoint -->|"starts"| node_user_bot
node_admin_bot -->|"uses"| node_common
node_user_bot -->|"uses"| node_common
node_admin_bot -->|"renders"| node_admin_content
node_admin_bot -->|"builds UI"| node_admin_markups
node_admin_bot -->|"formats"| node_admin_templates
node_user_bot -->|"renders"| node_user_content
node_user_bot -->|"builds UI"| node_user_markups
node_user_bot -->|"formats"| node_user_templates
node_admin_bot -->|"calls"| node_api
node_user_bot -->|"calls"| node_api
node_admin_bot -->|"reads/writes"| node_db
node_user_bot -->|"reads/writes"| node_db
node_api -->|"queries"| node_server_info
node_common -->|"uses"| node_utils
node_common -->|"reads"| node_config
node_cron_backup -->|"reads/writes"| node_db
node_cron_backup -->|"calls"| node_api
node_cron_backup_bot -->|"drives"| node_cron_backup
node_cron_reminder -->|"reads"| node_db
node_crontab -->|"schedules"| node_cron_backup
node_crontab -->|"schedules"| node_cron_reminder
node_update -->|"reads"| node_config
node_update -->|"migrates"| node_db

click node_entrypoint "https://github.com/hiddify/hiddify-telegram-bot/blob/main/hiddifyTelegramBot.py"
click node_admin_bot "https://github.com/hiddify/hiddify-telegram-bot/blob/main/AdminBot/bot.py"
click node_admin_content "https://github.com/hiddify/hiddify-telegram-bot/blob/main/AdminBot/content.py"
click node_admin_markups "https://github.com/hiddify/hiddify-telegram-bot/blob/main/AdminBot/markups.py"
click node_admin_templates "https://github.com/hiddify/hiddify-telegram-bot/blob/main/AdminBot/templates.py"
click node_user_bot "https://github.com/hiddify/hiddify-telegram-bot/blob/main/UserBot/bot.py"
click node_user_content "https://github.com/hiddify/hiddify-telegram-bot/blob/main/UserBot/content.py"
click node_user_markups "https://github.com/hiddify/hiddify-telegram-bot/blob/main/UserBot/markups.py"
click node_user_templates "https://github.com/hiddify/hiddify-telegram-bot/blob/main/UserBot/templates.py"
click node_common "https://github.com/hiddify/hiddify-telegram-bot/blob/main/Shared/common.py"
click node_api "https://github.com/hiddify/hiddify-telegram-bot/blob/main/Utils/api.py"
click node_server_info "https://github.com/hiddify/hiddify-telegram-bot/blob/main/Utils/serverInfo.py"
click node_utils "https://github.com/hiddify/hiddify-telegram-bot/blob/main/Utils/utils.py"
click node_db "https://github.com/hiddify/hiddify-telegram-bot/blob/main/Database/dbManager.py"
click node_config "https://github.com/hiddify/hiddify-telegram-bot/blob/main/config.py"
click node_cron_backup "https://github.com/hiddify/hiddify-telegram-bot/blob/main/Cronjob/backup.py"
click node_cron_backup_bot "https://github.com/hiddify/hiddify-telegram-bot/blob/main/Cronjob/backupBot.py"
click node_cron_reminder "https://github.com/hiddify/hiddify-telegram-bot/blob/main/Cronjob/reminder.py"
click node_crontab "https://github.com/hiddify/hiddify-telegram-bot/blob/main/crontab.py"
click node_update "https://github.com/hiddify/hiddify-telegram-bot/blob/main/update.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_admin_bot,node_admin_content,node_admin_markups,node_admin_templates,node_user_bot,node_user_content,node_user_markups,node_user_templates toneBlue
class node_entrypoint,node_common,node_api,node_server_info,node_utils,node_db,node_config toneAmber
class node_cron_backup,node_cron_backup_bot,node_cron_reminder,node_crontab,node_update toneMint
```

## Components

### Bots

Interactive Telegram bot subsystems for admins and end users.

- [Admin bot](https://github.com/hiddify/hiddify-telegram-bot/blob/main/AdminBot/bot.py): telegram control plane · Administrator-facing bot runtime and command routing. · `AdminBot/bot.py`
- [Admin content](https://github.com/hiddify/hiddify-telegram-bot/blob/main/AdminBot/content.py): ui content · Admin-side text, templates, and presentation helpers. · `AdminBot/content.py`
- [Admin markups](https://github.com/hiddify/hiddify-telegram-bot/blob/main/AdminBot/markups.py): ui layouts · Admin-side Telegram keyboard and menu layouts. · `AdminBot/markups.py`
- [Admin templates](https://github.com/hiddify/hiddify-telegram-bot/blob/main/AdminBot/templates.py): message templates · Admin-side templated messages and reusable responses. · `AdminBot/templates.py`
- [User bot](https://github.com/hiddify/hiddify-telegram-bot/blob/main/UserBot/bot.py): telegram client plane · Customer-facing bot runtime and self-service flows. · `UserBot/bot.py`
- [User content](https://github.com/hiddify/hiddify-telegram-bot/blob/main/UserBot/content.py): ui content · User-facing text, templates, and presentation helpers. · `UserBot/content.py`
- [User markups](https://github.com/hiddify/hiddify-telegram-bot/blob/main/UserBot/markups.py): ui layouts · User-facing Telegram keyboard and menu layouts. · `UserBot/markups.py`
- [User templates](https://github.com/hiddify/hiddify-telegram-bot/blob/main/UserBot/templates.py): message templates · User-facing templated messages and reusable responses. · `UserBot/templates.py`

### Shared Core

Common helpers, configuration, persistence, and Hiddify integration.

- [Main app](https://github.com/hiddify/hiddify-telegram-bot/blob/main/hiddifyTelegramBot.py): runtime entrypoint · Bootstraps the overall Telegram bot application. · `hiddifyTelegramBot.py`
- [Common core](https://github.com/hiddify/hiddify-telegram-bot/blob/main/Shared/common.py): shared helpers · Shared logic reused by both bot subsystems. · `Shared/common.py`
- [Hiddify API](https://github.com/hiddify/hiddify-telegram-bot/blob/main/Utils/api.py): panel integration · Outbound bridge to the Hiddify panel and related actions. · `Utils/api.py`
- [Server info](https://github.com/hiddify/hiddify-telegram-bot/blob/main/Utils/serverInfo.py): metrics bridge · Collects server and panel status information used by the bots. · `Utils/serverInfo.py`
- [Utilities](https://github.com/hiddify/hiddify-telegram-bot/blob/main/Utils/utils.py): helper library · General-purpose utility functions shared across the repository. · `Utils/utils.py`
- [Database](https://github.com/hiddify/hiddify-telegram-bot/blob/main/Database/dbManager.py): persistence layer · Persistent state boundary for bot and panel data. · `Database/dbManager.py`
- [Config](https://github.com/hiddify/hiddify-telegram-bot/blob/main/config.py): runtime config · Central configuration for bot behavior and deployment settings. · `config.py`

### Operations

Scheduled jobs and deployment scripts that run the service.

- [Backups](https://github.com/hiddify/hiddify-telegram-bot/blob/main/Cronjob/backup.py): scheduled jobs · Backup generation and backup delivery workflows. · `Cronjob/backup.py`
- [Backup bot](https://github.com/hiddify/hiddify-telegram-bot/blob/main/Cronjob/backupBot.py): automation worker · Bot-assisted backup automation and notification flow. · `Cronjob/backupBot.py`
- [Reminders](https://github.com/hiddify/hiddify-telegram-bot/blob/main/Cronjob/reminder.py): scheduled jobs · Reminder and notification workflows run on a schedule. · `Cronjob/reminder.py`
- [Crontab](https://github.com/hiddify/hiddify-telegram-bot/blob/main/crontab.py): scheduler setup · Scheduler configuration and job wiring for the server runtime. · `crontab.py`
- [Updater](https://github.com/hiddify/hiddify-telegram-bot/blob/main/update.py): deployment script · In-place update support for the deployed service. · `update.py`

## Connections

- Main app → Admin bot: starts · Bootstraps the admin-facing runtime.
- Main app → User bot: starts · Bootstraps the user-facing runtime.
- Admin bot → Common core: uses · Shares cross-cutting helpers and checks.
- User bot → Common core: uses · Shares cross-cutting helpers and checks.
- Admin bot → Admin content: renders · Uses admin text and response content.
- Admin bot → Admin markups: builds UI · Uses admin keyboard layouts and menus.
- Admin bot → Admin templates: formats · Uses admin message templates.
- User bot → User content: renders · Uses user-facing text and response content.
- User bot → User markups: builds UI · Uses user keyboard layouts and menus.
- User bot → User templates: formats · Uses user message templates.
- Admin bot → Hiddify API: calls · Executes panel administration actions through the API layer.
- User bot → Hiddify API: calls · Executes user-facing panel lookups and actions.
- Admin bot → Database: reads/writes · Stores admin state and operational records.
- User bot → Database: reads/writes · Stores user mappings and runtime state.
- Hiddify API → Server info: queries · Uses server status and metrics during panel operations.
- Common core → Utilities: uses · Depends on shared utility functions.
- Common core → Config: reads · Loads shared runtime configuration.
- Backups → Database: reads/writes · Backups use persisted configuration and state.
- Backups → Hiddify API: calls · Backup workflows may interact with the panel layer.
- Backup bot → Backups: drives · Coordinates backup automation and delivery.
- Reminders → Database: reads · Reminder jobs use stored schedules and recipients.
- Crontab → Backups: schedules · Registers backup jobs with the server scheduler.
- Crontab → Reminders: schedules · Registers reminder jobs with the server scheduler.
- Updater → Config: reads · Uses configuration during deployment updates.
- Updater → Database: migrates · May update persisted state during upgrades.