# cipherx7/torrentleechx architecture

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

- Interactive diagram: https://gitdiagram.com/cipherx7/torrentleechx
- Repository: https://github.com/cipherx7/torrentleechx

## Overview

##### Project Type and Purpose
- The project is clearly a Telegram bot built using Pyrogram. It is designed to “leech” (download) torrents, direct links, and even YouTube content and then either mirror them to a cloud storage (using rclone/gclone) or deliver them directly over Telegram.
- The README highlights support for both direct Telegram interactions and cloud integrations, so this is a full-featured bot that acts as a middleware between the Telegram API, file download/processing subsystems, and third-party cloud services.

##### File Structure
- Top-level files such as Dockerfile, heroku*.md, sample_config.env, and setup/start scripts indicate deployment and configuration support for multiple environments (VPS, Heroku, etc.).
- The “tobrot” directory holds most of the Python code including:
⁃ __main__.py and __init__.py which serve as the entrypoint.
⁃ A dedicated “aria2” subdirectory with configuration that shows integration with the Aria2 download manager.
⁃ “helper_funcs” contains various utility modules for downloads, extraction, progress display, exception handling, and external service integration (e.g., real debrid or YouTube downloading).
⁃ “plugins” directory contains modules that encapsulate individual commands/functions (for instance handling callbacks, new joins, rclone operations, custom thumbnails, etc.).
- Presence of configuration files (e.g., requirements.txt, _config.yml, rclone.conf) indicates that much of the runtime behavior is driven by environment-specific parameters.

##### Components
a. Telegram Bot Interface:
- Telegram API and BotFather-created bot token configuration.
- Incoming commands and message handling via Pyrogram.

b. Core Bot Application (tobrot):
- The Main Application module (tobrot/__main__.py) as the orchestrator.
- Break out the “plugins” (each command – such as /leech, /ytdl, /gclone, etc.) as separate functional blocks that extend the core functionality.
- “helper_funcs” as supporting modules which contain logic for downloading files (including torrent and direct-link downloads), file extraction, archiving, progress display, and error handling.
- A block showing the Aria2 integration (from the tobrot/aria2 directory), which manages torrent and multi-part downloads.

c. Cloud Integration:
- Configuration flow from environmental variables (such as DESTINATION_FOLDER, RCLONE_CONF_URL) that control this behavior.

d. Deployment and Configuration:
- Integration with deployment workflows. Include smaller blocks/maps for:
- Docker and Heroku: indicating that the project contains Dockerfile, heroku.yml, and separate deployment guides.
- GitHub Workflows (.github/workflows) which automatically build or run tests.
- Setup Scripts (setup.sh, start.sh) that initiate the bot.

##### Component Relationships and Interactions
- The “plugins” handling various commands.
- “Helper_funcs” modules that perform file downloads (through Aria2), extraction, and post-download file processing.
- Data flow from the downloader (Aria2 or helper functions) to the Cloud Integration block (which uses rclone/gclone).
- If applicable, show feedback paths such as sending status messages or logs back to the Telegram chat.
- Incorporate configuration management, where the environmental variables and setup scripts influence behaviors in the core components.

##### Architectural Patterns and Technologies
- Modular design – a clear separation between core bot logic, helper functions, and plugin command handlers.
- Usage of Pyrogram as the underlying technology for the Telegram API.
- Third-party integrations:
- Aria2 for download management.
- rclone/gclone for cloud interactions.
- External libraries (like youtube-dl) for media downloads.
- That command processing is achieved by parsing and then delegating commands to dedicated modules within the plugins folder.

