skaska0/telegram-leecher

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.