# nhnobnd1/mirror-leech-telegram-bot architecture

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

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

## Overview

##### Main Components
- Telegram Bot Interface:
- This is the primary interaction layer where users send commands (like mirror, leech, clone, etc.) to the bot through Telegram.
- Command Modules (in bot/modules):
- These modules – such as mirror, leech, clone, eval, search, etc. – represent the business logic and command handling parts.
- Helper Libraries:
- Under bot/helper, there are multiple subcomponents:
 ext_utils: Contains utilities for database handling, file system utilities, exception handling, and queuing (queued_starter).
 mirror_utils: Manages download and upload logic, with submodules for different downloaders (aria2/ qbittorrent, yt_dlp, etc.) and status tracking (status_utils).
 telegram_helper: Contains utilities to construct Telegram bot commands, messages, filters, and button layouts.
- Downloaders and Uploaders:
- There is a clear separation between modules that handle downloading tasks (torrent downloaders like aria2, qBittorrent, yt_dlp, and direct link downloaders) and modules that handle uploading tasks to either Google Drive, Telegram, or other endpoints.
- The “mirror_utils/upload_utils” for example includes gdriveTools and pyrogramEngine.
- Google Drive & Service Accounts:
- The “accounts” folder holds Service Account credentials—vital for Google Drive uploads, especially with the use of multiple accounts to bypass rate limits.
- Database Integration:
- MongoDB is used to store bot and user settings, thumbnails, unfinished tasks, RSS data, and more.
- Web Interface:
- The “web” directory (with files like wserver.py and nodes.py) indicates an additional web component, most likely to serve index links or provide status pages of ongoing tasks.
- Deployment and CI/CD:
- Files like Dockerfile, docker-compose.yml, Jenkindsfile, and deployment scripts (e.g., start.sh, aria.sh) indicate that the project has containerization and potential CI/CD automation.

##### Relationships and Interactions
 From Telegram user → Telegram Bot Interface → Command Modules.
 From Command Modules → (via helper libraries) → Appropriate Downloader Modules (e.g., mirror_utils/download_utils) to fetch content.
 From Downloader Modules → Uploader Modules which then interact with Google Drive or Telegram (and others).
 The Bot also interacts with a database (MongoDB) via the ext_utils/db_handler to store state and settings.
 The web component should have a two-way interaction with data from the bot (for status pages) and may interact with the database.

##### Architectural Patterns & Design Principles
- Modular architecture: The bot’s logic is clearly separated into modules (commands, helpers, mirror utilities), making it easier to extend functionality.
- Asynchronous processing: Note that the README mentions switching from sync to async; include a note that download/upload tasks use asynchronous execution.
- Containerization: The deployment part should show a Docker container encapsulating the bot application with separate builds for web and bot functionalities if needed.

