# veercli/veerv2 architecture

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

- Interactive diagram: https://gitdiagram.com/veercli/veerv2
- Repository: https://github.com/veercli/veerv2

## Overview

##### Project type and purpose
- This is a Telegram bot project written in Python.
- Its primary purpose is to handle incoming updates (commands, callbacks, inline queries, messages) and respond according to modular handler code.
- It relies on the Telegram Bot API, with optional forced-subscription to a channel.

##### File structure
- Top-level:
– bot.py: the main entry point that initializes the bot, registers handlers, and starts polling.
– setup.py, install.txt: installation and startup scripts.
- Directories:
– handlers/: each file is a handler module (all.py, callback.py, delete.py, edit.py, gpcmd.py, inline.py, locks.py, msg.py, nf.py, ranks.py, sudo.py).
– utlis/ (utils/typo): helper functions for locks, rank management, sending messages (send.py), and Telegram API wrappers (tg.py).
– lang/: language definitions and reply templates (arcmd.py, arreply.py).
- No external database code—state is managed in memory or simple lock files (locks.py).

##### Key points from README
- Guides install on Ubuntu 18 VPS; collects BOT_TOKEN, DEV_ID, CHANNEL_ID interactively.
- Requires granting the bot admin in a channel for forced subscription.
- Uses Python 3.8 and polling (no webhook specified).

##### Main components
a. Telegram API (cloud service)
b. Bot Process (your Python runtime)
– bot.py (core orchestrator)
– handlers/* (message-handling modules)
– utlis/* (utility library)
– lang/* (localization and reply templates)
c. Administrator (DEV_ID) – privileged user for owner commands
d. Channel (CHANNEL_ID) – for forced subscription
e. (Optional) Storage/Lock Files – for persistence of “locks” and “ranks” if implemented

##### Relationships and data flows
1. Telegram API sends an Update → Bot Process
2. bot.py inspects the Update and dispatches to the appropriate handler module
– e.g. a new message to handlers/msg.py, inline query to handlers/inline.py
3. Handler code may call utlis/send.py or utlis/tg.py to send messages back via the Telegram API
4. Handlers for locks or ranks consult utlis/locks.py or utlis/rank.py (and any backing storage)
6. For forced subscription, handler logic calls Telegram API to check user membership in CHANNEL_ID

##### Architectural patterns and design principles
- Modular handler registration – each concern in its own file
- Separation of concerns:
– Communication layer (tg.py)
– Business logic (handlers/)
– Utilities (locks, ranks, send wrappers)
– Localization (lang/)
- Single-process event loop (polling-based)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    TelegramAPI["Telegram API"]:::external
    Channel["Channel (CHANNEL_ID)"]:::external
    Administrator["Administrator (DEV_ID)"]:::external
    Config["Config Inputs\n(BOT_TOKEN, DEV_ID, CHANNEL_ID)"]:::external

    %% Bot Process Boundary
    subgraph "Bot Process" 
        direction TB
        BotPy["bot.py"]:::core
        subgraph "Handlers" 
            direction TB
            All["handlers/all.py"]:::core
            Callback["handlers/callback.py"]:::core
            Delete["handlers/delete.py"]:::core
            Edit["handlers/edit.py"]:::core
            GpCmd["handlers/gpcmd.py"]:::core
            Inline["handlers/inline.py"]:::core
            LocksH["handlers/locks.py"]:::core
            Msg["handlers/msg.py"]:::core
            Nf["handlers/nf.py"]:::core
            RanksH["handlers/ranks.py"]:::core
            Sudo["handlers/sudo.py"]:::core
        end
        subgraph "Utilities" 
            direction TB
            LocksU["utlis/locks.py"]:::util
            RankU["utlis/rank.py"]:::util
            SendU["utlis/send.py"]:::util
            TgU["utlis/tg.py"]:::util
        end
        subgraph "Localization" 
            direction TB
            ArCmd["lang/arcmd.py"]:::core
            ArReply["lang/arreply.py"]:::core
        end
        Storage[(Lock/Rank Storage)]:::storage
    end

    %% Data Flows
    TelegramAPI -->|"updates via polling"| BotPy
    BotPy -->|"dispatch to handlers"| All
    BotPy -->|"dispatch to handlers"| Callback
    BotPy -->|"dispatch to handlers"| Delete
    BotPy -->|"dispatch to handlers"| Edit
    BotPy -->|"dispatch to handlers"| GpCmd
    BotPy -->|"dispatch to handlers"| Inline
    BotPy -->|"dispatch to handlers"| LocksH
    BotPy -->|"dispatch to handlers"| Msg
    BotPy -->|"dispatch to handlers"| Nf
    BotPy -->|"dispatch to handlers"| RanksH
    BotPy -->|"dispatch to handlers"| Sudo

    All -->|uses| SendU
    Callback -->|uses| TgU
    Delete -->|uses| LocksU
    Edit -->|uses| SendU
    GpCmd -->|uses| RankU
    Inline -->|uses| TgU
    LocksH -->|reads/writes| LocksU
    RanksH -->|reads/writes| RankU
    Sudo -->|uses| TgU
    SendU -->|"API calls"| TelegramAPI
    TgU -->|"API calls"| TelegramAPI
    LocksU -->|persist| Storage
    RankU -->|persist| Storage

    BotPy -->|checks membership| Channel
    Channel -->|membership info| BotPy
    Administrator -->|owner commands| BotPy
    Config -->|startup params| BotPy

    %% Click Events
    click BotPy "https://github.com/veercli/veerv2/blob/main/bot.py"
    click All "https://github.com/veercli/veerv2/blob/main/handlers/all.py"
    click Callback "https://github.com/veercli/veerv2/blob/main/handlers/callback.py"
    click Delete "https://github.com/veercli/veerv2/blob/main/handlers/delete.py"
    click Edit "https://github.com/veercli/veerv2/blob/main/handlers/edit.py"
    click GpCmd "https://github.com/veercli/veerv2/blob/main/handlers/gpcmd.py"
    click Inline "https://github.com/veercli/veerv2/blob/main/handlers/inline.py"
    click LocksH "https://github.com/veercli/veerv2/blob/main/handlers/locks.py"
    click Msg "https://github.com/veercli/veerv2/blob/main/handlers/msg.py"
    click Nf "https://github.com/veercli/veerv2/blob/main/handlers/nf.py"
    click RanksH "https://github.com/veercli/veerv2/blob/main/handlers/ranks.py"
    click Sudo "https://github.com/veercli/veerv2/blob/main/handlers/sudo.py"
    click LocksU "https://github.com/veercli/veerv2/blob/main/utlis/locks.py"
    click RankU "https://github.com/veercli/veerv2/blob/main/utlis/rank.py"
    click SendU "https://github.com/veercli/veerv2/blob/main/utlis/send.py"
    click TgU "https://github.com/veercli/veerv2/blob/main/utlis/tg.py"
    click ArCmd "https://github.com/veercli/veerv2/blob/main/lang/arcmd.py"
    click ArReply "https://github.com/veercli/veerv2/blob/main/lang/arreply.py"
    click Setup "https://github.com/veercli/veerv2/blob/main/setup.py"
    click Install "https://github.com/veercli/veerv2/blob/main/install.txt"

    %% Styles
    classDef external fill:#e0ffe0,stroke:#2d7a2d,color:#000
    classDef core fill:#cce5ff,stroke:#2166a5,color:#000
    classDef util fill:#fff3cd,stroke:#a67c00,color:#000
    classDef storage fill:#fff3cd,stroke:#a67c00,color:#000
```
