# elimeshi1/videoresbot architecture

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

- Interactive diagram: https://gitdiagram.com/elimeshi1/videoresbot
- Repository: https://github.com/elimeshi1/videoresbot

## Overview

##### Project Type and Purpose
- This is a specialized full-stack automation tool (Telegram bot + userbot) that offloads video processing to Telegram’s native pipeline.
- Purpose: receive user videos → schedule them in a 10K+ channel → detect processed variants → deliver back to users.

##### File Structure
- Top-level directories:
- config: environment and constant definitions
- handlers: orchestrates commands, payment, video flows
- utils: core services (DB, logging, queue, cleanup, video processing)
- main.py: bootstraps both the bot and the userbot
- Patterns:
- Dual clients (Bot API client vs Telethon userbot)
- Queue management for scheduling messages
- Background polling for status updates
- Modular handlers for commands (general, premium) and subsystems (payment, video)

##### Extract Key Architectural Insights from README
- Dual Client Architecture:
- Bot client for direct user interactions
- Userbot client for channel operations
- External Dependencies:
- Telegram Bot API
- Telethon (for userbot)
- SQLite (for subscription and job tracking)

##### Main Components
a. User Interaction Layer
- Telegram Bot (main.py → Bot API client)
- Handlers/commands (general.py, premium.py)
b. Processing Orchestration
- Queue Manager (utils/queue_manager.py)
- Video Processor (utils/video_processor.py + utils/video_utils.py)
- Database (utils/db.py → SQLite)
c. Channel Automation Layer (Userbot)
- Telethon client
- Operations: transfer→destination→junk (handlers/video/channel.py, handlers/video/private.py)
- Payment & Channel Management (handlers/payment/)
d. Monitoring & Cleanup
- Status polling loop (config/state.py + handlers/video)
- Cleanup tasks (utils/cleanup.py)
e. External Systems
- Telegram API endpoints (Bot HTTP API & MTProto for userbot)
- Three Telegram channels:
– Transfer channel
– 10K+ subscriber destination channel
– Junk/status monitoring channel

##### Interactions and Data Flow
1. User → Bot API → Bot client
2. Bot client enqueues video job → SQLite queue table
3. Queue Manager dequeues job → sends video via userbot to Transfer Channel
4. Userbot schedules video in Destination Channel
5. Monitoring loop polls Junk Channel for processing completion events
6. Once multiple quality versions appear, userbot fetches them → stores references
7. Bot client sends processed videos back to user
8. Cleanup process deletes scheduled messages in Destination/Junk channels

##### Architectural Patterns & Principles
- Dual-client segmentation: clear separation between user-facing bot and backend userbot
- Queue/worker pattern: decouple video acceptance from channel scheduling
- Observer/polling: continuously monitor external changes (polling Junk Channel)
- Modular handler pattern: each subsystem (commands, payment, video, cleanup) lives in its own package

