# erfjab/holderbot architecture

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

- Interactive diagram: https://gitdiagram.com/erfjab/holderbot
- Repository: https://github.com/erfjab/holderbot

## Overview

##### Project Type & Purpose
- This is a Python-based Telegram bot designed to manage multiple VPN panels (e.g., Marzban, Marzneshin, and planned integrations with others). It helps manage users and admins on different VPN servers using bulk creation, user modifications, and node monitoring.
- The README clearly spells out multi-panel support and various user/admin management features, while the file structure reinforces that through dedicated modules for API clients, types, routers, database models, and system settings.

##### Analyzing the File Structure
- The top-level “app” directory holds most of the application logic.
- The “app/api” directory contains modules to interact with different VPN panels: subdirectories for clients and types (with further subdivisions for each panel).
- The “app/db” directory contains the database models, CRUD operations, and alembic migration scripts – indicating that the system uses a relational database with migrations.
- The “app/routers” directory holds routers for various Telegram commands (actions, servers, users, templates, etc.), which means the Telegram bot architecture is organized around multiple endpoints handling specific commands.
- The “app/settings” directory provides configuration, log, middleware, task scheduling, translation (language), tracking, and utility functions.
- Other parts include “app/keys” for managing enums, callbacks, and key-related operations (often used in Telegram bots for inline buttons or callback query handling).
- Additional files like Dockerfile, docker-compose.yml, and related workflows in the .github directory indicate containerization and CI/CD support.

##### Key Components
a. Telegram Bot Interface:
- Main entry point (main.py, app/bot.py, app/holderbot.py) that receives commands from Telegram.
- This component will interact with Telegram’s API and handle user inputs.
b. API Logic Layer:
- API Clients and Types (under app/api/clients and app/api/types) that abstract the interactions with various VPN panels (e.g., Marzban, Marzneshin).
- The “app/api/core” component which likely encapsulates core request handling and common functionality.
c. Routers & Command Handlers:
- Routers (in app/routers) are dedicated to different functionalities such as user management, server operations, actions, and stats. They determine how the bot processes commands and routes them to the proper API or business logic.
d. Database Layer:
- Models and CRUD operations in “app/db/models.py” and “app/db/crud.py”.
- Alembic migrations (stored in “app/db/alembic”), which manage schema changes.
e. Settings & Middleware:
- Configuration files from “app/settings”, including environment variables, log settings, language, tasks, and middleware. These pieces orchestrate the app’s configurations, security, and even scheduling (tasker).

##### Relationships and Interactions
- The Telegram Bot Interface receives a command/message and forwards the request to the appropriate Router.
- Routers then process the command:
- They may interact with API Core functions which in turn call one of the API Clients for the targeted VPN panel.
- Database operations (via the CRUD and model modules) persist or retrieve state changes (e.g., user creation or modifications).
- Settings and Middlewares validate sessions, handle logging, or trigger asynchronous tasks (found in the tasks subdirectories).
- External dependencies:
- Communication with Telegram servers.
- Communication with external VPN panels through the API client modules.
- The Docker & compose files indicate that these components run within containers, so you might also show the overall container orchestration as an outer boundary.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Each module (API, routers, models, settings, keys) is kept modular.
- Layered Architecture: Clear delineation between presentation (Telegram Bot interface), business logic (routers and API clients), and data (database operations).
- Extensibility: The design supports adding new VPN panels (as hinted by planned support for “Alireza”, “Hiddify”, “3x-ui”) through a modular API clients/types pattern.
- CI/CD & Containerization: The presence of Docker configurations and GitHub workflows shows modern deployment practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Container"
        EX1["Telegram API"]:::external
        TB["Telegram Bot Interface"]:::frontend
        R["Routers & Command Handlers"]:::frontend
        AC["API Core"]:::business
        AP["API Clients"]:::business
        ATM["API Types - Marzban"]:::business
        ATS["API Types - Marzneshin"]:::business
        DBM["Database Models/CRUD"]:::database
        DBA["Alembic Migrations"]:::database
        SM["Settings & Middleware"]:::config
        KC["Keys & Callbacks Management"]:::keys
        VP["VPN Panels"]:::external

        EX1 -->|"command"| TB
        TB -->|"routes"| R
        R -->|"processes"| AC
        AC -->|"invokes"| AP
        AP -->|"uses"| ATM
        AP -->|"uses"| ATS
        AP -->|"calls"| VP
        R -->|"DB_operations"| DBM
        DBM -->|"migrates"| DBA
        R -->|"uses"| SM
        R -->|"uses"| KC
        SM -->|"configures"| AC
        SM -->|"manages"| DBM
        TB -->|"communicates"| EX1
    end

    click TB "https://github.com/erfjab/holderbot/blob/master/main.py"
    click TB "https://github.com/erfjab/holderbot/blob/master/app/bot.py"
    click TB "https://github.com/erfjab/holderbot/blob/master/app/holderbot.py"
    click AC "https://github.com/erfjab/holderbot/blob/master/app/api/core/_request.py"
    click AP "https://github.com/erfjab/holderbot/tree/master/app/api/clients"
    click AP "https://github.com/erfjab/holderbot/blob/master/app/api/clients/marzban.py"
    click AP "https://github.com/erfjab/holderbot/blob/master/app/api/clients/marzneshin.py"
    click ATM "https://github.com/erfjab/holderbot/tree/master/app/api/types/marzban"
    click ATS "https://github.com/erfjab/holderbot/tree/master/app/api/types/marzneshin"
    click R "https://github.com/erfjab/holderbot/tree/master/app/routers"
    click DBM "https://github.com/erfjab/holderbot/tree/master/app/db"
    click DBA "https://github.com/erfjab/holderbot/tree/master/app/db/alembic"
    click SM "https://github.com/erfjab/holderbot/tree/master/app/settings"
    click KC "https://github.com/erfjab/holderbot/tree/master/app/keys"

    classDef external fill:#f96,stroke:#333,stroke-width:2px;
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef business fill:#afa,stroke:#333,stroke-width:2px;
    classDef database fill:#cfc,stroke:#333,stroke-width:2px;
    classDef config fill:#fcc,stroke:#333,stroke-width:2px;
    classDef keys fill:#fcf,stroke:#333,stroke-width:2px;
```
