# ritikroy960/uploader-bot architecture

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

- Interactive diagram: https://gitdiagram.com/ritikroy960/uploader-bot
- Repository: https://github.com/ritikroy960/uploader-bot

## Overview

##### Project type and purpose
- This is a backend-only Python Telegram Bot (“Uploader-Bot”) designed to download media (via yt-dlp/ffmpeg) from supported sites or HTTP/HTTPS links and upload them to Telegram chats. It also supports user management, permanent thumbnails, broadcasting, and stores user data in MongoDB. It runs on Heroku.

##### File structure
- Top-level scripts/config:
– bot.py: entry point; initializes the Pyrogram client, loads plugins, handles updates
– config.py: holds environment variables (API keys, database URIs)
– translation.py: multi-language message strings
– Procfile, runtime.txt, app.json: Heroku deployment descriptors
– requirements.txt: Python dependencies (pyrogram, pymongo, yt-dlp, ffmpeg, etc.)
- database/
– database.py: connection logic to MongoDB
– access.py, adduser.py: CRUD operations for user data, thumbnails, stats
- helper_funcs/
– display_progress.py: progress callbacks for uploads/downloads
– help_Nekmo_ffmpeg.py: ffmpeg wrapper utilities
– help_uploadbot.py: common routines for assembling/sending files
- plugins/
– modules named after commands: admin.py, broadcast.py, buttons.py, force-sub, youtube_dl_button.py, etc.
– Each plugin registers handlers for specific commands or callback queries.

