# skaska0/telegram-leecher architecture

> Architecture diagram of the GitHub repository skaska0/telegram-leecher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/skaska0/telegram-leecher
- Repository: https://github.com/skaska0/telegram-leecher

## Overview

1. **Overall shape**
   - This is a Python package named `colab_leecher` plus a top-level `main.py` entrypoint.
   - It is designed to run inside **Google Colab** as a Telegram bot-based transfer service, not as a standalone web application.

2. **Primary control surface**
   - The bot is built around **Pyrogram** and exposes functionality through Telegram commands/messages.
   - Incoming user actions are parsed and dispatched by the bot layer, then handed off to the download/upload orchestration code.

3. **Execution entrypoints**
   - `main.py` is the obvious runtime launcher.
   - `colab_leecher/__main__.py` makes the package runnable as a module.
   - This suggests the project supports both notebook-driven startup and standard Python invocation.

4. **Orchestration boundary**
   - `colab_leecher/downlader/manager.py` is the central coordinator.
   - It likely decides which source handler to use, tracks a job through download → processing → upload, and bridges command input to the correct backend.
   - The package name `downlader` is misspelled in the repo, but it clearly contains the core download subsystem.

5. **Source-specific downloader adapters**
   - The `downlader/` package is split by source:
     - `aria2.py` for direct HTTP/URL downloads and high-throughput file fetching.
     - `gdrive.py` for Google Drive links and authentication-related access.
     - `telegram.py` for Telegram file links / restricted content handling.
     - `ytdl.py` for YouTube and other `yt-dlp`-style video sources.
     - `mega.py` and `terabox.py` indicate additional source integrations, even if not all are fully featured.
   - This is a classic adapter layer: each source has its own fetch logic and constraints.

6. **Upload side**
   - `colab_leecher/uploader/telegram.py` is the destination upload module.
   - The architecture appears to mirror downloaded content back into Telegram, which matches the README’s “upload directly from Colab container” and “unlimited storage in Telegram” positioning.
   - There is no separate Google Drive uploader package in the tree, so Drive is mainly a download/mirror source or storage target on the Colab side rather than a full upload backend in this repo.

7. **Post-processing pipeline**
   - `utility/converters.py` and likely parts of `utility/helper.py` handle file transformations and packaging.
   - Based on the README, this includes video conversion, zipping, archive extraction, thumbnail generation, filename customization, and deciding whether large outputs need special handling.
   - These steps sit between raw download and final Telegram upload.

8. **Job/state management**
   - `utility/task_manager.py` suggests explicit tracking of active transfers, concurrency, and task lifecycle.
   - `utility/variables.py` likely centralizes runtime configuration such as size limits, paths, and feature flags.
   - Together, these modules act as the shared state layer for the bot’s active jobs.

9. **Messaging and progress reporting**
   - `utility/handler.py` is likely responsible for Telegram-facing progress/status updates, error handling, and common bot response behavior.
   - `utility/helper.py` probably contains shared routines used across downloaders, uploaders, and command handlers.
   - This keeps UI/notification logic separate from source-specific transfer logic.

10. **Data flow through the system**
   - The typical flow is: **Telegram command/link → bot handler → manager → source downloader → local/Colab filesystem (and possibly extracted/converted artifacts) → Telegram uploader → status updates back to the user**.
   - The filesystem inside the Colab runtime is the main staging boundary, which matters because disk space is limited and runtime disconnects are expected.

11. **External services and infrastructure**
   - The repo’s main external dependencies are **Telegram**, **Google Colab**, **Google Drive**, and remote download hosts such as YouTube and generic HTTP sources.
   - `aria2` implies a download engine optimized for parallel fetching.
   - The architecture is therefore a cloud-runnable transfer pipeline constrained by Colab policy and storage/runtime limits.

12. **Important architectural constraint**
   - The README explicitly excludes torrents/magnet links, and the codebase is structured around direct-link, Drive, Telegram, and video-source handling instead.
   - That means the system is intentionally optimized for non-P2P transfers and for short-lived, interactive Colab sessions rather than persistent hosting.

