# dkanil/vpn_bot architecture

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

- Interactive diagram: https://gitdiagram.com/dkanil/vpn_bot
- Repository: https://github.com/dkanil/vpn_bot

## Overview

This repository implements a Telegram bot for managing VPN clients in a 3x-ui panel. Users request access, await admin approval, and can then obtain a subscription link; administrators manage approvals and payment actions. The bot also synchronizes panel client data, checks payment periods in the background, and supports broadcasts and database export. The graph follows documented capabilities, but several handler details were not sampled, so those links rely on the README rather than inspected handler code.

Main entry points: [`main.py`](https://github.com/dkanil/vpn_bot/blob/master/main.py) (Bot runtime), [`db.py`](https://github.com/dkanil/vpn_bot/blob/master/db.py) (User records), [`auth.py`](https://github.com/dkanil/vpn_bot/blob/master/auth.py) (3x-ui API access), [`filter.py`](https://github.com/dkanil/vpn_bot/blob/master/filter.py) (User filtering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Telegram workflows"]
  node_bot_runtime["Bot runtime<br/>[main.py]"]
  node_access_approval["Access approval<br/>[main.py]"]
  node_user_guidance["Setup guidance<br/>[main.py]"]
  node_messaging["Broadcasts<br/>[main.py]"]
end

subgraph group_vpn["VPN client management"]
  node_client_link["Subscription link<br/>[main.py]"]
  node_client_provision["Client provisioning<br/>[main.py]"]
  node_panel_api["3x-ui API access<br/>[auth.py]"]
end

subgraph group_payments["Payment operations"]
  node_panel_sync["Client synchronization<br/>[main.py]"]
  node_payment_check["Payment monitoring<br/>[main.py]"]
  node_payment_actions["Payment actions<br/>[main.py]"]
end

subgraph group_support["Shared services"]
  node_database_export["Database export<br/>[main.py]"]
  node_sqlite[("User records<br/>[db.py]")]
  node_access_filter["User filtering<br/>[filter.py]"]
  node_configuration["Bot configuration<br/>[config.py]"]
  node_messages["Message templates<br/>[messages.yaml]"]
end

node_user(("VPN user"))
node_admin(("Administrator"))
node_panel["3x-ui panel"]

node_user -->|"sends commands"| node_bot_runtime
node_admin -->|"sends commands"| node_bot_runtime
node_bot_runtime -->|"routes requests"| node_access_approval
node_access_approval -->|"requests approval"| node_admin
node_user -->|"requests help"| node_user_guidance
node_bot_runtime -->|"routes request"| node_client_link
node_client_link -->|"gets credentials"| node_client_provision
node_client_provision -->|"requests client operations"| node_panel_api
node_panel_api -->|"calls panel API"| node_panel
node_bot_runtime -->|"runs synchronization"| node_panel_sync
node_panel_sync -->|"requests client list"| node_panel_api
node_panel_sync -->|"updates client records"| node_sqlite
node_bot_runtime -->|"starts background check"| node_payment_check
node_payment_check -->|"refreshes client data"| node_panel_sync
node_payment_check -->|"reads payment records"| node_sqlite
node_payment_check -->|"sends reminders"| node_admin
node_user -->|"requests renewal"| node_payment_actions
node_admin -->|"manages payments"| node_payment_actions
node_payment_actions -->|"updates payment records"| node_sqlite
node_admin -->|"starts broadcast"| node_messaging
node_admin -->|"requests database"| node_database_export
node_bot_runtime -->|"installs middleware"| node_access_filter
node_access_filter -->|"checks user status"| node_sqlite
node_bot_runtime -->|"uses settings"| node_configuration
node_configuration -->|"loads templates"| node_messages

click node_bot_runtime "https://github.com/dkanil/vpn_bot/blob/master/main.py"
click node_access_approval "https://github.com/dkanil/vpn_bot/blob/master/main.py"
click node_user_guidance "https://github.com/dkanil/vpn_bot/blob/master/main.py"
click node_client_link "https://github.com/dkanil/vpn_bot/blob/master/main.py"
click node_client_provision "https://github.com/dkanil/vpn_bot/blob/master/main.py"
click node_panel_api "https://github.com/dkanil/vpn_bot/blob/master/auth.py"
click node_panel_sync "https://github.com/dkanil/vpn_bot/blob/master/main.py"
click node_payment_check "https://github.com/dkanil/vpn_bot/blob/master/main.py"
click node_payment_actions "https://github.com/dkanil/vpn_bot/blob/master/main.py"
click node_messaging "https://github.com/dkanil/vpn_bot/blob/master/main.py"
click node_database_export "https://github.com/dkanil/vpn_bot/blob/master/main.py"
click node_sqlite "https://github.com/dkanil/vpn_bot/blob/master/db.py"
click node_access_filter "https://github.com/dkanil/vpn_bot/blob/master/filter.py"
click node_configuration "https://github.com/dkanil/vpn_bot/blob/master/config.py"
click node_messages "https://github.com/dkanil/vpn_bot/blob/master/messages.yaml"

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_bot_runtime,node_access_approval,node_user_guidance,node_messaging,node_user,node_panel toneBlue
class node_client_link,node_client_provision,node_panel_api toneAmber
class node_panel_sync,node_payment_check,node_payment_actions toneMint
class node_database_export,node_sqlite,node_access_filter,node_configuration,node_messages toneRose
class node_admin toneIndigo
```

## Components

### Telegram workflows

- [Bot runtime](https://github.com/dkanil/vpn_bot/blob/master/main.py): `main.py`
- [Access approval](https://github.com/dkanil/vpn_bot/blob/master/main.py): `main.py`
- [Setup guidance](https://github.com/dkanil/vpn_bot/blob/master/main.py): `main.py`
- [Broadcasts](https://github.com/dkanil/vpn_bot/blob/master/main.py): `main.py`

### VPN client management

- [Subscription link](https://github.com/dkanil/vpn_bot/blob/master/main.py): `main.py`
- [Client provisioning](https://github.com/dkanil/vpn_bot/blob/master/main.py): `main.py`
- [3x-ui API access](https://github.com/dkanil/vpn_bot/blob/master/auth.py): `auth.py`

### Payment operations

- [Client synchronization](https://github.com/dkanil/vpn_bot/blob/master/main.py): `main.py`
- [Payment monitoring](https://github.com/dkanil/vpn_bot/blob/master/main.py): `main.py`
- [Payment actions](https://github.com/dkanil/vpn_bot/blob/master/main.py): `main.py`

### Shared services

- [Database export](https://github.com/dkanil/vpn_bot/blob/master/main.py): `main.py`
- [User records](https://github.com/dkanil/vpn_bot/blob/master/db.py): `db.py`
- [User filtering](https://github.com/dkanil/vpn_bot/blob/master/filter.py): `filter.py`
- [Bot configuration](https://github.com/dkanil/vpn_bot/blob/master/config.py): `config.py`
- [Message templates](https://github.com/dkanil/vpn_bot/blob/master/messages.yaml): `messages.yaml`

### Other components

- **VPN user**
- **Administrator**
- **3x-ui panel**

## Connections

- VPN user → Bot runtime: sends commands (evidence: `README.md`)
- Administrator → Bot runtime: sends commands (evidence: `README.md`)
- Bot runtime → Access approval: routes requests (evidence: `README.md`)
- Access approval → Administrator: requests approval (evidence: `README.md`)
- VPN user → Setup guidance: requests help (evidence: `README.md`)
- Bot runtime → Subscription link: routes request (evidence: `README.md`)
- Subscription link → Client provisioning: gets credentials (evidence: `main.py`)
- Client provisioning → 3x-ui API access: requests client operations (evidence: `main.py`)
- 3x-ui API access → 3x-ui panel: calls panel API (evidence: `README.md`)
- Bot runtime → Client synchronization: runs synchronization (evidence: `main.py`)
- Client synchronization → 3x-ui API access: requests client list (evidence: `main.py`)
- Client synchronization → User records: updates client records (evidence: `main.py`)
- Bot runtime → Payment monitoring: starts background check (evidence: `main.py`)
- Payment monitoring → Client synchronization: refreshes client data (evidence: `main.py`)
- Payment monitoring → User records: reads payment records (evidence: `main.py`)
- Payment monitoring → Administrator: sends reminders (evidence: `README.md`)
- VPN user → Payment actions: requests renewal (evidence: `README.md`)
- Administrator → Payment actions: manages payments (evidence: `README.md`)
- Payment actions → User records: updates payment records (evidence: `README.md`)
- Administrator → Broadcasts: starts broadcast (evidence: `README.md`)
- Administrator → Database export: requests database (evidence: `README.md`)
- Bot runtime → User filtering: installs middleware (evidence: `main.py`)
- User filtering → User records: checks user status (evidence: `filter.py`)
- Bot runtime → Bot configuration: uses settings (evidence: `main.py`)
- Bot configuration → Message templates: loads templates (evidence: `config.py`)
