How the-moontg-project/moon-userbot works
Project Type & Purpose
• This is a Python-based, event-driven Telegram “userbot” (i.e., a self-hosted bot client that logs in as a user)
• It exposes a plugin architecture: core bootstrap + dynamically loaded command modules + shared utilities
• Supports both SQLite and MongoDB for persistence and integrates multiple external AI/image/metadata services
Top-Level Components
1. Bot Core
• app.py / main.py: starts the application, reads config, initializes Pyrogram client
• modules/loader.py & utils/module.py: dynamically discover & load each command module
• utils/handlers.py: central dispatcher for incoming Telegram events
2. Modules Directory
• modules/*.py: individual command handlers (e.g., afk.py, updater.py, shell.py)
• Each module registers commands/triggers with the core handler
3. Utilities Layer
• utils/config.py: environment‐var parsing, defaults (.env / .env.dist)
• utils/db.py: abstracted DB interface for SQLite (db.sqlite3) or MongoDB (via DATABASE_URL)
• utils/conv.py, utils/misc.py, utils/rentry.py, utils/scripts.py: helper routines
4. External Services
• Telegram API (via Pyrogram)
• AI/Image APIs: Gemini, Cohere, ChatGPT3.5, SDXL, DALL-E, Upscaling, RemoveBG, VirusTotal, APIFLASH
5. Deployment & Orchestration
• Docker (Dockerfile, docker-compose.yml, compose.yml)
• Cloud CI/CD: GitHub Actions, Render/Heroku/Koyeb Cloudfiles & Procfile
• Nix packs, .gitpod.yml, install scripts (install.sh, install.py, install_yum.sh, termux-install.sh)
Relationships & Data Flows
• Startup: main.py → read .env via config.py → initialize Pyrogram client
• Event Loop: Telegram → Pyrogram Client → handlers.py dispatch → loader.py picks module → module logic
• Persistent Storage: Modules & utilities call db.py → SQLite file or MongoDB cluster
• External API Calls: Modules invoke AI/image services over HTTPS (API keys via env)
• Response: Module returns result → handlers.py → Pyrogram Client → Telegram network
Architectural Patterns & Principles
• Plugin Architecture: loose coupling; modules adhere to a common interface for registration & teardown
• Event-Driven: core dispatcher routes messages to appropriate module handlers
• Abstraction: db.py hides underlying DB type; config.py centralizes all environment logic
• Single-Process Monolith: no separate microservices; everything lives in one container/process
Technologies & Frameworks
• Language: Python 3.x
• Telegram Client: Pyrogram (Pyrofork) + pytgcalls
• DB Engines: SQLite3 or MongoDB
• Containerization: Docker, Docker Compose, Nixpacks
• CI/CD: GitHub Actions, Render/Heroku/Koyeb cloud templates
• Scripting: Bash (*.sh), Python installers