# quirkysiiiiiid/vj-filter-bot architecture

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

- Interactive diagram: https://gitdiagram.com/quirkysiiiiiid/vj-filter-bot
- Repository: https://github.com/quirkysiiiiiid/vj-filter-bot

## Overview

##### Project Type and Purpose
- This is a Python-based Telegram bot (using the Pyrogram library) that provides filter/search/clone/stream features, backed by MongoDB, and packaged for deployment on Heroku, Render, or any Docker-enabled host.
- No traditional “frontend” – the user interface is Telegram itself; the code comprises a monolithic backend with a plugin-based architecture.

##### Main Components
A. Telegram Client Layer
- Pyrogram client instantiated in bot.py
- Handles incoming updates (commands, messages) and outgoing responses
B. Core Business Logic
- Command router: commands.py, broadcast.py, pm_filter.py, Script.py
- Clone features: CloneTechVJ/ (broadcast.py, commands.py, pm_filter.py)
- TechVJ modules:
- bot/clients.py (low-level Pyrogram wrappers)
- server/exceptions.py (error classes, if HTTP endpoints exist)
- template/dl.html, req.html (HTML templates for links or web pages)
C. Plugin Framework
- plugins/ directory: dozens of independent modules (e.g., auto_approve, stream, rename, fonts, openai)
- Each plugin defines a set of handlers that register with the main router at startup
D. Utilities & Helpers
- TechVJ/util: config_parser.py, render_template.py, file_size.py, human_readable.py, keepalive.py, time_format.py, custom_dl.py
- utils.py at root for general helpers
E. Data Layer
- MongoDB connection & abstraction:
- database/connections_mdb.py (per-chat connection records)
- database/filters_mdb.py, gfilters_mdb.py, ia_filterdb.py (filter storage)
- database/join_reqs.py (join request tracking)
- database/users_chats_db.py (user & chat metadata)
- CloneTechVJ/database/clone_bot_userdb.py (clone-specific user DB)
F. Configuration & Secrets
- info.py (environment variables loader)
- runtime.txt, requirements.txt, Dockerfile, Procfile, heroku.yml
G. External Services
- Telegram API
- MongoDB Atlas (DATABASE_URI)
- (Optional) UptimeRobot or Render health-check monitor
- Optional logging channel (LOG_CHANNEL)

