hiddify/hiddify-telegram-bot

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.