# freedmanofart/vpnsrv architecture

> Architecture diagram of the GitHub repository freedmanofart/vpnsrv, 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/freedmanofart/vpnsrv
- Repository: https://github.com/freedmanofart/vpnsrv

## Overview

VPN Service sells and provisions VPN access through Telegram, web, and administrative interfaces. The core journey is user/order interaction → API account, plan, and payment handling → subscription provisioning through the 3x-ui master → client configuration delivery; background work expires access and reconciles panel state. The graph also preserves device activation, web-cabinet/admin, notifications, and audit capabilities. Some route and worker internals were not sampled, so those links rely on README statements or indexed references rather than inspected implementations.

Main entry points: [`api/app/main.py`](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/main.py) (FastAPI entry), [`api/app/db/session.py`](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/db/session.py) (Database access), [`api/app/api/routes/client.py`](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/client.py) (Account and device API), [`api/app/services/payments.py`](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/payments.py) (Payment handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_bot["Telegram bot<br/>[main.py]"]
  node_web["Web cabinet<br/>[web.py]"]
  node_admin["Web admin<br/>[admin.py]"]
end

subgraph group_api["API and domain"]
  node_api_entry["FastAPI entry<br/>[main.py]"]
  node_account_routes["Account and device API<br/>[client.py]"]
  node_plans["Plans API<br/>[plans.py]"]
  node_subscription_routes["Subscription API<br/>[subscriptions.py]"]
  node_payment_routes["Payment API<br/>[payments.py]"]
  node_vpn_routes["VPN node API<br/>[vpn.py]"]
  node_payment_service["Payment handling<br/>[payments.py]"]
end

subgraph group_operations["Access operations"]
  node_provisioning["Client provisioning<br/>[provisioning.py]"]
  node_panel_client["3x-ui integration<br/>[threexui.py]"]
  node_worker["Lifecycle worker<br/>[worker.py]"]
  node_lifecycle["Expiry and lifecycle<br/>[lifecycle.py]"]
  node_reconciliation["Node reconciliation<br/>[reconciliation.py]"]
  node_notifications["Notifications<br/>[notifications.py]"]
end

subgraph group_state["State and integrations"]
  node_security["API security<br/>[security.py]"]
  node_audit["Audit service<br/>[audit.py]"]
  node_db_session["Database access<br/>[session.py]"]
  node_db_models["Service records"]
end

node_customer(("VPN customer"))
node_telegram["Telegram"]
node_postgres[("PostgreSQL")]
node_panel["3x-ui master"]
node_payment_provider["Payment providers"]

node_customer -->|"uses"| node_telegram
node_telegram -->|"delivers interaction"| node_bot
node_bot -->|"calls API"| node_api_entry
node_customer -->|"uses cabinet"| node_web
node_customer -->|"uses service"| node_api_entry
node_api_entry -->|"routes to"| node_account_routes
node_api_entry -->|"routes to"| node_plans
node_api_entry -->|"routes to"| node_subscription_routes
node_api_entry -->|"routes to"| node_payment_routes
node_api_entry -->|"routes to"| node_vpn_routes
node_api_entry -->|"routes to"| node_web
node_api_entry -->|"routes to"| node_admin
node_subscription_routes -->|"calls"| node_provisioning
node_payment_service -->|"calls"| node_provisioning
node_provisioning -->|"manages clients"| node_panel_client
node_panel_client -->|"REST requests"| node_panel
node_payment_routes -.->|"handles payments"| node_payment_service
node_payment_service -.->|"uses provider"| node_payment_provider
node_worker -->|"runs lifecycle"| node_lifecycle
node_worker -.->|"runs reconciliation"| node_reconciliation
node_worker -->|"syncs access"| node_panel
node_account_routes -.->|"uses client operations"| node_provisioning
node_payment_service -.->|"notifies"| node_notifications
node_admin -->|"authenticates"| node_security
node_api_entry -->|"protects routes"| node_security
node_subscription_routes -->|"queries records"| node_db_session
node_web -->|"queries records"| node_db_session
node_admin -->|"queries records"| node_db_session
node_account_routes -->|"queries records"| node_db_session
node_db_session -->|"opens sessions"| node_postgres
node_db_models -->|"stores service data"| node_postgres
node_account_routes -->|"writes audit"| node_audit
node_audit -->|"persists audit log"| node_db_models
node_notifications -->|"sends messages"| node_telegram

click node_bot "https://github.com/freedmanofart/vpnsrv/blob/main/bot/app/main.py"
click node_web "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/web.py"
click node_admin "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/admin.py"
click node_api_entry "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/main.py"
click node_account_routes "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/client.py"
click node_plans "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/plans.py"
click node_subscription_routes "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/subscriptions.py"
click node_payment_routes "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/payments.py"
click node_vpn_routes "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/vpn.py"
click node_payment_service "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/payments.py"
click node_provisioning "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/provisioning.py"
click node_panel_client "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/threexui.py"
click node_worker "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/worker.py"
click node_lifecycle "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/lifecycle.py"
click node_reconciliation "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/reconciliation.py"
click node_notifications "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/notifications.py"
click node_security "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/core/security.py"
click node_audit "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/audit.py"
click node_db_session "https://github.com/freedmanofart/vpnsrv/blob/main/api/app/db/session.py"
click node_db_models "https://github.com/freedmanofart/vpnsrv/tree/main/api/app/db/models"

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,node_web,node_admin,node_panel toneBlue
class node_api_entry,node_account_routes,node_plans,node_subscription_routes,node_payment_routes,node_vpn_routes,node_payment_service,node_postgres toneAmber
class node_provisioning,node_panel_client,node_worker,node_lifecycle,node_reconciliation,node_notifications toneMint
class node_security,node_audit,node_db_session,node_db_models toneRose
class node_customer,node_telegram,node_payment_provider toneIndigo
```

## Components

### User interfaces

- [Telegram bot](https://github.com/freedmanofart/vpnsrv/blob/main/bot/app/main.py): `bot/app/main.py`
- [Web cabinet](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/web.py): `api/app/api/routes/web.py`
- [Web admin](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/admin.py): `api/app/api/routes/admin.py`

### API and domain

- [FastAPI entry](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/main.py): `api/app/main.py`
- [Account and device API](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/client.py): `api/app/api/routes/client.py`
- [Plans API](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/plans.py): `api/app/api/routes/plans.py`
- [Subscription API](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/subscriptions.py): `api/app/api/routes/subscriptions.py`
- [Payment API](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/payments.py): `api/app/api/routes/payments.py`
- [VPN node API](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/api/routes/vpn.py): `api/app/api/routes/vpn.py`
- [Payment handling](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/payments.py): `api/app/services/payments.py`

### Access operations

- [Client provisioning](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/provisioning.py): `api/app/services/provisioning.py`
- [3x-ui integration](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/threexui.py): `api/app/services/threexui.py`
- [Lifecycle worker](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/worker.py): `api/app/worker.py`
- [Expiry and lifecycle](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/lifecycle.py): `api/app/services/lifecycle.py`
- [Node reconciliation](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/reconciliation.py): `api/app/services/reconciliation.py`
- [Notifications](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/notifications.py): `api/app/services/notifications.py`

### State and integrations

- [API security](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/core/security.py): `api/app/core/security.py`
- [Audit service](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/services/audit.py): `api/app/services/audit.py`
- [Database access](https://github.com/freedmanofart/vpnsrv/blob/main/api/app/db/session.py): `api/app/db/session.py`
- [Service records](https://github.com/freedmanofart/vpnsrv/tree/main/api/app/db/models): `api/app/db/models`

### Other components

- **VPN customer**
- **Telegram**
- **PostgreSQL**
- **3x-ui master**
- **Payment providers**

## Connections

- VPN customer → Telegram: uses
- Telegram → Telegram bot: delivers interaction
- Telegram bot → FastAPI entry: calls API
- VPN customer → Web cabinet: uses cabinet
- VPN customer → FastAPI entry: uses service
- FastAPI entry → Account and device API: routes to (evidence: `api/app/main.py`)
- FastAPI entry → Plans API: routes to (evidence: `api/app/main.py`)
- FastAPI entry → Subscription API: routes to (evidence: `api/app/main.py`)
- FastAPI entry → Payment API: routes to (evidence: `api/app/main.py`)
- FastAPI entry → VPN node API: routes to (evidence: `api/app/main.py`)
- FastAPI entry → Web cabinet: routes to (evidence: `api/app/main.py`)
- FastAPI entry → Web admin: routes to (evidence: `api/app/main.py`)
- Subscription API → Client provisioning: calls (evidence: `api/app/api/routes/subscriptions.py`)
- Payment handling → Client provisioning: calls (evidence: `api/app/services/payments.py`)
- Client provisioning → 3x-ui integration: manages clients (evidence: `api/app/services/provisioning.py`)
- 3x-ui integration → 3x-ui master: REST requests
- Payment API → Payment handling: handles payments
- Payment handling → Payment providers: uses provider
- Lifecycle worker → Expiry and lifecycle: runs lifecycle (evidence: `api/app/worker.py`)
- Lifecycle worker → Node reconciliation: runs reconciliation
- Lifecycle worker → 3x-ui master: syncs access
- Account and device API → Client provisioning: uses client operations
- Payment handling → Notifications: notifies
- Web admin → API security: authenticates (evidence: `api/app/api/routes/admin.py`)
- FastAPI entry → API security: protects routes (evidence: `api/app/main.py`)
- Subscription API → Database access: queries records (evidence: `api/app/api/routes/subscriptions.py`)
- Web cabinet → Database access: queries records (evidence: `api/app/api/routes/web.py`)
- Web admin → Database access: queries records (evidence: `api/app/api/routes/admin.py`)
- Account and device API → Database access: queries records (evidence: `api/app/api/routes/client.py`)
- Database access → PostgreSQL: opens sessions (evidence: `api/app/db/session.py`)
- Service records → PostgreSQL: stores service data
- Account and device API → Audit service: writes audit (evidence: `api/app/api/routes/client.py`)
- Audit service → Service records: persists audit log (evidence: `api/app/services/audit.py`)
- Notifications → Telegram: sends messages (evidence: `api/app/services/notifications.py`)