##### Relationships & Data Flows
1. Telegram client receives an Update → passes to Command Router
2. Router dispatches to one of:
– Core command modules (e.g., /clone, /filter)
– Plugin module (auto_approve, tts, openai, etc.)
3. Handler executes business logic, which may:
– Read/write from MongoDB via the database/ abstraction layer
– Render an HTML template (render_template.py + template/*.html) for link pages
– Interact with external APIs (e.g., YouTube DL in custom_dl.py, OpenAI, URL shortener)
– Send messages back via Pyrogram client
4. Broadcast jobs (broadcast.py) iterate user/chat collections, send mass messages

##### Architectural Patterns & Principles
- Modular monolith with plugin registry: new features live in plugins/ and CloneTechVJ/.
- Layered design: separation between transport (Telegram client), business logic (commands + plugins), data access (database modules), and utilities.
- Configuration via environment (info.py + config_parser) supports 12-factor app principles.
- Template rendering for any optional HTTP interface or rich Telegram messages.

##### Diagramming Conventions
– Rounded rectangle: process or module (e.g., “Command Router”)
– Cloud: external APIs/Telegram
– Hexagon or gear: plugin modules
– Blue for core bot components
– Green for database layers
– Orange for external services
– Gray for utilities
– Clearly name each module (e.g., “TechVJ/util”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    TelegramAPI["Telegram API"]:::external
    MongoDB["MongoDB Atlas"]:::database
    HealthCheck["Health Check / Monitoring"]:::external

    %% Deployment Boundary
    subgraph "Docker / Heroku / Render"
        direction TB
        subgraph "Bot Application (Python Runtime)"
            direction TB

            %% Telegram Client Layer
            subgraph "Telegram Client Layer"
                direction TB
                BotPy["bot.py"]:::core
                Clients["TechVJ/bot/clients.py"]:::core
            end

            %% Command & Plugin Dispatcher
            subgraph "Command & Plugin Dispatcher"
                direction TB
                Commands["commands.py"]:::core
                Broadcast["broadcast.py"]:::core
                PMFilter["pm_filter.py"]:::core
                Script["Script.py"]:::core
                Plugins["plugins/"]:::plugin
            end

            %% CloneTechVJ Module
            subgraph "CloneTechVJ Module"
                direction TB
                CTCommands["CloneTechVJ/commands.py"]:::core
                CTBroadcast["CloneTechVJ/broadcast.py"]:::core
                CTPMFilter["CloneTechVJ/pm_filter.py"]:::core
                CTUserDB["CloneTechVJ/database/clone_bot_userdb.py"]:::database
            end

            %% Utilities & Helpers
            subgraph "Utilities & Helpers"
                direction TB
                ConfigParser["TechVJ/util/config_parser.py"]:::util
                RenderTemplateUtil["TechVJ/util/render_template.py"]:::util
                CustomDL["TechVJ/util/custom_dl.py"]:::util
                FileProps["TechVJ/util/file_properties.py"]:::util
                FileSize["TechVJ/util/file_size.py"]:::util
                HumanReadable["TechVJ/util/human_readable.py"]:::util
                KeepAlive["TechVJ/util/keepalive.py"]:::util
                TimeFormat["TechVJ/util/time_format.py"]:::util
                UtilsRoot["utils.py"]:::util
            end

            %% Template Engine & HTML Templates
            subgraph "Template Engine"
                direction TB
                RenderTemplate["TechVJ/util/render_template.py"]:::util
                DLHTML["TechVJ/template/dl.html"]:::util
                REQHTML["TechVJ/template/req.html"]:::util
            end

            %% HTTP/Server Exceptions
            ServerExc["TechVJ/server/exceptions.py"]:::util

            %% Data Access Layer
            subgraph "Data Access Layer"
                direction TB
                ConnMDB["database/connections_mdb.py"]:::database
                FiltersMDB["database/filters_mdb.py"]:::database
                GFiltersMDB["database/gfilters_mdb.py"]:::database
                IAFilters["database/ia_filterdb.py"]:::database
                JoinReqs["database/join_reqs.py"]:::database
                UsersChatsDB["database/users_chats_db.py"]:::database
            end

            %% Configuration & Deployment Manifests
            subgraph "Configuration & Deployment"
                direction TB
                InfoPy["info.py"]:::config
                Requirements["requirements.txt"]:::config
                RuntimeTxt["runtime.txt"]:::config
                Dockerfile["Dockerfile"]:::config
                Procfile["Procfile"]:::config
                HerokuYML["heroku.yml"]:::config
                LoggingConf["logging.conf"]:::config
            end

        end
    end

    %% Data Flows
    TelegramAPI -->|"Update"| BotPy
    BotPy -->|"instantiates client"| Clients
    BotPy -->|"forwards update"| Commands
    Commands --> Plugins
    Commands --> Broadcast
    Commands --> PMFilter
    Commands --> Script
    Commands --> CTCommands
    Commands --> CTBroadcast
    Commands --> CTPMFilter

    Plugins -->|"handler logic"| ConnMDB
    Commands -->|"access filters"| FiltersMDB
    Commands --> FiltersMDB
    Commands --> GFiltersMDB
    Commands --> IAFilters
    Commands --> JoinReqs
    Commands --> UsersChatsDB
    CTCommands --> CTUserDB

    Commands -->|"uses util"| ConfigParser
    Commands --> RenderTemplateUtil
    Plugins --> CustomDL
    Plugins --> FileProps
    Plugins --> FileSize
    Plugins --> HumanReadable
    Plugins --> KeepAlive
    Plugins --> TimeFormat
    Commands --> UtilsRoot

    RenderTemplateUtil --> DLHTML
    RenderTemplateUtil --> REQHTML
    ServerExc --> DLHTML

    Commands -->|"send response"| BotPy
    Commands -->|"broadcast jobs"| Broadcast

    BotPy --> TelegramAPI

    %% Health Check
    HealthCheck -.->|pings| BotPy

    %% Database connection
    ConnMDB --> MongoDB
    FiltersMDB --> MongoDB
    GFiltersMDB --> MongoDB
    IAFilters --> MongoDB
    JoinReqs --> MongoDB
    UsersChatsDB --> MongoDB
    CTUserDB --> MongoDB

    %% Click Events
    click BotPy "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/bot.py"
    click Clients "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/bot/clients.py"
    click Commands "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/commands.py"
    click Broadcast "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/broadcast.py"
    click PMFilter "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/pm_filter.py"
    click Script "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/Script.py"
    click CTCommands "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/CloneTechVJ/commands.py"
    click CTBroadcast "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/CloneTechVJ/broadcast.py"
    click CTPMFilter "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/CloneTechVJ/pm_filter.py"
    click CTUserDB "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/CloneTechVJ/database/clone_bot_userdb.py"
    click Plugins "https://github.com/quirkysiiiiiid/vj-filter-bot/tree/Tech_VJ/plugins/"
    click ConfigParser "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/util/config_parser.py"
    click RenderTemplateUtil "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/util/render_template.py"
    click CustomDL "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/util/custom_dl.py"
    click FileProps "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/util/file_properties.py"
    click FileSize "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/util/file_size.py"
    click HumanReadable "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/util/human_readable.py"
    click KeepAlive "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/util/keepalive.py"
    click TimeFormat "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/util/time_format.py"
    click UtilsRoot "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/utils.py"
    click DLHTML "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/template/dl.html"
    click REQHTML "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/template/req.html"
    click ServerExc "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/TechVJ/server/exceptions.py"
    click ConnMDB "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/database/connections_mdb.py"
    click FiltersMDB "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/database/filters_mdb.py"
    click GFiltersMDB "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/database/gfilters_mdb.py"
    click IAFilters "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/database/ia_filterdb.py"
    click JoinReqs "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/database/join_reqs.py"
    click UsersChatsDB "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/database/users_chats_db.py"
    click InfoPy "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/info.py"
    click Requirements "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/requirements.txt"
    click RuntimeTxt "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/runtime.txt"
    click Dockerfile "https://github.com/quirkysiiiiiid/vj-filter-bot/tree/Tech_VJ/Dockerfile"
    click Procfile "https://github.com/quirkysiiiiiid/vj-filter-bot/tree/Tech_VJ/Procfile"
    click HerokuYML "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/heroku.yml"
    click LoggingConf "https://github.com/quirkysiiiiiid/vj-filter-bot/blob/Tech_VJ/logging.conf"

    %% Styles
    classDef core fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef plugin fill:#FFF8E1,stroke:#FF6F00,color:#E65100
    classDef database fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32
    classDef util fill:#ECEFF1,stroke:#37474F,color:#263238
    classDef config fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
    classDef external fill:#FFE0B2,stroke:#E65100,color:#BF360C
```