- Clear labels: component names, file references (e.g., utils/queue_manager.py)
- Optional notes: configuration source (config/config.py), environment variables (.env)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction Layer"
        main["main.py\n(Bot Entry Point)"]:::frontend
        gen["General Commands\nhandlers/commands/general.py"]:::frontend
        prem["Premium Commands\nhandlers/commands/premium.py"]:::frontend
    end

    %% Core Orchestration
    subgraph "Core Orchestration"
        queue["Queue Manager\nutils/queue_manager.py"]:::core
        vp["Video Processor\nutils/video_processor.py"]:::core
        vu["Video Utilities\nutils/video_utils.py"]:::core
        db["SQLite DB\nutils/db.py"]:::core
    end

    %% Channel Automation Layer
    subgraph "Channel Automation Layer"
        chanOps["Channel Operations\nhandlers/video/channel.py"]:::automation
        privVid["Private Video Handlers\nhandlers/video/private.py"]:::automation
        payMgmt["Payment Management\nhandlers/payment/channel_management_handlers.py"]:::automation
        payView["Payment View\nhandlers/payment/channel_view_handlers.py"]:::automation
        inv["Invoice Handlers\nhandlers/payment/invoice_handlers.py"]:::automation
        menu["Payment Menu Handlers\nhandlers/payment/menu_handlers.py"]:::automation
        help["Payment Helpers\nhandlers/payment/helpers.py"]:::automation
    end

    %% Monitoring & Cleanup
    subgraph "Monitoring & Cleanup"
        state["State Definitions\nconfig/state.py"]:::core
        cleanup["Cleanup Service\nutils/cleanup.py"]:::core
    end

    %% Configuration
    subgraph "Configuration"
        configEnv["Config Constants\nconfig/config.py"]:::config
        configMsg["Message Templates\nconfig/messages.py"]:::config
    end

    %% External Telegram Systems
    subgraph "External Telegram Systems"
        BotAPI["Telegram Bot API"]:::external
        MTProto["Telegram MTProto API"]:::external
        transferChan["Transfer Channel"]:::external
        destChan["Destination Channel"]:::external
        junkChan["Junk Channel"]:::external
    end

    %% External User
    User["User"]:::external

    %% Connections
    User --> main
    main --> gen
    main --> prem
    main --> BotAPI
    gen --> db
    prem --> db
    gen --> queue
    prem --> queue
    queue --> db
    queue --> chanOps
    chanOps --> MTProto
    chanOps --> transferChan
    transferChan --> destChan
    destChan --> junkChan
    junkChan --> privVid
    privVid --> MTProto
    privVid --> db
    privVid --> vp
    vp --> vu
    vp --> main
    privVid --> state
    cleanup --> destChan
    cleanup --> junkChan
    cleanup --> state
    state --> privVid
    configEnv --> main
    configMsg --> main

    %% Click Events
    click main "https://github.com/elimeshi1/videoresbot/blob/main/main.py"
    click gen "https://github.com/elimeshi1/videoresbot/blob/main/handlers/commands/general.py"
    click prem "https://github.com/elimeshi1/videoresbot/blob/main/handlers/commands/premium.py"
    click queue "https://github.com/elimeshi1/videoresbot/blob/main/utils/queue_manager.py"
    click vp "https://github.com/elimeshi1/videoresbot/blob/main/utils/video_processor.py"
    click vu "https://github.com/elimeshi1/videoresbot/blob/main/utils/video_utils.py"
    click db "https://github.com/elimeshi1/videoresbot/blob/main/utils/db.py"
    click chanOps "https://github.com/elimeshi1/videoresbot/blob/main/handlers/video/channel.py"
    click privVid "https://github.com/elimeshi1/videoresbot/blob/main/handlers/video/private.py"
    click payMgmt "https://github.com/elimeshi1/videoresbot/blob/main/handlers/payment/channel_management_handlers.py"
    click payView "https://github.com/elimeshi1/videoresbot/blob/main/handlers/payment/channel_view_handlers.py"
    click inv "https://github.com/elimeshi1/videoresbot/blob/main/handlers/payment/invoice_handlers.py"
    click menu "https://github.com/elimeshi1/videoresbot/blob/main/handlers/payment/menu_handlers.py"
    click help "https://github.com/elimeshi1/videoresbot/blob/main/handlers/payment/helpers.py"
    click state "https://github.com/elimeshi1/videoresbot/blob/main/config/state.py"
    click cleanup "https://github.com/elimeshi1/videoresbot/blob/main/utils/cleanup.py"
    click configEnv "https://github.com/elimeshi1/videoresbot/blob/main/config/config.py"
    click configMsg "https://github.com/elimeshi1/videoresbot/blob/main/config/messages.py"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#333,color:#000
    classDef core fill:#C2F0C2,stroke:#333,color:#000
    classDef automation fill:#F7D6AE,stroke:#333,color:#000
    classDef external fill:#E0E0E0,stroke:#333,color:#000
    classDef config fill:#D3C0EB,stroke:#333,color:#000
```
