# anasty17/mirror-leech-telegram-bot architecture

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

- Interactive diagram: https://gitdiagram.com/anasty17/mirror-leech-telegram-bot
- Repository: https://github.com/anasty17/mirror-leech-telegram-bot

## Overview

##### Main components
- Telegram Bot Interface: This is the entry point where the bot receives commands via Telegram. It consists of the core modules in the “bot” folder (e.g., bot/__main__.py, bot/core/*) and Telegram helper functions.
- Core Logic & Configuration: The “bot/core” modules handle startup, configuration management, and task scheduling. Include “bot/core/config_manager.py”, “bot/core/startup.py”, etc.
- Download/Upload Adapters: There are dedicated adapters for each supported service:
- Torrent downloaders: Under bot/helper/mirror_leech_utils/download_utils (for Aria2, direct, qBittorrent, jDownloader, etc.)
- Google Drive integration: Under bot/helper/mirror_leech_utils/gdrive_utils (with clone, count, delete, upload, etc.)
- Rclone integration: Under bot/helper/mirror_leech_utils/rclone_utils (listing, serve, transfer)
- Sabnzbd and JDownloader support: Separate modules (see sabnzbd, sabnzbdapi, and myjd folders)
- Yt-dlp and other direct link generators: Found in bot/helper/mirror_leech_utils and related helper modules.
- Listeners & Event Handlers: The “bot/helper/listeners” directory is responsible for listening to events or status from different download/upload engines.
- Web UI Component: The “web” directory includes the web server (web/wserver.py) and templates (web/templates) to interact with and select files (for example, for torrent file selection).
- Database Integration: Although not directly visible in the directory structure, the README details a Mongo database being used to store bot settings, user settings, and task data.
- Docker & Deployment Configuration: Files like Dockerfile, docker-compose.yml, and scripts like start.sh define the containerization, while the .dockerignore and GitHub workflows ensure proper deployment.
- External Scripts and Tools: Extra scripts such as add_to_team_drive.py, generate_drive_token.py, and others provide supporting functions (e.g., for interacting with Google OAuth, service account generation).

##### Relationships and interactions
- Incoming Telegram commands are received by the Bot Interface and processed by the core modules.
- Core modules trigger corresponding “modules” (from bot/modules), depending on the task (mirror, leech, clone, etc.).
- These modules call the appropriate download adapter (from bot/helper/mirror_leech_utils/download_utils, listeners, etc.) depending on the chosen service.
- The download/upload adapters interact with external services: Google Drive (via gdrive_utils), rclone (via rclone_utils), torrent clients, and video downloaders (yt-dlp) to process files.
- Status and progress are tracked via listeners and stored/updated in the Mongo database.
- The Web UI (web/wserver.py) serves pages showing task status, file selection pages for torrents or NZB downloads.
- Docker and deployment components tie all these services into a unified containerized service.

##### Architectural patterns and principles
- Modular Design: The project is organized into distinct packages (core, helper, modules) for separation of concerns.
- Asynchronous Programming: The README mentions asynchronous coding in Python, so note that many of the modules interact concurrently.
- Service-Adapter Pattern: Each external service (torrent client, cloud storage, downloaders) has its adapter making extensions easier.
- Configuration-driven Behavior: The extensive config_sample.py and usage of a Mongo database show that much of the behavior is driven by configuration parameters.
- Containerization: Dockerfile and docker-compose.yml indicate a cloud-ready, containerized application.

- Use clear segmentation between the Bot Interface, Task Handlers, Download/Upload Adapters, External Tools & Services, and the Database.
- Explicitly mark the Docker/Deployment layer and include external dependencies (MongoDB, Google APIs, Docker containers, etc.)

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "Deployment Environment"
    BotInterface["Telegram Bot Interface"]:::interface
    TelegramHelpers["Telegram Helper Functions"]:::helper
    CoreModules["Core Modules & Config"]:::core

    subgraph "Service Adapters"
      subgraph "Torrent Services"
        TorrentDownloader["Torrent Downloader (qBittorrent)"]:::adapter
        subgraph "Listeners"
          QbitListener["Qbit Listener"]:::listener
          Aria2Listener["Aria2 Listener"]:::listener
          JDownloaderListener["JDownloader Listener"]:::listener
          NZBListener["NZB Listener"]:::listener
          DirectListener["Direct Listener"]:::listener
          TaskListener["Task Listener"]:::listener
        end
        JDownloaderSupport["JDownloader Support"]:::adapter
        JDownloaderBooter["JDownloader Booter"]:::adapter
        MyJD["MyJD Integration"]:::adapter
      end
      subgraph "Cloud Storage Adapters"
        GoogleDrive["Google Drive Adapter"]:::cloud
        Rclone["Rclone Adapter"]:::cloud
      end
      subgraph "Direct Link & Media Utilities"
        DirectDownloader["Direct Downloader & Generator"]:::adapter
        YtDlp["yt-dlp Integration"]:::adapter
        MediaUtils["Media Utilities"]:::adapter
      end
    end

    TaskModules["Modular Task Modules"]:::module

    subgraph "Web Interface"
      WebUI["Web UI Server"]:::web
      Templates["Templates"]:::web
    end

    MongoDB["Database (MongoDB)"]:::database

    subgraph "External Tools & Scripts"
      AddToTeam["add_to_team_drive.py"]:::external
      GenerateDrive["generate_drive_token.py"]:::external
      GenSA["gen_sa_accounts.py"]:::external
      DriveID["driveid.py"]:::external
      GenString["generate_string_session.py"]:::external
    end

    subgraph "Deployment Config"
      Dockerfile["Dockerfile"]:::deploy
      DockerCompose["docker-compose.yml"]:::deploy
      DockerIgnore[".dockerignore"]:::deploy
      StartSh["start.sh"]:::deploy
    end
  end

  %% Connections
  BotInterface -->|"commands"| CoreModules
  BotInterface -->|"assist"| TelegramHelpers
  TelegramHelpers -->|"process_commands"| CoreModules

  CoreModules -->|"trigger_torrent"| TorrentDownloader
  CoreModules -->|"trigger_jdownloader"| JDownloaderSupport
  CoreModules -->|"trigger_jdownloader_boot"| JDownloaderBooter
  CoreModules -->|"trigger_cloud"| GoogleDrive
  CoreModules -->|"trigger_cloud"| Rclone
  CoreModules -->|"trigger_direct"| DirectDownloader
  CoreModules -->|"trigger_async"| YtDlp
  CoreModules -->|"trigger_async"| MediaUtils
  CoreModules -->|"trigger_task"| TaskModules

  QbitListener -->|"status_update"| CoreModules
  Aria2Listener -->|"status_update"| CoreModules
  JDownloaderListener -->|"status_update"| CoreModules
  NZBListener -->|"status_update"| CoreModules
  DirectListener -->|"status_update"| CoreModules
  TaskListener -->|"status_update"| CoreModules

  CoreModules -->|"update_status"| MongoDB
  CoreModules -->|"display_update"| WebUI

  WebUI -->|"render"| Templates

  CoreModules -->|"trigger_myjd"| MyJD

  GenerateDrive -->|"auth_token"| GoogleDrive

  %% Click Events
  click BotInterface "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/__main__.py"
  click TelegramHelpers "https://github.com/anasty17/mirror-leech-telegram-bot/tree/master/bot/helper/telegram_helper/"
  click CoreModules "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/core/config_manager.py"
  click TorrentDownloader "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/mirror_leech_utils/download_utils/qbit_download.py"
  click QbitListener "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/listeners/qbit_listener.py"
  click Aria2Listener "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/listeners/aria2_listener.py"
  click JDownloaderListener "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/listeners/jdownloader_listener.py"
  click NZBListener "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/listeners/nzb_listener.py"
  click DirectListener "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/listeners/direct_listener.py"
  click TaskListener "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/listeners/task_listener.py"
  click JDownloaderSupport "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/mirror_leech_utils/download_utils/jd_download.py"
  click JDownloaderBooter "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/core/jdownloader_booter.py"
  click MyJD "https://github.com/anasty17/mirror-leech-telegram-bot/tree/master/myjd/"
  click GoogleDrive "https://github.com/anasty17/mirror-leech-telegram-bot/tree/master/bot/helper/mirror_leech_utils/gdrive_utils/"
  click Rclone "https://github.com/anasty17/mirror-leech-telegram-bot/tree/master/bot/helper/mirror_leech_utils/rclone_utils/"
  click DirectDownloader "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/mirror_leech_utils/download_utils/direct_downloader.py"
  click YtDlp "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/mirror_leech_utils/download_utils/yt_dlp_download.py"
  click MediaUtils "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/ext_utils/media_utils.py"
  click TaskModules "https://github.com/anasty17/mirror-leech-telegram-bot/tree/master/bot/modules/"
  click WebUI "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/web/wserver.py"
  click Templates "https://github.com/anasty17/mirror-leech-telegram-bot/tree/master/web/templates/"
  click MongoDB "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/bot/helper/ext_utils/db_handler.py"
  click AddToTeam "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/add_to_team_drive.py"
  click GenerateDrive "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/generate_drive_token.py"
  click GenSA "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/gen_sa_accounts.py"
  click DriveID "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/driveid.py"
  click GenString "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/generate_string_session.py"
  click Dockerfile "https://github.com/anasty17/mirror-leech-telegram-bot/tree/master/Dockerfile"
  click DockerCompose "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/docker-compose.yml"
  click DockerIgnore "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/.dockerignore"
  click StartSh "https://github.com/anasty17/mirror-leech-telegram-bot/blob/master/start.sh"

  %% Styles
  classDef interface fill:#b3e5fc,stroke:#01579b,stroke-width:2px;
  classDef helper fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
  classDef core fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
  classDef adapter fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
  classDef listener fill:#ffccbc,stroke:#d84315,stroke-width:2px;
  classDef cloud fill:#d1c4e9,stroke:#512da8,stroke-width:2px;
  classDef module fill:#f0f4c3,stroke:#9e9d24,stroke-width:2px;
  classDef web fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;
  classDef database fill:#d7ccc8,stroke:#5d4037,stroke-width:2px;
  classDef external fill:#f8bbd0,stroke:#880e4f,stroke-width:2px;
  classDef deploy fill:#d0f8ce,stroke:#388e3c,stroke-width:2px;
```
