# the-moontg-project/moon-userbot architecture

> Architecture diagram of the GitHub repository the-moontg-project/moon-userbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/the-moontg-project/moon-userbot
- Repository: https://github.com/the-moontg-project/moon-userbot

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration
    subgraph "Configuration" 
        direction TB
        EnvFile[".env.dist"]:::codeComp
        Config["utils/config.py"]:::codeComp
    end

    %% Bot Core
    subgraph "Bot Core" 
        direction TB
        EntryApp1["app.py"]:::codeComp
        EntryApp2["main.py"]:::codeComp
        Loader["modules/loader.py"]:::codeComp
        ModuleUtil["utils/module.py"]:::codeComp
        Handler["utils/handlers.py"]:::codeComp
        PyroClient["Pyrogram Client"]:::external
    end

    %% Modules
    subgraph "Modules Directory" 
        direction TB
        AFK["modules/afk.py"]:::codeComp
        Updater["modules/updater.py"]:::codeComp
        Shell["modules/shell.py"]:::codeComp
        MoreModules["... other modules ..."]:::codeComp
    end

    %% Utilities Layer
    subgraph "Utilities" 
        direction TB
        DBUtil["utils/db.py"]:::codeComp
        Conv["utils/conv.py"]:::codeComp
        Misc["utils/misc.py"]:::codeComp
        Rentry["utils/rentry.py"]:::codeComp
        Scripts["utils/scripts.py"]:::codeComp
    end

    %% Database Engines
    subgraph "Databases" 
        direction TB
        SQLite["SQLite (db.sqlite3)"]:::db
        MongoDB["MongoDB"]:::db
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        TelegramAPI["Telegram API"]:::external
        Gemini["Gemini AI"]:::external
        Cohere["Cohere"]:::external
        ChatGPT["ChatGPT3.5"]:::external
        SDXL["SDXL"]:::external
        Dalle["DALL·E"]:::external
        Upscale["Upscaling"]:::external
        RemoveBG["RemoveBG"]:::external
        VirusTotal["VirusTotal"]:::external
        APIFLASH["APIFLASH"]:::external
    end

    %% Deployment & Orchestration
    subgraph "Deployment & Orchestration" 
        direction TB
        subgraph "Docker" 
            direction TB
            Dockerfile["Dockerfile"]:::deploy
            Compose1["docker-compose.yml"]:::deploy
            Compose2["compose.yml"]:::deploy
        end
        subgraph "Cloud Templates" 
            direction TB
            RenderYAML["render.yaml"]:::deploy
            Cloudfile["Cloudfile"]:::deploy
            Procfile["Procfile"]:::deploy
            GHWorkflow1[".github/workflows/docker-image.yml"]:::deploy
            GHWorkflow2[".github/workflows/cloud-image.yml"]:::deploy
        end
        subgraph "CI/CD & DevEnv" 
            direction TB
            GHAll[".github/workflows/*"]:::deploy
            Gitpod[".gitpod.yml"]:::deploy
            Nixpacks["nixpacks.toml"]:::deploy
            DevNix[".idx/dev.nix"]:::deploy
        end
        subgraph "Install Scripts" 
            direction TB
            InstallSh["install.sh"]:::deploy
            InstallPy["install.py"]:::deploy
            YumSh["install_yum.sh"]:::deploy
            Termux["termux-install.sh"]:::deploy
            CloudSh["cloud.sh"]:::deploy
        end
    end

    %% Relationships
    EnvFile -->|reads| Config
    Config -->|provides env| EntryApp1
    Config -->|provides env| EntryApp2
    EntryApp1 -->|initializes| PyroClient
    EntryApp2 -->|initializes| PyroClient
    PyroClient -->|forwards events| Handler
    Handler -->|dispatches| Loader
    Loader -->|loads| AFK
    Loader -->|loads| Updater
    Loader -->|loads| Shell
    Loader -->|loads| MoreModules
    AFK -->|uses| DBUtil
    Updater -->|uses| DBUtil
    Shell -->|uses| DBUtil
    MoreModules -->|uses| DBUtil
    DBUtil -->|manages| SQLite
    DBUtil -->|manages| MongoDB
    AFK -->|calls| Gemini
    AFK -->|calls| Cohere
    Updater -->|calls| ChatGPT
    Shell -->|calls| SDXL
    Shell -->|calls| Dalle
    MoreModules -->|calls| Upscale
    MoreModules -->|calls| RemoveBG
    MoreModules -->|calls| VirusTotal
    MoreModules -->|calls| APIFLASH
    AFK -->|responds via| Handler
    Updater -->|responds via| Handler
    Shell -->|responds via| Handler
    MoreModules -->|responds via| Handler
    Handler -->|sends| PyroClient
    PyroClient -->|to network| TelegramAPI
    DeployEnv["Docker Container"]:::deploy
    Dockerfile --> DeployEnv
    Compose1 --> DeployEnv
    Compose2 --> DeployEnv
    DeployEnv -->|deployed to| RenderYAML
    DeployEnv -->|deployed to| Cloudfile
    DeployEnv -->|deployed to| Procfile
    DeployEnv -->|CI/CD| GHWorkflow1
    DeployEnv -->|CI/CD| GHWorkflow2
    GHAll -->|defines| GHWorkflow1
    GHAll -->|defines| GHWorkflow2
    DeployEnv -->|supports| Gitpod
    DeployEnv -->|build via| Nixpacks
    DeployEnv -->|uses| DevNix
    DeployEnv -->|includes| InstallSh
    DeployEnv -->|includes| InstallPy
    DeployEnv -->|includes| YumSh
    DeployEnv -->|includes| Termux
    DeployEnv -->|includes| CloudSh

    %% Click Events
    click EnvFile "https://github.com/the-moontg-project/moon-userbot/blob/main/.env.dist"
    click Config "https://github.com/the-moontg-project/moon-userbot/blob/main/utils/config.py"
    click EntryApp1 "https://github.com/the-moontg-project/moon-userbot/blob/main/app.py"
    click EntryApp2 "https://github.com/the-moontg-project/moon-userbot/blob/main/main.py"
    click Loader "https://github.com/the-moontg-project/moon-userbot/blob/main/modules/loader.py"
    click ModuleUtil "https://github.com/the-moontg-project/moon-userbot/blob/main/utils/module.py"
    click Handler "https://github.com/the-moontg-project/moon-userbot/blob/main/utils/handlers.py"
    click AFK "https://github.com/the-moontg-project/moon-userbot/blob/main/modules/afk.py"
    click Updater "https://github.com/the-moontg-project/moon-userbot/blob/main/modules/updater.py"
    click Shell "https://github.com/the-moontg-project/moon-userbot/blob/main/modules/shell.py"
    click DBUtil "https://github.com/the-moontg-project/moon-userbot/blob/main/utils/db.py"
    click Conv "https://github.com/the-moontg-project/moon-userbot/blob/main/utils/conv.py"
    click Misc "https://github.com/the-moontg-project/moon-userbot/blob/main/utils/misc.py"
    click Rentry "https://github.com/the-moontg-project/moon-userbot/blob/main/utils/rentry.py"
    click Scripts "https://github.com/the-moontg-project/moon-userbot/blob/main/utils/scripts.py"
    click Dockerfile "https://github.com/the-moontg-project/moon-userbot/tree/main/Dockerfile"
    click Compose1 "https://github.com/the-moontg-project/moon-userbot/blob/main/docker-compose.yml"
    click Compose2 "https://github.com/the-moontg-project/moon-userbot/blob/main/compose.yml"
    click RenderYAML "https://github.com/the-moontg-project/moon-userbot/blob/main/render.yaml"
    click Cloudfile "https://github.com/the-moontg-project/moon-userbot/tree/main/Cloudfile"
    click Procfile "https://github.com/the-moontg-project/moon-userbot/tree/main/Procfile"
    click GHWorkflow1 "https://github.com/the-moontg-project/moon-userbot/blob/main/.github/workflows/docker-image.yml"
    click GHWorkflow2 "https://github.com/the-moontg-project/moon-userbot/blob/main/.github/workflows/cloud-image.yml"
    click GHAll "https://github.com/the-moontg-project/moon-userbot/tree/main/.github/workflows/*"
    click Gitpod "https://github.com/the-moontg-project/moon-userbot/blob/main/.gitpod.yml"
    click Nixpacks "https://github.com/the-moontg-project/moon-userbot/blob/main/nixpacks.toml"
    click DevNix "https://github.com/the-moontg-project/moon-userbot/blob/main/.idx/dev.nix"
    click InstallSh "https://github.com/the-moontg-project/moon-userbot/blob/main/install.sh"
    click InstallPy "https://github.com/the-moontg-project/moon-userbot/blob/main/install.py"
    click YumSh "https://github.com/the-moontg-project/moon-userbot/blob/main/install_yum.sh"
    click Termux "https://github.com/the-moontg-project/moon-userbot/blob/main/termux-install.sh"
    click CloudSh "https://github.com/the-moontg-project/moon-userbot/blob/main/cloud.sh"

    %% Styles
    classDef codeComp fill:#D0E6FF,stroke:#036ACA,color:#000
    classDef db fill:#D5F5E3,stroke:#27AE60,color:#000
    classDef external fill:#FDEBD0,stroke:#E67E22,color:#000
    classDef deploy fill:#E5E7E9,stroke:#566573,color:#000
```
