How silentdemonsd/wzml-x works
Project Type and Purpose
• The project is a Telegram bot (using the Pyrogram framework) designed to mirror/clone files from online and local sources to cloud storage (Google Drive, rclone-supported clouds, DDL sites, and Telegram itself). It integrates with several external services (like qBittorrent, Aria2, yt-dlp, etc.) to handle downloads and uploads.
• The README shows an extensive feature set including torrent support, mirror/leech functionality, Google Drive API integration, and a web component for file selection (as seen in the “web” directory). There is also robust support for Dockerized deployment.
Analysis of the File Structure
• Top-Level Files/Directories:
– Configuration and deployment files: Dockerfile, docker-compose.yml, config_sample.env, start.sh.
– The “bot” directory forms the core of the Telegram bot. Its structure is broken out into several subdirectories:
▪ "bot/helper" – Contains utility modules grouped into:
• ext_utils: Contains helper functions for tasks like database handling, file system operations, task management, and even telegraph helper functions.
• listeners: Contains listeners for download events (for Aria2, qBittorrent, etc.) and task monitoring.
• mirror_utils: Contains modules for actual download logic (using Aria2, direct downloads, GD download, Mega download, etc.), rclone utilities, status utilities, and upload utilities.
• telegram_helper: Contains logic for command handling, buttons, message formatting, and filters for Telegram messages.
• themes: Contains files that help customize the bot’s look and feel (user interface elements).
– "bot/modules": Contains the discrete command modules such as mirror, leech, clone, status, cancel, RSS, etc. These modules are called when Telegram commands are received.
– "web": Contains a web service component (with nodes and a simple web server) that likely serves as an auxiliary UI for tasks like file selection.
– Additional infrastructure scripts (like add_to_team_drive.py, driveid.py) assist with supplementary tasks such as team drive integration.
a. Main Components:
• Telegram Bot Interface:
– The central entry point (bot/__main__.py) receives Telegram commands via Pyrogram.
• Command Handler Modules:
– Located in bot/modules, these trigger specific functions (e.g., mirror, leech, clone, torrent search, etc.).
• Utility/Helper Subsystems:
– Organized into subcomponents under bot/helper:
▪ ext_utils: General support utilities (database, file system, exception handling, task management).
▪ listeners: Monitor progress for different download methods (e.g., aria2, direct, qBittorrent).
▪ mirror_utils: Contains downloader logic for various protocols (Aria2, direct, GT downloads, etc.), status tracking, upload mechanisms (via rclone, gdrive, etc.).
▪ telegram_helper: Provides Telegram-specific assistance (command formatting, button building).
▪ themes: Applies UI themes to messages.
• Web Interface:
– The web folder components (nodes.py, wserver.py) provide a web-based UI for torrent file selection and possibly status display.
• External Service Integrations:
– Download engines: Aria2, qBittorrent, yt-dlp.
– Cloud Uploads: Google Drive (via google-api-python-client and token.pickle), rclone (with its own folder for configuration), DDL upload services.
– Database: MongoDB (storing bot settings, user data, incomplete tasks, etc.).
– Third-party APIs: Used for torrent search, various shortener integrations, and real-debrid services.
• Deployment/Docker layer:
– Dockerfile and docker-compose manage deployment and container orchestration.
– Additional scripts (e.g., update.py, add_to_team_drive.py) assist in dynamic configuration and service account management.
b. Mapping Relationships and Interactions:
• Telegram Users (clients) send commands → The Telegram Bot Interface (bot/__main__.py) receives them.
• Command Dispatcher routes the commands to the appropriate module in bot/modules.
• Modules invoke helper functions (via bot/helper/ext_utils, listeners, mirror_utils, and telegram_helper) to process tasks.
• Downloader components then interact with download engines (Aria2, qBittorrent, yt-dlp) to fetch the files.
• After downloading, uploader utilities (in mirror_utils/upload_utils) take over to mirror files to Google Drive, rclone, or supported DDL servers.
• The Web Interface interacts with the Bot for file selection (e.g., selecting specific files from torrent downloads).
• Database (MongoDB) stores persistent state, logging, and user configurations.
• External APIs and services exchange data (e.g., Google API, torrent search services, service accounts for multi-Drive operations).
c. Architectural Patterns / Design Principles:
• Modularity: Clear separation of concerns by grouping downloading, uploading, Telegram handling, and utility functions in separate directories.
• Layered Architecture: Presentation layer (Telegram commands and web UI), application layer (modules and helper utilities), integration layer (external APIs and services like Google Drive, rclone, MongoDB, etc.).
• Containerized Deployment: Use of Docker and docker-compose for consistent environment setup.
• Extensibility: Ability to update or add modules (the README details many optional features and external APIs).
d. Relevant Technologies:
• Python with Pyrogram for Telegram integration.
• Download/upload utilities: Aria2, qBittorrent, yt-dlp, rclone.
• Google Drive APIs and MongoDB for storage and data persistence.
• Docker for containerized deployment.
• Web server components serving UI selections (in web/).
– Bot Interface (input entry point)
– Command Modules (driving functionalities like mirror, leech, clone, etc.)
– Helper/Utility Layer split into:
◦ Download helpers and listeners (aria2_listener, qbit_listener, etc.)
◦ Mirror utilities and upload utilities (modules for direct download, rclone, google drive operations)
◦ Telegram helper supporting UI commands, button building.
– Web UI (a separate but communicating component, if needed).
– Database (MongoDB) and configuration (environment files, docker-compose).