Main entry points: [`colab_leecher/downlader/manager.py`](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/manager.py) (Manager), [`colab_leecher/utility/converters.py`](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/converters.py) (Converters), [`colab_leecher/uploader/telegram.py`](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/uploader/telegram.py) (Telegram upload), [`colab_leecher/utility/handler.py`](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/handler.py) (Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_py["main.py<br/>entrypoint<br/>[main.py]"]
  node_module_main["__main__<br/>module entry<br/>[__main__.py]"]
end

subgraph group_download["Downloaders"]
  node_job_manager["Manager<br/>orchestrator<br/>[manager.py]"]
  node_aria2_dl["Aria2<br/>http downloader<br/>[aria2.py]"]
  node_gdrive_dl["Drive<br/>cloud source<br/>[gdrive.py]"]
  node_tg_dl["Telegram src<br/>telegram source<br/>[telegram.py]"]
  node_ytdl_dl["YTDL<br/>video source<br/>[ytdl.py]"]
  node_mega_dl["Mega<br/>cloud source<br/>[mega.py]"]
  node_terabox_dl["TeraBox<br/>cloud source<br/>[terabox.py]"]
end

subgraph group_delivery["Delivery"]
  node_converter["Converters<br/>post-process<br/>[converters.py]"]
  node_uploader_tg["Telegram upload<br/>uploader<br/>[telegram.py]"]
end

subgraph group_shared["Shared"]
  node_bot_api["Pyrogram bot<br/>telegram interface"]
  node_task_mgr["Task manager<br/>state tracker<br/>[task_manager.py]"]
  node_vars["Variables<br/>runtime config<br/>[variables.py]"]
  node_handler["Handler<br/>[handler.py]"]
  node_helper["Helper<br/>shared utils<br/>[helper.py]"]
end

node_main_py -->|"starts"| node_bot_api
node_module_main -->|"starts"| node_bot_api
node_bot_api -->|"dispatches"| node_job_manager
node_job_manager -->|"reads config"| node_vars
node_job_manager -->|"tracks jobs"| node_task_mgr
node_job_manager -->|"selects"| node_aria2_dl
node_job_manager -->|"selects"| node_gdrive_dl
node_job_manager -->|"selects"| node_tg_dl
node_job_manager -->|"selects"| node_ytdl_dl
node_job_manager -->|"selects"| node_mega_dl
node_job_manager -->|"selects"| node_terabox_dl
node_aria2_dl -->|"hands off"| node_converter
node_gdrive_dl -->|"hands off"| node_converter
node_tg_dl -->|"hands off"| node_converter
node_ytdl_dl -->|"hands off"| node_converter
node_mega_dl -->|"hands off"| node_converter
node_terabox_dl -->|"hands off"| node_converter
node_converter -->|"passes artifacts"| node_uploader_tg
node_uploader_tg -->|"reports status"| node_handler
node_job_manager -->|"reports status"| node_handler
node_handler -->|"uses"| node_helper
node_converter -->|"uses"| node_helper
node_uploader_tg -->|"uses"| node_helper

click node_main_py "https://github.com/skaska0/telegram-leecher/blob/main/main.py"
click node_module_main "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/__main__.py"
click node_job_manager "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/manager.py"
click node_aria2_dl "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/aria2.py"
click node_gdrive_dl "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/gdrive.py"
click node_tg_dl "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/telegram.py"
click node_ytdl_dl "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/ytdl.py"
click node_mega_dl "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/mega.py"
click node_terabox_dl "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/terabox.py"
click node_converter "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/converters.py"
click node_uploader_tg "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/uploader/telegram.py"
click node_task_mgr "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/task_manager.py"
click node_vars "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/variables.py"
click node_handler "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/handler.py"
click node_helper "https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/helper.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_py,node_module_main toneBlue
class node_job_manager,node_aria2_dl,node_gdrive_dl,node_tg_dl,node_ytdl_dl,node_mega_dl,node_terabox_dl toneAmber
class node_converter,node_uploader_tg toneMint
class node_bot_api,node_task_mgr,node_vars,node_handler,node_helper toneRose
```

## Components

### Runtime

Entry points for starting the Colab bot service.

- [main.py](https://github.com/skaska0/telegram-leecher/blob/main/main.py): entrypoint · Top-level launcher for running the service directly. · `main.py`
- [__main__](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/__main__.py): module entry · Package entrypoint for python -m startup. · `colab_leecher/__main__.py`

### Downloaders

Source-specific adapters and orchestration for inbound transfers.

- [Manager](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/manager.py): orchestrator · Central coordinator that routes jobs from commands to the right backend. · `colab_leecher/downlader/manager.py`
- [Aria2](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/aria2.py): http downloader · High-throughput direct-link and file download adapter. · `colab_leecher/downlader/aria2.py`
- [Drive](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/gdrive.py): cloud source · Google Drive access and link handling adapter. · `colab_leecher/downlader/gdrive.py`
- [Telegram src](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/telegram.py): telegram source · Telegram file/link retrieval adapter. · `colab_leecher/downlader/telegram.py`
- [YTDL](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/ytdl.py): video source · YouTube and yt-dlp-style media source adapter. · `colab_leecher/downlader/ytdl.py`
- [Mega](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/mega.py): cloud source · MEGA transfer adapter. · `colab_leecher/downlader/mega.py`
- [TeraBox](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/downlader/terabox.py): cloud source · TeraBox transfer adapter. · `colab_leecher/downlader/terabox.py`

### Delivery

Processing and Telegram upload of prepared artifacts.

- [Converters](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/converters.py): post-process · File transformation, packaging, extraction, and media prep. · `colab_leecher/utility/converters.py`
- [Telegram upload](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/uploader/telegram.py): uploader · Final destination uploader that sends prepared files back to Telegram. · `colab_leecher/uploader/telegram.py`

### Shared

Common state, helpers, and bot-facing coordination.

- **Pyrogram bot**: telegram interface · Telegram command and message surface that receives user actions.
- [Task manager](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/task_manager.py): state tracker · Tracks active transfers and job lifecycle. · `colab_leecher/utility/task_manager.py`
- [Variables](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/variables.py): runtime config · Shared runtime settings, limits, and feature flags. · `colab_leecher/utility/variables.py`
- [Handler](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/handler.py): status handler · Telegram-facing progress, error, and response handling. · `colab_leecher/utility/handler.py`
- [Helper](https://github.com/skaska0/telegram-leecher/blob/main/colab_leecher/utility/helper.py): shared utils · Common routines reused across bot, download, and upload code. · `colab_leecher/utility/helper.py`

## Connections

- main.py → Pyrogram bot: starts · Direct launcher initializes the Telegram bot runtime.
- __main__ → Pyrogram bot: starts · Module execution path initializes the same bot runtime.
- Pyrogram bot → Manager: dispatches · User commands and link actions are routed into the orchestrator.
- Manager → Variables: reads config · Coordinator uses shared runtime limits and settings.
- Manager → Task manager: tracks jobs · Active transfer state is registered and updated.
- Manager → Aria2: selects · Direct links and bulk HTTP downloads are handed to Aria2.
- Manager → Drive: selects · Google Drive inputs are delegated to the Drive adapter.
- Manager → Telegram src: selects · Telegram-origin content is delegated to the Telegram source adapter.
- Manager → YTDL: selects · Video and media sources are delegated to the YTDL adapter.
- Manager → Mega: selects · MEGA links are delegated to the MEGA adapter.
- Manager → TeraBox: selects · TeraBox links are delegated to the TeraBox adapter.
- Aria2 → Converters: hands off · Downloaded payloads may be prepared for upload or packaging.
- Drive → Converters: hands off · Fetched files can be transformed or packaged before upload.
- Telegram src → Converters: hands off · Retrieved Telegram files may be post-processed.
- YTDL → Converters: hands off · Media downloads often require conversion or remuxing.
- Mega → Converters: hands off · MEGA downloads can enter the same preparation pipeline.
- TeraBox → Converters: hands off · TeraBox downloads can enter the same preparation pipeline.
- Converters → Telegram upload: passes artifacts · Prepared outputs are sent to the Telegram uploader.
- Telegram upload → Handler: reports status · Upload progress, completion, and failures are surfaced to the user.
- Manager → Handler: reports status · Coordinator emits job-level updates and errors.
- Handler → Helper: uses · Common response and formatting helpers support bot messaging.
- Converters → Helper: uses · Transformation steps rely on shared utility routines.
- Telegram upload → Helper: uses · Upload-side common logic is shared through helpers.