# jatixs/tgbotvpscp architecture

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

- Interactive diagram: https://gitdiagram.com/jatixs/tgbotvpscp
- Repository: https://github.com/jatixs/tgbotvpscp

## Overview

VPS Manager is a Telegram- and web-operated control plane for a master server and remote VPS nodes. Administrators configure nodes, then inspect live status and use Telegram or the dashboard to manage infrastructure; the node agent reports to the master. The graph also preserves documented service, backup/update, alerting, security, and VPN-management capabilities. Several feature modules are listed in the repository but were not excerpted, so their internal call paths are not inferred; dashed edges mark documented but unverified connections.

Main entry points: [`bot.py`](https://github.com/jatixs/tgbotvpscp/blob/main/bot.py) (Telegram bot), [`core/web/app.py`](https://github.com/jatixs/tgbotvpscp/blob/main/core/web/app.py) (Web app), [`core/web/api_nodes.py`](https://github.com/jatixs/tgbotvpscp/blob/main/core/web/api_nodes.py) (Node API), [`core/web/streaming.py`](https://github.com/jatixs/tgbotvpscp/blob/main/core/web/streaming.py) (Live streams)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_telegrambot["Telegram bot<br/>[bot.py]"]
  node_webapp["Web app<br/>[app.py]"]
  node_webviews["Dashboard views<br/>[views.py]"]
  node_webassets["Dashboard client<br/>[dashboard.js]"]
end

subgraph group_control["Control plane"]
  node_webapi["Node API<br/>[api_nodes.py]"]
  node_streaming["Live streams<br/>[streaming.py]"]
  node_background["Background tasks<br/>[tasks.py]"]
end

subgraph group_nodeops["Node operations"]
  node_nodes["Node management<br/>[nodes.py]"]
  node_services["Service manager<br/>[services.py]"]
  node_traffic["Traffic monitor<br/>[traffic.py]"]
end

subgraph group_features["Operations features"]
  node_backup["Backup manager<br/>[backups.py]"]
  node_update["Updates<br/>[update.py]"]
  node_alerts["Alerts and notifications<br/>[client_alerts.py]"]
  node_vpn["VLESS / Xray<br/>[vless.py]"]
end

subgraph group_state["State and security"]
  node_auth["Web authentication<br/>[auth.py]"]
  node_rbac["Access control<br/>[rbac.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_nodedb[("Node database<br/>[nodes_db.py]")]
  node_models["Database models<br/>[models.py]"]
  node_shared["Shared runtime state<br/>[shared_state.py]"]
end

node_admin(("Administrator"))
node_telegram(("Telegram"))
node_webuser(("Web user"))
node_agent["Remote node agent<br/>[node.py]"]

node_admin -->|"uses"| node_telegram
node_telegram -.->|"sends commands"| node_telegrambot
node_admin -.->|"uses"| node_webapp
node_webuser -.->|"opens dashboard"| node_webapp
node_telegrambot -->|"starts"| node_webapp
node_webapp -->|"registers routes"| node_webviews
node_webapp -->|"registers routes"| node_webapi
node_webapp -->|"registers routes"| node_streaming
node_webapp -->|"starts tasks"| node_background
node_webviews -.->|"serves dashboard"| node_webassets
node_webassets -.->|"requests node data"| node_webapi
node_webassets -.->|"receives SSE"| node_streaming
node_agent -.->|"reports node data"| node_webapi
node_webapi -->|"uses node records"| node_nodedb
node_webapi -->|"uses service operations"| node_services
node_streaming -->|"reads node state"| node_nodedb
node_streaming -->|"reads service data"| node_services
node_streaming -->|"reads traffic data"| node_traffic
node_telegrambot -.->|"dispatches management"| node_nodes
node_telegrambot -.->|"dispatches controls"| node_services
node_telegrambot -.->|"dispatches monitoring"| node_traffic
node_telegrambot -.->|"offers backups"| node_backup
node_telegrambot -.->|"offers updates"| node_update
node_telegrambot -.->|"delivers alerts"| node_alerts
node_telegrambot -.->|"manages VPN panels"| node_vpn
node_webapp -->|"registers routes"| node_auth
node_webapi -->|"checks permissions"| node_rbac
node_webapi -->|"uses authentication"| node_auth
node_nodedb -->|"persists records"| node_models
node_nodedb -->|"uses database config"| node_config
node_telegrambot -->|"loads settings"| node_config
node_telegrambot -->|"shares runtime state"| node_shared
node_background -->|"updates runtime state"| node_shared

click node_agent "https://github.com/jatixs/tgbotvpscp/blob/main/node/node.py"
click node_telegrambot "https://github.com/jatixs/tgbotvpscp/blob/main/bot.py"
click node_webapp "https://github.com/jatixs/tgbotvpscp/blob/main/core/web/app.py"
click node_webviews "https://github.com/jatixs/tgbotvpscp/blob/main/core/web/views.py"
click node_webassets "https://github.com/jatixs/tgbotvpscp/blob/main/core/static/js/dashboard.js"
click node_webapi "https://github.com/jatixs/tgbotvpscp/blob/main/core/web/api_nodes.py"
click node_streaming "https://github.com/jatixs/tgbotvpscp/blob/main/core/web/streaming.py"
click node_background "https://github.com/jatixs/tgbotvpscp/blob/main/core/tasks.py"
click node_nodes "https://github.com/jatixs/tgbotvpscp/blob/main/modules/nodes.py"
click node_services "https://github.com/jatixs/tgbotvpscp/blob/main/modules/services.py"
click node_traffic "https://github.com/jatixs/tgbotvpscp/blob/main/modules/traffic.py"
click node_backup "https://github.com/jatixs/tgbotvpscp/blob/main/modules/backups.py"
click node_update "https://github.com/jatixs/tgbotvpscp/blob/main/modules/update.py"
click node_alerts "https://github.com/jatixs/tgbotvpscp/blob/main/modules/client_alerts.py"
click node_vpn "https://github.com/jatixs/tgbotvpscp/blob/main/modules/vless.py"
click node_auth "https://github.com/jatixs/tgbotvpscp/blob/main/core/web/auth.py"
click node_rbac "https://github.com/jatixs/tgbotvpscp/blob/main/core/rbac.py"
click node_config "https://github.com/jatixs/tgbotvpscp/blob/main/core/config.py"
click node_nodedb "https://github.com/jatixs/tgbotvpscp/blob/main/core/nodes_db.py"
click node_models "https://github.com/jatixs/tgbotvpscp/blob/main/core/models.py"
click node_shared "https://github.com/jatixs/tgbotvpscp/blob/main/core/shared_state.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_telegrambot,node_webapp,node_webviews,node_webassets,node_webuser toneBlue
class node_webapi,node_streaming,node_background toneAmber
class node_nodes,node_services,node_traffic toneMint
class node_backup,node_update,node_alerts,node_vpn toneRose
class node_auth,node_rbac,node_config,node_nodedb,node_models,node_shared,node_admin,node_telegram toneIndigo
class node_agent toneTeal
```

## Components

### User interfaces

- [Telegram bot](https://github.com/jatixs/tgbotvpscp/blob/main/bot.py): `bot.py`
- [Web app](https://github.com/jatixs/tgbotvpscp/blob/main/core/web/app.py): `core/web/app.py`
- [Dashboard views](https://github.com/jatixs/tgbotvpscp/blob/main/core/web/views.py): `core/web/views.py`
- [Dashboard client](https://github.com/jatixs/tgbotvpscp/blob/main/core/static/js/dashboard.js): `core/static/js/dashboard.js`

### Control plane

- [Node API](https://github.com/jatixs/tgbotvpscp/blob/main/core/web/api_nodes.py): `core/web/api_nodes.py`
- [Live streams](https://github.com/jatixs/tgbotvpscp/blob/main/core/web/streaming.py): `core/web/streaming.py`
- [Background tasks](https://github.com/jatixs/tgbotvpscp/blob/main/core/tasks.py): `core/tasks.py`

### Node operations

- [Node management](https://github.com/jatixs/tgbotvpscp/blob/main/modules/nodes.py): `modules/nodes.py`
- [Service manager](https://github.com/jatixs/tgbotvpscp/blob/main/modules/services.py): `modules/services.py`
- [Traffic monitor](https://github.com/jatixs/tgbotvpscp/blob/main/modules/traffic.py): `modules/traffic.py`

### Operations features

- [Backup manager](https://github.com/jatixs/tgbotvpscp/blob/main/modules/backups.py): `modules/backups.py`
- [Updates](https://github.com/jatixs/tgbotvpscp/blob/main/modules/update.py): `modules/update.py`
- [Alerts and notifications](https://github.com/jatixs/tgbotvpscp/blob/main/modules/client_alerts.py): `modules/client_alerts.py`
- [VLESS / Xray](https://github.com/jatixs/tgbotvpscp/blob/main/modules/vless.py): `modules/vless.py`

### State and security

- [Web authentication](https://github.com/jatixs/tgbotvpscp/blob/main/core/web/auth.py): `core/web/auth.py`
- [Access control](https://github.com/jatixs/tgbotvpscp/blob/main/core/rbac.py): `core/rbac.py`
- [Configuration](https://github.com/jatixs/tgbotvpscp/blob/main/core/config.py): `core/config.py`
- [Node database](https://github.com/jatixs/tgbotvpscp/blob/main/core/nodes_db.py): `core/nodes_db.py`
- [Database models](https://github.com/jatixs/tgbotvpscp/blob/main/core/models.py): `core/models.py`
- [Shared runtime state](https://github.com/jatixs/tgbotvpscp/blob/main/core/shared_state.py): `core/shared_state.py`

### Other components

- **Administrator**
- **Telegram**
- **Web user**
- [Remote node agent](https://github.com/jatixs/tgbotvpscp/blob/main/node/node.py): `node/node.py`

## Connections

- Administrator → Telegram: uses
- Telegram → Telegram bot: sends commands
- Administrator → Web app: uses
- Web user → Web app: opens dashboard
- Telegram bot → Web app: starts (evidence: `bot.py`)
- Web app → Dashboard views: registers routes (evidence: `core/web/app.py`)
- Web app → Node API: registers routes (evidence: `core/web/app.py`)
- Web app → Live streams: registers routes (evidence: `core/web/app.py`)
- Web app → Background tasks: starts tasks (evidence: `core/web/app.py`)
- Dashboard views → Dashboard client: serves dashboard
- Dashboard client → Node API: requests node data
- Dashboard client → Live streams: receives SSE
- Remote node agent → Node API: reports node data
- Node API → Node database: uses node records (evidence: `core/web/api_nodes.py`)
- Node API → Service manager: uses service operations (evidence: `core/web/api_nodes.py`)
- Live streams → Node database: reads node state (evidence: `core/web/streaming.py`)
- Live streams → Service manager: reads service data (evidence: `core/web/streaming.py`)
- Live streams → Traffic monitor: reads traffic data (evidence: `core/web/streaming.py`)
- Telegram bot → Node management: dispatches management (evidence: `modules/nodes.py`)
- Telegram bot → Service manager: dispatches controls (evidence: `modules/services.py`)
- Telegram bot → Traffic monitor: dispatches monitoring (evidence: `modules/traffic.py`)
- Telegram bot → Backup manager: offers backups
- Telegram bot → Updates: offers updates
- Telegram bot → Alerts and notifications: delivers alerts (evidence: `modules/client_alerts.py`)
- Telegram bot → VLESS / Xray: manages VPN panels
- Web app → Web authentication: registers routes (evidence: `core/web/app.py`)
- Node API → Access control: checks permissions (evidence: `core/web/api_nodes.py`)
- Node API → Web authentication: uses authentication (evidence: `core/web/api_nodes.py`)
- Node database → Database models: persists records (evidence: `core/nodes_db.py`)
- Node database → Configuration: uses database config (evidence: `core/nodes_db.py`)
- Telegram bot → Configuration: loads settings (evidence: `bot.py`)
- Telegram bot → Shared runtime state: shares runtime state (evidence: `bot.py`)
- Background tasks → Shared runtime state: updates runtime state (evidence: `core/tasks.py`)