##### Instructing the Principal Software Engineer
- Branch out to show the “plugins” handling various commands.
- “helper_funcs” as supporting modules.
- Environment variables/configurations that initiate or modulate functionality.
- A note on the asynchronous, event-driven nature of command handling.
- Deployment pipelines that include Docker, Heroku, and GitHub workflows.
- Finally, don’t hesitate to add annotations that explain how commands (from Telegram) are helped by specific plugins and helper functions which ultimately result in file download/compression/cloud upload operations, emphasizing the modularity and clarity of the codebase.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Users["Telegram Users"]:::frontend

    %% Telegram Bot Interface
    subgraph "Telegram Bot Interface"
        T1["Entry Point & Message Handler"]:::application
        T2["Incoming Message Handler"]:::plugin
    end

    %% Core Bot Application
    subgraph "Core Bot Application"
        CA1["Main Application Module"]:::application
        CA2["Core Initialization"]:::application
        CA3["Command Processing (Plugins)"]:::plugin
        CA4["Utility/Helper Modules"]:::plugin
    end

    %% Download Manager & Aria2 Integration
    subgraph "Download Manager & Aria2 Integration"
        D1["Aria2 Integration"]:::download
        D2["Additional Download Logic"]:::download
    end

    %% Cloud Integration
    subgraph "Cloud Integration"
        CI1["rclone/gclone Operations"]:::cloud
        CI2["Cloud Clone Helper"]:::cloud
    end

    %% Deployment and Configuration
    subgraph "Deployment and Configuration"
        DC1["Deployment Configs"]:::config
        DC2["CI Workflows"]:::config
        DC3["Setup/Start Scripts"]:::config
    end

    %% Connections
    Users -->|"sends_commands"| T1
    T1 -->|"invokes"| CA1
    T2 -->|"routes_to"| CA1

    CA1 -->|"delegates"| CA3
    CA1 -->|"calls"| CA4
    CA3 -->|"triggers_action"| CA4

    CA4 -->|"initiates_download"| D1
    D1 -->|"manages_parts"| D2
    D2 -->|"post_download"| CI1
    CI1 -->|"executes_sync"| CI2
    CI2 -->|"updates_status"| CA1
    CA1 -->|"sends_update"| Users

    DC1 -->|"configures"| CA1
    DC2 -->|"triggers_CI"| CA1
    DC2 -->|"monitors"| CI1
    DC3 -->|"starts_up"| CA1

    %% Styles
    classDef frontend fill:#FAD02E,stroke:#333,stroke-width:2px;
    classDef application fill:#A1C6EA,stroke:#333,stroke-width:2px;
    classDef plugin fill:#A3E4D7,stroke:#333,stroke-width:2px;
    classDef download fill:#D7BDE2,stroke:#333,stroke-width:2px;
    classDef cloud fill:#F7DC6F,stroke:#333,stroke-width:2px;
    classDef config fill:#AED6F1,stroke:#333,stroke-width:2px;

    %% Click Events
    click T1 "https://github.com/cipherx7/torrentleechx/blob/master/tobrot/__main__.py"
    click T2 "https://github.com/cipherx7/torrentleechx/blob/master/tobrot/plugins/incoming_message_fn.py"
    click CA1 "https://github.com/cipherx7/torrentleechx/blob/master/tobrot/__main__.py"
    click CA2 "https://github.com/cipherx7/torrentleechx/blob/master/tobrot/__init__.py"
    click CA3 "https://github.com/cipherx7/torrentleechx/tree/master/tobrot/plugins/"
    click CA4 "https://github.com/cipherx7/torrentleechx/tree/master/tobrot/helper_funcs/"
    click D1 "https://github.com/cipherx7/torrentleechx/tree/master/tobrot/aria2/"
    click D2 "https://github.com/cipherx7/torrentleechx/blob/master/tobrot/helper_funcs/download_aria_p_n.py"
    click CI1 "https://github.com/cipherx7/torrentleechx/blob/master/tobrot/plugins/choose_rclone_config.py"
    click CI2 "https://github.com/cipherx7/torrentleechx/blob/master/tobrot/helper_funcs/cloneHelper.py"
    click DC1 "https://github.com/cipherx7/torrentleechx/tree/master/Dockerfile"
    click DC2 "https://github.com/cipherx7/torrentleechx/blob/master/.github/workflows/main.yml"
    click DC3 "https://github.com/cipherx7/torrentleechx/blob/master/setup.sh"
```
