# silentdemonsd/wzml-x architecture

> Architecture diagram of the GitHub repository silentdemonsd/wzml-x, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/silentdemonsd/wzml-x
- Repository: https://github.com/silentdemonsd/wzml-x
- Video tour (about a minute): https://gitdiagram.com/silentdemonsd/wzml-x/video

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    TelegramUsers["Telegram Users"]:::external
    BotInterface["Bot Interface"]:::bot
    CommandModules["Command Handler Modules"]:::bot
    ExtUtils["General Helpers (ext_utils)"]:::utility
    Listeners["Task Listeners"]:::utility
    MirrorUtils["Mirror & Upload Logic"]:::utility
    TelegramHelper["Telegram Helpers"]:::utility
    Themes["UI Themes"]:::utility
    WebInterface["Web Interface"]:::webui
    MongoDB["MongoDB"]:::database
    DownloadEngines["Download Engines"]:::integration
    CloudUploads["Cloud Uploads"]:::integration

    TelegramUsers -->|"sends_command"| BotInterface
    BotInterface -->|"dispatches"| CommandModules
    CommandModules -->|"uses"| ExtUtils
    CommandModules -->|"triggers"| Listeners
    CommandModules -->|"calls"| MirrorUtils
    CommandModules -->|"utilizes"| TelegramHelper
    CommandModules -->|"applies"| Themes
    MirrorUtils -->|"initiates"| DownloadEngines
    MirrorUtils -->|"uploads_to"| CloudUploads
    CommandModules -->|"records_state"| MongoDB
    BotInterface -->|"integrates_UI"| WebInterface

    subgraph "Deployment and Configuration"
        Dockerfile["Dockerfile"]:::deployment
        DockerCompose["docker-compose.yml"]:::deployment
        ConfigSample["config_sample.env"]:::deployment
        StartSh["start.sh"]:::deployment
    end

    subgraph "External Service Integrations"
        AddToTeamDrive["add_to_team_drive.py"]:::integration
        DriveID["driveid.py"]:::integration
        GenSAAccounts["gen_sa_accounts.py"]:::integration
        GenerateDriveToken["generate_drive_token.py"]:::integration
        QbittorrentConfig["qBittorrent Config"]:::integration
    end

    classDef external fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef bot fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef utility fill:#d6e9ff,stroke:#333,stroke-width:2px;
    classDef webui fill:#d9f2d9,stroke:#333,stroke-width:2px;
    classDef deployment fill:#ffd6cc,stroke:#333,stroke-width:2px;
    classDef integration fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef database fill:#ffcce6,stroke:#333,stroke-width:2px;

    click BotInterface "https://github.com/silentdemonsd/wzml-x/blob/master/bot/__main__.py"
    click CommandModules "https://github.com/silentdemonsd/wzml-x/tree/master/bot/modules/"
    click ExtUtils "https://github.com/silentdemonsd/wzml-x/tree/master/bot/helper/ext_utils/"
    click Listeners "https://github.com/silentdemonsd/wzml-x/tree/master/bot/helper/listeners/"
    click MirrorUtils "https://github.com/silentdemonsd/wzml-x/tree/master/bot/helper/mirror_utils/"
    click TelegramHelper "https://github.com/silentdemonsd/wzml-x/tree/master/bot/helper/telegram_helper/"
    click Themes "https://github.com/silentdemonsd/wzml-x/tree/master/bot/helper/themes/"
    click WebInterface "https://github.com/silentdemonsd/wzml-x/tree/master/web/"
    click Dockerfile "https://github.com/silentdemonsd/wzml-x/tree/master/Dockerfile"
    click DockerCompose "https://github.com/silentdemonsd/wzml-x/blob/master/docker-compose.yml"
    click ConfigSample "https://github.com/silentdemonsd/wzml-x/blob/master/config_sample.env"
    click StartSh "https://github.com/silentdemonsd/wzml-x/blob/master/start.sh"
    click AddToTeamDrive "https://github.com/silentdemonsd/wzml-x/blob/master/add_to_team_drive.py"
    click DriveID "https://github.com/silentdemonsd/wzml-x/blob/master/driveid.py"
    click GenSAAccounts "https://github.com/silentdemonsd/wzml-x/blob/master/gen_sa_accounts.py"
    click GenerateDriveToken "https://github.com/silentdemonsd/wzml-x/blob/master/generate_drive_token.py"
    click QbittorrentConfig "https://github.com/silentdemonsd/wzml-x/blob/master/qBittorrent/config/qBittorrent.conf"
```
