How quirkysiiiiiid/vj-filter-bot works
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”)