# alberteinsteintg/adv-auto-filter-bot-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/alberteinsteintg/adv-auto-filter-bot-v2
- Repository: https://github.com/alberteinsteintg/adv-auto-filter-bot-v2

## Overview

##### Project Type and Purpose
- This is a specialized messaging “service” rather than a typical web app: a Python-based Telegram bot that automatically filters and searches files stored in MongoDB and returns message links as inline buttons.
- It leverages the Pyrogram library to listen for incoming Telegram updates, processes queries via a plugin architecture, and persists chat–channel connections and file metadata in a MongoDB database.

##### File-Structure Analysis
- Top-level:
- bot/ – the core application package
- bot/database/ – MongoDB adapter (database.py)
- bot/plugins/ – modular business logic for filters, callbacks, channel management, commands, settings
- bot/translation.py – user-facing text templates or multilingual support
- bot/user.py – user/session abstractions
- Procfile, runtime.txt, app.json – deployment configs (Heroku or other PaaS)
- requirements.txt – Python dependencies (pyrogram, pymongo)

a. External Systems
- Telegram API – delivers updates (messages, commands) and receives bot responses
- MongoDB Atlas (or self-hosted) – persistent storage of connected chat-channel mappings and file metadata
b. Bot Application Service (Python container)
- Update Receiver (Pyrogram Client)
- Core Dispatcher – routes each incoming update to the appropriate plugin
- Plugins –
– auto_filter.py: listens for plain-text queries, performs DB searches
– commands.py: handles /add, /del, /delall, /settings commands
– callback.py: processes inline-button callbacks from settings panels or search results
– channel.py, settings.py: channel-connection management and configuration toggles
- Database Layer (bot/database/database.py) – CRUD operations on chat/channel collections
- Translation Layer (bot/translation.py) – static or dynamic text generation for replies and buttons
- User Model (bot/user.py) – encapsulates user or chat metadata, permission checks
c. Deployment Environment
- Heroku or VPS – container or VM running Procfile (`worker: python3 -m bot`)
- Environment Variables – BOT_TOKEN, API_ID, API_HASH, MONGO_URL, SESSION_STRING

##### Interactions & Data Flow
1. A user sends a message or command → Telegram API → Bot’s Pyrogram client
2. Dispatcher inspects update:
- If command → plugin commands.py → may update DB via database.py → acknowledges with inline keyboard
- If text query → auto_filter.py → queries MongoDB → builds result buttons via translation layer → sends response
- If callback query → callback.py → modifies settings or paginates results → edits message or sends new keyboard
3. All DB reads/writes flow through the database adapter to MongoDB.

##### Key Architectural Patterns & Principles
- Modular “Plugin” pattern: each bot capability in its own Python module, making it easy to extend or disable features.
- Separation of Concerns:
- Pyrogram client (network/update handling)
- Core Dispatcher (routing)
- Business logic (plugins)
- Persistence (database adapter)
- Presentation/text (translation layer)
- Configuration via environment variables and a settings panel bot command – no code changes required at runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        Telegram["Telegram API"]:::external
        MongoDB["MongoDB"]:::db
    end

    %% Bot Service Container
    subgraph "Bot Service"
        direction TB
        UR["Update Receiver\n(Pyrogram Client)"]:::core
        Dispatcher["Core Dispatcher"]:::core

        subgraph "Plugins"
            AF["Auto-Filter Plugin"]:::plugin
            CMD["Commands Plugin"]:::plugin
            CB["Callback Plugin"]:::plugin
            CH["Channel Management Plugin"]:::plugin
            SET["Settings Plugin"]:::plugin
        end

        DBLayer["Database Layer"]:::db
        Trans["Translation Layer"]:::core
        UserModel["User Model"]:::core
    end

    %% Deployment Environment
    subgraph "Deployment"
        Heroku["Heroku/VPS"]:::deploy
        Env["Environment Variables"]:::deploy
        PFile["Procfile"]:::config
        runTxt["runtime.txt"]:::config
        appJson["app.json"]:::config
        reqs["requirements.txt"]:::config
    end

    %% Data Flows
    Telegram -->|get_updates| UR
    UR -->|forward_update| Dispatcher

    Dispatcher -->|command_update| CMD
    Dispatcher -->|text_query| AF
    Dispatcher -->|callback_query| CB
    Dispatcher -->|channel_event| CH
    Dispatcher -->|settings_event| SET

    AF -->|query_files| DBLayer
    CMD -->|db_ops| DBLayer
    CB -->|db_ops| DBLayer
    CH -->|db_ops| DBLayer
    SET -->|db_ops| DBLayer

    DBLayer -->|read/write| MongoDB

    AF -->|generate_text| Trans
    CMD -->|generate_text| Trans
    CB -->|generate_text| Trans
    CH -->|generate_text| Trans
    SET -->|generate_text| Trans

    AF -->|send_message| Telegram
    CMD -->|send_message| Telegram
    CB -->|send_message| Telegram

    Env -->|config| UR
    Env -->|config| Dispatcher
    Env -->|config| DBLayer

    Heroku -->|runs worker| UR

    %% Click Events
    click UR "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/bot/bot.py"
    click UR "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/bot/__main__.py"
    click Dispatcher "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/bot/bot.py"
    click AF "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/bot/plugins/auto_filter.py"
    click CMD "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/bot/plugins/commands.py"
    click CB "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/bot/plugins/callback.py"
    click CH "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/bot/plugins/channel.py"
    click SET "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/bot/plugins/settings.py"
    click DBLayer "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/bot/database/database.py"
    click Trans "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/bot/translation.py"
    click UserModel "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/bot/user.py"
    click PFile "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/tree/main/Procfile"
    click runTxt "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/runtime.txt"
    click appJson "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/app.json"
    click reqs "https://github.com/alberteinsteintg/adv-auto-filter-bot-v2/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#add8e6,stroke:#000
    classDef db fill:#ffa500,stroke:#000
    classDef core fill:#98fb98,stroke:#000
    classDef plugin fill:#90ee90,stroke:#000
    classDef deploy fill:#d8bfd8,stroke:#000
    classDef config fill:#d3d3d3,stroke:#000
```