##### Diagramming main components
a. Components
1) Telegram API (Cloud)
2) Uploader-Bot Application (Heroku dyno)
– Entry Point (bot.py & Pyrogram client)
– Plugin Layer (plugins/*.py)
– Helper Utilities (helper_funcs/*.py)
– Data Access Layer (database/*.py)
– Configuration & Translation
3) MongoDB Service (external, via URI)
4) External Media Sources (YouTube, HTTP hosts, Zee5, Voot, etc.)
5) System Tools (yt-dlp, ffmpeg buildpacks)
b. Relationships and data flow
1) Telegram client polls or receives webhooks from Telegram API → bot.py
2) bot.py dispatches updates to plugin handlers (plugins/*.py)
3) Handlers invoke helper_funcs for downloads/uploads:
– Call yt-dlp/ffmpeg subprocess → raw media files
– Use Pyrogram APIs to send media back to Telegram
– Use display_progress callbacks for user feedback
4) Plugins & data layer interact with MongoDB via database/*.py to:
– Create & retrieve user records (adduser/access)
– Store/delete thumbnail URLs
– Track broadcast statistics
5) Config drives all environment-specific settings; translation provides user messages.
6) Heroku buildpacks supply ffmpeg and dependencies.
c. Architectural patterns & principles
– Modular plugin architecture: each command lives in its own file, loosely coupled by a central dispatcher
– Layered separation: entry point → plugin handlers → helper functions → database access
– Externalization of configuration for 12-factor compliance on Heroku
– Use of asynchronous callbacks (Pyrogram) and subprocess calls for long-running tasks
d. Key technologies
– Python 3.x, Pyrogram (Telegram MTProto library)
– yt-dlp & ffmpeg for media handling
– MongoDB (pymongo) for persistence
– Heroku (Procfile, buildpacks) for deployment

##### Essential details to capture
- Bot entry point (bot.py with Pyrogram client) and plugin loader
- Separation of handlers (plugins) vs. utility code (helper_funcs) vs. data layer (database)
- Configuration module driving environment settings (Heroku, MongoDB URI, API keys)
- External services: Telegram, MongoDB, yt-dlp/ffmpeg, supported media websites
- Data flows for download, upload, database operations, broadcast

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    TELEGRAM_API["Telegram API"]:::cloud
    EXTERNAL_MEDIA["External Media Sources<br/>(YouTube, HTTP Hosts, Zee5, Voot, etc.)"]:::cloud
    TOOLS["yt-dlp / ffmpeg Tools"]:::gear
    MONGODB["MongoDB Service"]:::db

    %% Bot Application on Heroku
    subgraph "Heroku Dyno: Uploader-Bot Application"
        direction TB
        BOT["Entry Point / Dispatcher<br/>(bot.py)"]:::component
        CONFIG["Configuration Module<br/>(config.py)"]:::component
        TRANS["Translation Module<br/>(translation.py)"]:::component

        subgraph "Plugin Layer"
            direction TB
            ADMIN["admin.py"]:::plugin
            BROADCAST["broadcast.py"]:::plugin
            BUTTONS["buttons.py"]:::plugin
            CALLBACK["callback.py"]:::plugin
            CUSTOM_THUMB["custom_thumbnail.py"]:::plugin
            DL_BUTTON["dl_button.py"]:::plugin
            FORCESUB["forcesub.py"]:::plugin
            HELP_TEXT["help_text.py"]:::plugin
            YT_DL_BUTTON["youtube_dl_button.py"]:::plugin
            YT_DL_ECHO["youtube_dl_echo.py"]:::plugin
        end

        subgraph "Helper Utilities"
            direction TB
            PROGRESS["display_progress.py"]:::helper
            FFMPEG_UTILS["help_Nekmo_ffmpeg.py"]:::helper
            UPLOAD_HELP["help_uploadbot.py"]:::helper
        end

        subgraph "Data Access Layer"
            direction TB
            DB_CONN["database.py"]:::data
            ACCESS["access.py"]:::data
            ADDUSER["adduser.py"]:::data
        end
    end

    %% Data Flows
    TELEGRAM_API -->|"Inbound Updates"| BOT
    BOT -->|"Dispatch to Plugins"| ADMIN
    BOT -->|"Dispatch to Plugins"| BROADCAST
    BOT -->|"Dispatch to Plugins"| BUTTONS
    BOT -->|"Dispatch to Plugins"| CALLBACK
    BOT -->|"Dispatch to Plugins"| CUSTOM_THUMB
    BOT -->|"Dispatch to Plugins"| DL_BUTTON
    BOT -->|"Dispatch to Plugins"| FORCESUB
    BOT -->|"Dispatch to Plugins"| HELP_TEXT
    BOT -->|"Dispatch to Plugins"| YT_DL_BUTTON
    BOT -->|"Dispatch to Plugins"| YT_DL_ECHO

    %% Plugins use helpers and data
    ADMIN -->|"invoke helpers"| PROGRESS
    BROADCAST -->|"invoke helpers"| UPLOAD_HELP
    BUTTONS -->|"invoke helpers"| PROGRESS
    CALLBACK -->|"invoke helpers"| FFMPEG_UTILS
    CUSTOM_THUMB -->|"invoke helpers"| UPLOAD_HELP
    DL_BUTTON -->|"invoke helpers"| PROGRESS
    FORCESUB -->|"invoke helpers"| UPLOAD_HELP
    HELP_TEXT -->|"invoke helpers"| PROGRESS
    YT_DL_BUTTON -->|"invoke helpers"| FFMPEG_UTILS
    YT_DL_ECHO -->|"invoke helpers"| FFMPEG_UTILS

    ADMIN -->|"DB CRUD"| DB_CONN
    BROADCAST -->|"DB CRUD"| ACCESS
    BUTTONS -->|"DB CRUD"| DB_CONN
    CALLBACK -->|"DB CRUD"| ACCESS
    CUSTOM_THUMB -->|"DB CRUD"| ADDUSER
    DL_BUTTON -->|"DB CRUD"| ACCESS
    FORCESUB -->|"DB CRUD"| ADDUSER
    HELP_TEXT -->|"DB CRUD"| DB_CONN
    YT_DL_BUTTON -->|"DB CRUD"| ACCESS
    YT_DL_ECHO -->|"DB CRUD"| ADDUSER

    %% Helpers to External tools and services
    PROGRESS -->|"track download/upload"| TOOLS
    FFMPEG_UTILS -->|"process media"| TOOLS
    UPLOAD_HELP -->|"send via Pyrogram"| BOT

    %% Data Access to MongoDB
    DB_CONN -->|"connect"| MONGODB
    ACCESS -->|"query/update"| MONGODB
    ADDUSER -->|"insert/delete"| MONGODB

    %% Outbound responses
    BOT -->|"Send Media/Replies"| TELEGRAM_API

    %% Click Events
    click BOT "https://github.com/ritikroy960/uploader-bot/blob/V3.0/bot.py"
    click CONFIG "https://github.com/ritikroy960/uploader-bot/blob/V3.0/config.py"
    click TRANS "https://github.com/ritikroy960/uploader-bot/blob/V3.0/translation.py"
    click DB_CONN "https://github.com/ritikroy960/uploader-bot/blob/V3.0/database/database.py"
    click ACCESS "https://github.com/ritikroy960/uploader-bot/blob/V3.0/database/access.py"
    click ADDUSER "https://github.com/ritikroy960/uploader-bot/blob/V3.0/database/adduser.py"
    click PROGRESS "https://github.com/ritikroy960/uploader-bot/blob/V3.0/helper_funcs/display_progress.py"
    click FFMPEG_UTILS "https://github.com/ritikroy960/uploader-bot/blob/V3.0/helper_funcs/help_Nekmo_ffmpeg.py"
    click UPLOAD_HELP "https://github.com/ritikroy960/uploader-bot/blob/V3.0/helper_funcs/help_uploadbot.py"
    click ADMIN "https://github.com/ritikroy960/uploader-bot/blob/V3.0/plugins/admin.py"
    click BROADCAST "https://github.com/ritikroy960/uploader-bot/blob/V3.0/plugins/broadcast.py"
    click BUTTONS "https://github.com/ritikroy960/uploader-bot/blob/V3.0/plugins/buttons.py"
    click CALLBACK "https://github.com/ritikroy960/uploader-bot/blob/V3.0/plugins/callback.py"
    click CUSTOM_THUMB "https://github.com/ritikroy960/uploader-bot/blob/V3.0/plugins/custom_thumbnail.py"
    click DL_BUTTON "https://github.com/ritikroy960/uploader-bot/blob/V3.0/plugins/dl_button.py"
    click FORCESUB "https://github.com/ritikroy960/uploader-bot/blob/V3.0/plugins/forcesub.py"
    click HELP_TEXT "https://github.com/ritikroy960/uploader-bot/blob/V3.0/plugins/help_text.py"
    click YT_DL_BUTTON "https://github.com/ritikroy960/uploader-bot/blob/V3.0/plugins/youtube_dl_button.py"
    click YT_DL_ECHO "https://github.com/ritikroy960/uploader-bot/blob/V3.0/plugins/youtube_dl_echo.py"

    classDef component fill:#B3CDE3,stroke:#03396C,color:#03396C
    classDef plugin fill:#6497B1,stroke:#005B96,color:#FFFFFF
    classDef helper fill:#B3CDE3,stroke:#03396C,color:#03396C
    classDef data fill:#FBB4AE,stroke:#B10026,color:#7F0000
    classDef cloud fill:#C7E9B4,stroke:#238B45,color:#006d2c
    classDef db fill:#FED9A6,stroke:#D95F02,color:#662506
    classDef gear fill:#DECBE4,stroke:#6A51A3,color:#2D004B
```
