# evansvl/vless-shopbot architecture

> Architecture diagram of the GitHub repository evansvl/vless-shopbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evansvl/vless-shopbot
- Repository: https://github.com/evansvl/vless-shopbot

## Overview

VLESS Shop Bot automates VPN-key sales through Telegram, with an admin web panel for configuration and management. The main workflow is customer interaction, plan selection and payment, then key provisioning through 3x-ui; scheduled jobs synchronize keys and notify users about expiry. The graph also includes support tickets and the panel’s management role. Relationships are based on shown imports and calls or README claims; unsampled implementation details are represented only where the README documents the capability.

Main entry points: [`src/shop_bot/bot/handlers.py`](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot/handlers.py) (Shop bot handlers), [`src/shop_bot/webhook_server/app.py`](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/webhook_server/app.py) (Web panel and webhooks), [`src/shop_bot/data_manager/database.py`](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/data_manager/database.py) (Application database), [`src/shop_bot/bot_controller.py`](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot_controller.py) (Bot controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_entry["Application entry<br/>[__main__.py]"]
  node_controller["Bot controller<br/>[bot_controller.py]"]
end

subgraph group_telegram["Telegram experience"]
  node_handlers["Shop bot handlers<br/>[handlers.py]"]
  node_keyboards["Bot keyboards<br/>[keyboards.py]"]
  node_middleware["Ban middleware<br/>[middlewares.py]"]
  node_support["Support bot"]
  node_config["Bot configuration text<br/>[config.py]"]
end

subgraph group_web["Web administration"]
  node_webapp["Web panel and webhooks<br/>[app.py]"]
end

subgraph group_domain["Sales and VPN operations"]
  node_database[("Application database<br/>[database.py]")]
  node_scheduler["Key scheduler<br/>[scheduler.py]"]
  node_xui["3x-ui integration<br/>[xui_api.py]"]
end

node_customer(("VPN customer"))
node_admin(("Administrator"))
node_telegram(("Telegram platform"))
node_xui_service{{"3x-ui panels"}}
node_payments{{"Payment providers"}}

node_entry -->|"initializes"| node_database
node_entry -->|"creates"| node_controller
node_entry -->|"starts"| node_webapp
node_entry -->|"runs"| node_scheduler
node_controller -->|"registers"| node_handlers
node_controller -->|"installs"| node_middleware
node_controller -->|"registers"| node_support
node_handlers -->|"reads and writes"| node_database
node_handlers -->|"uses"| node_keyboards
node_handlers -->|"provisions keys"| node_xui
node_handlers -->|"formats messages"| node_config
node_keyboards -->|"reads settings"| node_database
node_middleware -->|"checks bans"| node_database
node_support -->|"stores ticket links"| node_database
node_scheduler -->|"syncs key records"| node_database
node_scheduler -->|"checks panels"| node_xui
node_webapp -->|"manages records"| node_database
node_webapp -.->|"starts and stops"| node_controller
node_webapp -->|"revokes keys"| node_xui
node_webapp -->|"dispatches payment"| node_handlers
node_customer -->|"uses"| node_telegram
node_telegram -->|"delivers updates"| node_handlers
node_handlers -->|"sends keys"| node_customer
node_admin -->|"manages service"| node_webapp
node_webapp -->|"receives webhooks"| node_payments
node_handlers -.->|"accepts payments"| node_payments
node_xui -->|"manages clients"| node_xui_service

click node_entry "https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/__main__.py"
click node_controller "https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot_controller.py"
click node_webapp "https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/webhook_server/app.py"
click node_handlers "https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot/handlers.py"
click node_keyboards "https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot/keyboards.py"
click node_middleware "https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot/middlewares.py"
click node_support "https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot/support_handlers.py"
click node_database "https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/data_manager/database.py"
click node_scheduler "https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/data_manager/scheduler.py"
click node_xui "https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/modules/xui_api.py"
click node_config "https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_controller,node_xui_service toneBlue
class node_handlers,node_keyboards,node_middleware,node_support,node_config toneAmber
class node_webapp toneMint
class node_database,node_scheduler,node_xui toneRose
class node_customer,node_admin,node_telegram,node_payments toneIndigo
```

## Components

### Application runtime

- [Application entry](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/__main__.py): `src/shop_bot/__main__.py`
- [Bot controller](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot_controller.py): `src/shop_bot/bot_controller.py`

### Telegram experience

- [Shop bot handlers](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot/handlers.py): `src/shop_bot/bot/handlers.py`
- [Bot keyboards](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot/keyboards.py): `src/shop_bot/bot/keyboards.py`
- [Ban middleware](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot/middlewares.py): `src/shop_bot/bot/middlewares.py`
- [Support bot](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/bot/support_handlers.py): `src/shop_bot/bot/support_handlers.py`
- [Bot configuration text](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/config.py): `src/shop_bot/config.py`

### Web administration

- [Web panel and webhooks](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/webhook_server/app.py): `src/shop_bot/webhook_server/app.py`

### Sales and VPN operations

- [Application database](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/data_manager/database.py): `src/shop_bot/data_manager/database.py`
- [Key scheduler](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/data_manager/scheduler.py): `src/shop_bot/data_manager/scheduler.py`
- [3x-ui integration](https://github.com/evansvl/vless-shopbot/blob/main/src/shop_bot/modules/xui_api.py): `src/shop_bot/modules/xui_api.py`

### Other components

- **VPN customer**
- **Administrator**
- **Telegram platform**
- **3x-ui panels**
- **Payment providers**

## Connections

- Application entry → Application database: initializes (evidence: `src/shop_bot/__main__.py`)
- Application entry → Bot controller: creates (evidence: `src/shop_bot/__main__.py`)
- Application entry → Web panel and webhooks: starts (evidence: `src/shop_bot/__main__.py`)
- Application entry → Key scheduler: runs (evidence: `src/shop_bot/__main__.py`)
- Bot controller → Shop bot handlers: registers (evidence: `src/shop_bot/bot_controller.py`)
- Bot controller → Ban middleware: installs (evidence: `src/shop_bot/bot_controller.py`)
- Bot controller → Support bot: registers (evidence: `src/shop_bot/bot_controller.py`)
- Shop bot handlers → Application database: reads and writes (evidence: `src/shop_bot/bot/handlers.py`)
- Shop bot handlers → Bot keyboards: uses (evidence: `src/shop_bot/bot/handlers.py`)
- Shop bot handlers → 3x-ui integration: provisions keys (evidence: `src/shop_bot/bot/handlers.py`)
- Shop bot handlers → Bot configuration text: formats messages (evidence: `src/shop_bot/bot/handlers.py`)
- Bot keyboards → Application database: reads settings (evidence: `src/shop_bot/bot/keyboards.py`)
- Ban middleware → Application database: checks bans (evidence: `src/shop_bot/bot/middlewares.py`)
- Support bot → Application database: stores ticket links (evidence: `src/shop_bot/bot/support_handlers.py`)
- Key scheduler → Application database: syncs key records (evidence: `src/shop_bot/data_manager/scheduler.py`)
- Key scheduler → 3x-ui integration: checks panels (evidence: `src/shop_bot/data_manager/scheduler.py`)
- Web panel and webhooks → Application database: manages records (evidence: `src/shop_bot/webhook_server/app.py`)
- Web panel and webhooks → Bot controller: starts and stops
- Web panel and webhooks → 3x-ui integration: revokes keys (evidence: `src/shop_bot/webhook_server/app.py`)
- Web panel and webhooks → Shop bot handlers: dispatches payment (evidence: `src/shop_bot/webhook_server/app.py`)
- VPN customer → Telegram platform: uses (evidence: `README.md`)
- Telegram platform → Shop bot handlers: delivers updates (evidence: `README.md`)
- Shop bot handlers → VPN customer: sends keys (evidence: `README.md`)
- Administrator → Web panel and webhooks: manages service (evidence: `README.md`)
- Web panel and webhooks → Payment providers: receives webhooks (evidence: `README.md`)
- Shop bot handlers → Payment providers: accepts payments (evidence: `README.md`)
- 3x-ui integration → 3x-ui panels: manages clients (evidence: `README.md`)
