# vjbots/vj-filter-bot architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source, modular Telegram bot (named “VJ Filter Bot”) built in Python using the Pyrogram library.
- Its primary purpose is to provide cloning, filtering, renaming, streaming, subscription enforcement, and various utility commands inside Telegram chats and groups, backed by MongoDB.

##### File structure
- Top-level scripts:
- bot.py / CloneTechVJ/broadcast.py / Script.py / info.py – entry points and command orchestrators
- Dockerfile / Procfile / heroku.yml – deployment descriptors
- Core package: **TechVJ/**
- TechVJ/bot/clients.py – Telegram client abstraction
- TechVJ/server/ – small HTTP server (serving dl.html, req.html) for user flows
- TechVJ/util/ – helpers (config parsing, file size, human-readable, template rendering, keepalive, time formatting)
- Database layer: **database/** & **CloneTechVJ/database/**
- Multiple modules (clone_bot_userdb.py, connections_mdb.py, filters_mdb.py, users_chats_db.py, etc.) – wrappers around MongoDB operations
- Plugins: **plugins/**
- plugins/Extra/… – extended commands (auto-approve, openai, font, stream, etc.)
- plugins/*.py – core feature plugins (clone, filters, broadcast, pm_filter, etc.)
- Configuration:
- README.md – environment variables (BOT_TOKEN, API_ID/HASH, DATABASE_URI, etc.)
- requirements.txt – Python dependencies

##### README for additional insights
- Features toggleable via environment flags
- Uses Pyrogram / Pyrofork for Telegram API
- MongoDB for persistence
- Templates for in-chat IMDB rendering and HTTP download/join flows
- Hosted on platforms like Heroku, Render, Koyeb, or any VPS

##### Components
a. Main components:
1. Telegram API (external)
2. Bot Service (Python process)
– Core Telegram client (Pyrogram)
– Command dispatcher & plugin loader
– Utilities & template renderer
– Built-in HTTP server (for download pages)
3. Database (MongoDB cluster)
4. File / Media Channel (Telegram channel or external storage)
5. Deployment & CI/CD (Docker / Heroku / Render / VPS)
6. Optional External Services (e.g., OpenAI for spell-check plugin, URL-shortener APIs)
b. Relationships & interactions:
- Bot Service ↔ Telegram API: Bi-directional (receives updates, sends messages)
- Bot Service → MongoDB: CRUD on users, filters, sessions, premium status
- Bot Service → HTTP server (internal module) → End Users: Serves dl.html or req.html when they click links
- Bot Service ↔ External APIs: e.g., OpenAI, telegraph, yt-dl
- Deployment platform ↔ Bot Service: Starts/stops container or Python process
c. Architectural patterns & design principles:
- Modular plugin architecture: Each feature encapsulated in a plugin module under plugins/
- Layered design:
– Presentation (Telegram client + HTTP server + templates)
– Business logic (commands.py, broadcast.py, pm_filter.py, util/)
– Data access (database/… modules)
- Configuration via environment variables for twelve-factor adherence
d. Key technologies & frameworks:
- Python 3.x, Pyrogram (Telegram client library)
- MongoDB (via pymongo or motor)
- Docker, Procfile (Heroku), heroku.yml, Render/Koyeb manifests
- Jinja2 or custom HTML templates (dl.html, req.html)
- Optional APIs: OpenAI, Telegraph, YouTube-DL

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    TelegramAPI["Telegram API"]:::external
    EndUser["End Users"]:::external

    %% Bot Service
    subgraph "Bot Service (Python Process)"
        direction TB
        subgraph "Core Components"
            direction TB
            subgraph "Entry Points & Dispatcher"
                direction TB
                Bot_py["bot.py"]:::internal
                Broadcast_py["CloneTechVJ/broadcast.py"]:::internal
                Commands_py["CloneTechVJ/commands.py"]:::internal
                Script_py["Script.py"]:::internal
                Info_py["info.py"]:::internal
            end
            subgraph "Client & Manager"
                direction TB
                Client["Telegram Client Abstraction"]:::internal
                PluginManager["Plugin Manager"]:::internal
            end
            subgraph "HTTP Server & Templates"
                direction TB
                HTTPServer["Built-in HTTP Server"]:::internal
                DL_html["dl.html"]:::internal
                REQ_html["req.html"]:::internal
            end
            subgraph "Utilities & Template Renderer"
                direction TB
                Render["render_template.py"]:::internal
                ConfigParser["config_parser.py"]:::internal
                KeepAlive["keepalive.py"]:::internal
                TimeFmt["time_format.py"]:::internal
                FileSize["file_size.py"]:::internal
                HumanReadable["human_readable.py"]:::internal
                FileProps["file_properties.py"]:::internal
                CustomDL["custom_dl.py"]:::internal
            end
        end
        subgraph "Plugins"
            direction TB
            subgraph "Core Feature Plugins"
                direction TB
                PClone["plugins/clone.py"]:::internal
                PFilters["plugins/filters.py"]:::internal
                PPM["plugins/pm_filter.py"]:::internal
                PBroad["plugins/broadcast.py"]:::internal
                POther["plugins/__init__.py & others"]:::internal
            end
            subgraph "Extended (Extra) Plugins"
                direction TB
                EA["plugins/Extra/auto_approve/approve.py"]:::internal
                EB["plugins/Extra/openai.py"]:::internal
                EC["plugins/Extra/telegraph.py"]:::internal
                ED["plugins/Extra/yt_dl.py"]:::internal
                ES["plugins/Extra/stream/stream.py"]:::internal
                EF["plugins/Extra/font.py"]:::internal
                EOther["plugins/Extra/..."]:::internal
            end
        end
        subgraph "Database Layer"
            direction TB
            ConnDB["database/connections_mdb.py"]:::internal
            FiltersDB["database/filters_mdb.py"]:::internal
            GFiltersDB["database/gfilters_mdb.py"]:::internal
            IAFilterDB["database/ia_filterdb.py"]:::internal
            JoinReqs["database/join_reqs.py"]:::internal
            UsersChats["database/users_chats_db.py"]:::internal
            CloneUserDB["CloneTechVJ/database/clone_bot_userdb.py"]:::internal
        end
    end

    %% External Services and Database
    Database["MongoDB Cluster"]:::db
    subgraph "External APIs"
        direction TB
        OpenAI["OpenAI API"]:::external
        TelegraphAPI["Telegraph API"]:::external
        YTDLAPI["YouTube-DL"]:::external
    end

    Deployment["Deployment (Docker/Heroku/VPS)"]:::deploy
    ConfigDocs["Config & Docs"]:::config
    Logging["Logging/Monitoring"]:::config

    %% Connections
    TelegramAPI -->|"updates & messages"| Client
    Bot_py --> PluginManager
    Broadcast_py --> PluginManager
    Commands_py --> PluginManager
    Script_py --> PluginManager
    Info_py --> PluginManager
    Client --> PluginManager
    PluginManager --> PClone & PFilters & PPM & PBroad & POther & EA & EB & EC & ED & ES & EF & EOther
    PluginManager --> OpenAI & TelegraphAPI & YTDLAPI
    PluginManager --> Database
    ConnDB & FiltersDB & GFiltersDB & IAFilterDB & JoinReqs & UsersChats & CloneUserDB --> Database
    PluginManager --> HTTPServer
    HTTPServer --> DL_html & REQ_html
    DL_html & REQ_html --> EndUser
    PluginManager --> Render
    Render --> ConfigParser & KeepAlive & TimeFmt & FileSize & HumanReadable & FileProps & CustomDL
    ConfigDocs --> ConfigParser
    Bot_py & Broadcast_py & Commands_py & Script_py & Info_py --> ConfigParser
    Bot_py & Broadcast_py & Commands_py & Script_py & Info_py --> Logging
    Deployment --> Bot_py & Client & PluginManager

    %% Click Events
    click Client "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/bot/clients.py"
    click Bot_py "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/bot.py"
    click Broadcast_py "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/CloneTechVJ/broadcast.py"
    click Commands_py "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/CloneTechVJ/commands.py"
    click Script_py "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/Script.py"
    click Info_py "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/info.py"
    click HTTPServer "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/server/exceptions.py"
    click DL_html "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/template/dl.html"
    click REQ_html "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/template/req.html"
    click Render "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/util/render_template.py"
    click ConfigParser "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/util/config_parser.py"
    click KeepAlive "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/util/keepalive.py"
    click TimeFmt "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/util/time_format.py"
    click FileSize "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/util/file_size.py"
    click HumanReadable "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/util/human_readable.py"
    click FileProps "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/util/file_properties.py"
    click CustomDL "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/TechVJ/util/custom_dl.py"
    click ConnDB "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/database/connections_mdb.py"
    click FiltersDB "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/database/filters_mdb.py"
    click GFiltersDB "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/database/gfilters_mdb.py"
    click IAFilterDB "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/database/ia_filterdb.py"
    click JoinReqs "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/database/join_reqs.py"
    click UsersChats "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/database/users_chats_db.py"
    click CloneUserDB "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/CloneTechVJ/database/clone_bot_userdb.py"
    click PClone "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/plugins/clone.py"
    click PFilters "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/plugins/filters.py"
    click PPM "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/plugins/pm_filter.py"
    click PBroad "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/plugins/broadcast.py"
    click POther "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/plugins/__init__.py"
    click EA "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/plugins/Extra/auto_approve/approve.py"
    click EB "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/plugins/Extra/openai.py"
    click EC "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/plugins/Extra/telegraph.py"
    click ED "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/plugins/Extra/yt_dl.py"
    click ES "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/plugins/Extra/stream/stream.py"
    click EF "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/plugins/Extra/font.py"
    click Deployment "https://github.com/vjbots/vj-filter-bot/tree/Tech_VJ/Dockerfile"
    click Deployment "https://github.com/vjbots/vj-filter-bot/tree/Tech_VJ/Procfile"
    click Deployment "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/heroku.yml"
    click Deployment "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/runtime.txt"
    click ConfigDocs "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/README.md"
    click ConfigDocs "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/requirements.txt"
    click Logging "https://github.com/vjbots/vj-filter-bot/blob/Tech_VJ/logging.conf"

    %% Styles
    classDef external fill:#E0F7FA,stroke:#006064,color:#006064
    classDef internal fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef db fill:#E3F2FD,stroke:#1565C0,color:#1565C0
    classDef deploy fill:#ECEFF1,stroke:#455A64,color:#455A64
    classDef config fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00
```