##### Technologies, Frameworks, and Tools
- Python: The core language in which the bot is implemented.
- Pyrogram: Used for interacting with Telegram.
- qBittorrent, Aria2c, yt-dlp: For handling torrent and direct downloads.
- MongoDB: For persistent storage.
- Docker & Docker-Compose: For containerized deployment.
- Service Accounts (Google Cloud): For handling Drive uploads.
- Additional utilities: 7-zip or similar (for file archive extraction), and possibly the use of external APIs (Torrent Search API).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    TelegramUser["Telegram User"]:::ui
    BotInterface["Telegram Bot Interface (Pyrogram)"]:::ui
    WebInterface["Web Interface (wserver.py & nodes.py)"]:::ui

    %% Command Modules Layer
    subgraph "Command Modules (bot/modules/)"
        CmdModules["Command Modules<br/>(e.g., mirror_leech, clone, rss)"]:::module
    end

    %% Helper Libraries Layer
    subgraph "Helper Libraries"
        ExtUtils["Ext Utils<br/>(db_handler, fs_utils, queued_starter)"]:::helper
        subgraph "Mirror Utils"
            DownloadUtils["Download Utils<br/>(aria2_download, qbit_downloader, yt_dlp_download_helper)"]:::helper
            StatusUtils["Status Utils<br/>(aria_download_status, queue_status)"]:::helper
            UploadUtils["Upload Utils<br/>(gdriveTools, pyrogramEngine)"]:::helper
        end
        TelHelper["Telegram Helper<br/>(bot_commands, button_build)"]:::helper
    end

    %% External Services Layer
    subgraph "External Services"
        ExtDownloads["Download Services<br/>(qBittorrent, Aria2c, yt-dlp)"]:::external
        GoogleDrive["Google Drive"]:::external
        MongoDB["MongoDB Database"]:::external
        APIServices["RSS/Torrent Search API"]:::external
    end

    %% Deployment & CI/CD Layer
    subgraph "Deployment & CI/CD"
        DockerCompose["Docker & Compose<br/>(Dockerfile, docker-compose.yml)"]:::deployment
        CICDPipeline["CI/CD Pipeline<br/>(Jenkindsfile)"]:::deployment
        DeployScripts["Deployment Scripts<br/>(start.sh, aria.sh)"]:::deployment
    end

    %% Data Flow Connections
    TelegramUser -->|"sends commands"| BotInterface
    BotInterface -->|"forwards commands"| CmdModules
    CmdModules -->|"invokes operations"| ExtUtils
    CmdModules -->|"invokes operations"| TelHelper
    CmdModules -->|"delegates download tasks"| DownloadUtils
    DownloadUtils -->|"fetches files from"| ExtDownloads
    DownloadUtils -->|"triggers status updates"| StatusUtils
    UploadUtils -->|"uploads to"| GoogleDrive
    ExtUtils -->|"stores state"| MongoDB
    TelHelper -->|"formats responses"| BotInterface
    WebInterface -->|"displays status/data from"| MongoDB
    WebInterface -->|"communicates with"| BotInterface

    %% Deployment Integration (Encapsulating overall system)
    BotInterface ---|"runs inside"| DockerCompose
    CmdModules ---|"runs inside"| DockerCompose
    ExtUtils ---|"runs inside"| DockerCompose
    DownloadUtils ---|"runs inside"| DockerCompose
    UploadUtils ---|"runs inside"| DockerCompose
    TelHelper ---|"runs inside"| DockerCompose
    DockerCompose ---|"managed by"| CICDPipeline
    DockerCompose ---|"launched by"| DeployScripts

    %% Click Events
    click BotInterface "https://github.com/nhnobnd1/mirror-leech-telegram-bot/blob/master/bot/__main__.py"
    click TelHelper "https://github.com/nhnobnd1/mirror-leech-telegram-bot/tree/master/bot/helper/telegram_helper/"
    click CmdModules "https://github.com/nhnobnd1/mirror-leech-telegram-bot/tree/master/bot/modules/"
    click ExtUtils "https://github.com/nhnobnd1/mirror-leech-telegram-bot/blob/master/bot/helper/ext_utils/db_handler.py"
    click DownloadUtils "https://github.com/nhnobnd1/mirror-leech-telegram-bot/tree/master/bot/helper/mirror_utils/download_utils/"
    click StatusUtils "https://github.com/nhnobnd1/mirror-leech-telegram-bot/tree/master/bot/helper/mirror_utils/status_utils/"
    click UploadUtils "https://github.com/nhnobnd1/mirror-leech-telegram-bot/tree/master/bot/helper/mirror_utils/upload_utils/"
    click UploadUtils "https://github.com/nhnobnd1/mirror-leech-telegram-bot/blob/master/bot/helper/mirror_utils/upload_utils/gdriveTools.py"
    click GoogleDrive "https://github.com/nhnobnd1/mirror-leech-telegram-bot/tree/master/accounts/"
    click WebInterface "https://github.com/nhnobnd1/mirror-leech-telegram-bot/tree/master/web/"
    click DockerCompose "https://github.com/nhnobnd1/mirror-leech-telegram-bot/blob/master/docker-compose.yml"
    click CICDPipeline "https://github.com/nhnobnd1/mirror-leech-telegram-bot/tree/master/Jenkindsfile"
    click DeployScripts "https://github.com/nhnobnd1/mirror-leech-telegram-bot/blob/master/start.sh"

    %% Styles
    classDef ui fill:#B3E5FC,stroke:#01579B,stroke-width:2px;
    classDef module fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef helper fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef deployment fill:#D7CCC8,stroke:#5D4037,stroke-width:2px;
```
