# kereal/rs8kvn_bot architecture

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

- Interactive diagram: https://gitdiagram.com/kereal/rs8kvn_bot
- Repository: https://github.com/kereal/rs8kvn_bot

## Overview

#### Purpose and Entry Points
This Go service distributes VPN subscriptions through a Telegram bot and HTTP endpoints. It manages users, plans, orders, trials, referrals, subscriptions, and synchronization to VPN nodes. Process startup and lifecycle wiring are in `cmd/bot/main.go` and `cmd/bot/lifecycle.go`; the built binary runs as `./cmd/bot`.

#### Composition Root and Runtime
Configuration, logging, database migration, HTTP server, Telegram handlers, workers, and shutdown are assembled at startup. The runtime is container-oriented (`Dockerfile`, `docker-compose.yml`) and exposes HTTP on port 8880. Configuration is environment-driven through `internal/config/config.go`; operational liveness/readiness and metrics are part of the same process.

#### Telegram Interaction Layer
`internal/bot/handler.go` routes Telegram updates into command, callback, menu, admin, referral, and subscription flows. It is the user-facing control plane: it creates or displays subscriptions, emits QR/import links, administers broadcasts, and exposes referral actions. Delivery and UI formatting are separated into `internal/bot/message_sender.go`, `internal/bot/menu.go`, and `internal/bot/subscription_handler.go`.

#### Domain Service Layer
Business workflows sit behind bot and HTTP transports. Subscription lifecycle, traffic, reminders, and node synchronization are handled by `internal/service/subscription.go`, `internal/service/subscription_traffic.go`, and `internal/service/sync.go`. Order and product/plan behavior is represented by `internal/service/order.go`. This layer coordinates durable database state with remote VPN-panel state rather than letting transports call panels directly.

#### Persistence and State Model
PostgreSQL-style relational persistence is abstracted by `internal/database/service.go`, with repositories for subscriptions, nodes, plans/products, orders, invites, and trials. The embedded migration sequence establishes the architectural model: subscriptions map to plans and multiple nodes, while orders/products support commercial flows; see `internal/database/migrations/017_create_orders.up.sql`, `internal/database/migrations/018_create_subscription_nodes.up.sql`, and `internal/database/subscription_nodes.go`. Backup creation/rotation is provided by `internal/backup/backup.go`.

#### VPN Node Boundary
`internal/vpn/client.go` defines the multi-node client abstraction. Concrete integrations include 3x-ui, proxman, and direct fetch sources in `internal/vpn/threex_ui.go`, `internal/vpn/proxman.go`, and `internal/vpn/fetch.go`. Sync services provision/update/delete remote clients per assigned node; failures and remote availability are therefore isolated at this adapter boundary.

#### HTTP Delivery and Subscription Aggregation
`internal/web/web.go` exposes health, readiness, invite/trial, metrics, payment callback stub, and subscription routes. The subscription server in `internal/subserver/service.go` and `internal/subserver/subscription_handler.go` validates `/sub/{subID}`, caches responses, fetches all active assigned nodes, merges protocol outputs, adds profile/device headers, and records access data. Its node fetch boundary is implemented by `internal/subserver/fetch.go`.

#### Background Operations and Observability
Periodic workers execute backup, expiry, trial cleanup, reminder, and pending subscription-sync work via `internal/scheduler/subscription_sync_worker.go`, `internal/scheduler/subscription_expire_worker.go`, and `internal/scheduler/backup.go`. Prometheus instrumentation is exposed through `internal/metrics/metrics.go`; external error/performance reporting is Sentry. In-memory caches and rate limiting protect recurring reads and public trial routes (`internal/bot/referral_cache.go`, `internal/ratelimiter/per_user.go`).

Main entry points: [`internal/database/service.go`](https://github.com/kereal/rs8kvn_bot/blob/main/internal/database/service.go) (Relational persistence), [`cmd/bot/main.go`](https://github.com/kereal/rs8kvn_bot/blob/main/cmd/bot/main.go) (Startup & lifecycle), [`internal/bot/handler.go`](https://github.com/kereal/rs8kvn_bot/blob/main/internal/bot/handler.go) (Telegram update router), [`internal/web/web.go`](https://github.com/kereal/rs8kvn_bot/blob/main/internal/web/web.go) (HTTP endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_startup{{"Startup &amp; lifecycle<br/>Go entrypoint<br/>[main.go]"}}
  node_config["Environment config<br/>configuration<br/>[config.go]"]
end

subgraph group_interfaces["Delivery"]
  node_bot["Telegram update router<br/>bot transport<br/>[handler.go]"]
  node_bot_delivery["Bot UI delivery<br/>bot presentation<br/>[message_sender.go]"]
  node_http["HTTP endpoints<br/>HTTP transport<br/>[web.go]"]
  node_subscription_server["Subscription server<br/>subscription delivery<br/>[service.go]"]
end

subgraph group_domain["Domain workflows"]
  node_subscription_workflow["Subscription lifecycle<br/>domain service<br/>[subscription.go]"]
  node_order_workflow["Orders &amp; plans<br/>domain service<br/>[order.go]"]
  node_sync_workflow["Node synchronization<br/>domain service<br/>[sync.go]"]
end

subgraph group_data["State and adapters"]
  node_database[("Relational persistence<br/>database service<br/>[service.go]")]
  node_subscription_nodes["Subscription-node assignments<br/>persistence model"]
  node_vpn_client{{"VPN client abstraction<br/>adapter interface<br/>[client.go]"}}
  node_vpn_adapters["VPN panel adapters<br/>remote adapters<br/>[threex_ui.go]"]
  node_node_fetch["Node subscription fetch<br/>remote fetch adapter<br/>[fetch.go]"]
end

subgraph group_operations["Background operations"]
  node_scheduler["Periodic workers<br/>scheduler"]
  node_backup["Database backup rotation<br/>backup service<br/>[backup.go]"]
  node_metrics["Metrics &amp; reporting<br/>observability<br/>[metrics.go]"]
  node_rate_limit["Public route protection<br/>rate limiter<br/>[per_user.go]"]
end

node_startup -->|"loads"| node_config
node_startup -->|"wires"| node_bot
node_startup -->|"serves :8880"| node_http
node_startup -->|"starts"| node_scheduler
node_startup -->|"initializes"| node_metrics
node_bot -->|"renders via"| node_bot_delivery
node_bot -->|"subscription actions"| node_subscription_workflow
node_bot -->|"commercial actions"| node_order_workflow
node_http -->|"subscription route"| node_subscription_server
node_http -->|"guards public routes"| node_rate_limit
node_subscription_server -->|"validates subscription"| node_database
node_subscription_server -->|"fetches active nodes"| node_node_fetch
node_node_fetch -->|"retrieves node output"| node_vpn_adapters
node_subscription_workflow -->|"reads and writes"| node_database
node_order_workflow -->|"persists orders and plans"| node_database
node_sync_workflow -->|"reads assignments"| node_database
node_sync_workflow -->|"provisions clients"| node_vpn_client
node_vpn_client -->|"implemented by"| node_vpn_adapters
node_database -->|"stores mapping"| node_subscription_nodes
node_scheduler -->|"expiry and reminders"| node_subscription_workflow
node_scheduler -->|"pending sync"| node_sync_workflow
node_scheduler -->|"runs"| node_backup
node_backup -->|"backs up"| node_database
node_http -->|"exposes"| node_metrics

click node_startup "https://github.com/kereal/rs8kvn_bot/blob/main/cmd/bot/main.go"
click node_config "https://github.com/kereal/rs8kvn_bot/blob/main/internal/config/config.go"
click node_bot "https://github.com/kereal/rs8kvn_bot/blob/main/internal/bot/handler.go"
click node_bot_delivery "https://github.com/kereal/rs8kvn_bot/blob/main/internal/bot/message_sender.go"
click node_http "https://github.com/kereal/rs8kvn_bot/blob/main/internal/web/web.go"
click node_subscription_server "https://github.com/kereal/rs8kvn_bot/blob/main/internal/subserver/service.go"
click node_subscription_workflow "https://github.com/kereal/rs8kvn_bot/blob/main/internal/service/subscription.go"
click node_order_workflow "https://github.com/kereal/rs8kvn_bot/blob/main/internal/service/order.go"
click node_sync_workflow "https://github.com/kereal/rs8kvn_bot/blob/main/internal/service/sync.go"
click node_database "https://github.com/kereal/rs8kvn_bot/blob/main/internal/database/service.go"
click node_subscription_nodes "https://github.com/kereal/rs8kvn_bot/blob/main/internal/database/subscription_nodes.go"
click node_vpn_client "https://github.com/kereal/rs8kvn_bot/blob/main/internal/vpn/client.go"
click node_vpn_adapters "https://github.com/kereal/rs8kvn_bot/blob/main/internal/vpn/threex_ui.go"
click node_node_fetch "https://github.com/kereal/rs8kvn_bot/blob/main/internal/subserver/fetch.go"
click node_scheduler "https://github.com/kereal/rs8kvn_bot/blob/main/internal/scheduler/subscription_sync_worker.go"
click node_backup "https://github.com/kereal/rs8kvn_bot/blob/main/internal/backup/backup.go"
click node_metrics "https://github.com/kereal/rs8kvn_bot/blob/main/internal/metrics/metrics.go"
click node_rate_limit "https://github.com/kereal/rs8kvn_bot/blob/main/internal/ratelimiter/per_user.go"

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_startup,node_config toneBlue
class node_bot,node_bot_delivery,node_http,node_subscription_server toneAmber
class node_subscription_workflow,node_order_workflow,node_sync_workflow toneMint
class node_database,node_subscription_nodes,node_vpn_client,node_vpn_adapters,node_node_fetch toneRose
class node_scheduler,node_backup,node_metrics,node_rate_limit toneIndigo
```

## Components

### Runtime

- [Startup & lifecycle](https://github.com/kereal/rs8kvn_bot/blob/main/cmd/bot/main.go): Go entrypoint · Assembles process dependencies and shutdown. · `cmd/bot/main.go`
- [Environment config](https://github.com/kereal/rs8kvn_bot/blob/main/internal/config/config.go): configuration · `internal/config/config.go`

### Delivery

- [Telegram update router](https://github.com/kereal/rs8kvn_bot/blob/main/internal/bot/handler.go): bot transport · Routes commands, callbacks, menus, admin, referral, and subscription actions. · `internal/bot/handler.go`
- [Bot UI delivery](https://github.com/kereal/rs8kvn_bot/blob/main/internal/bot/message_sender.go): bot presentation · Formats menus and subscription messages. · `internal/bot/message_sender.go`
- [HTTP endpoints](https://github.com/kereal/rs8kvn_bot/blob/main/internal/web/web.go): HTTP transport · Serves health, readiness, invites, trials, metrics, callbacks, and subscription routes. · `internal/web/web.go`
- [Subscription server](https://github.com/kereal/rs8kvn_bot/blob/main/internal/subserver/service.go): subscription delivery · Validates public subscriptions and composes assigned-node outputs. · `internal/subserver/service.go`

### Domain workflows

- [Subscription lifecycle](https://github.com/kereal/rs8kvn_bot/blob/main/internal/service/subscription.go): domain service · Coordinates lifecycle, traffic, reminders, and durable state. · `internal/service/subscription.go`
- [Orders & plans](https://github.com/kereal/rs8kvn_bot/blob/main/internal/service/order.go): domain service · `internal/service/order.go`
- [Node synchronization](https://github.com/kereal/rs8kvn_bot/blob/main/internal/service/sync.go): domain service · Reconciles subscription clients across assigned VPN nodes. · `internal/service/sync.go`

### State and adapters

- [Relational persistence](https://github.com/kereal/rs8kvn_bot/blob/main/internal/database/service.go): database service · Repository boundary for subscriptions, nodes, plans, orders, invites, and trials. · `internal/database/service.go`
- [Subscription-node assignments](https://github.com/kereal/rs8kvn_bot/blob/main/internal/database/subscription_nodes.go): persistence model · Maps subscriptions to multiple VPN nodes. · `internal/database/subscription_nodes.go`
- [VPN client abstraction](https://github.com/kereal/rs8kvn_bot/blob/main/internal/vpn/client.go): adapter interface · Isolates remote node provisioning and availability failures. · `internal/vpn/client.go`
- [VPN panel adapters](https://github.com/kereal/rs8kvn_bot/blob/main/internal/vpn/threex_ui.go): remote adapters · 3x-ui, proxman, and direct-fetch integrations. · `internal/vpn/threex_ui.go`
- [Node subscription fetch](https://github.com/kereal/rs8kvn_bot/blob/main/internal/subserver/fetch.go): remote fetch adapter · `internal/subserver/fetch.go`

### Background operations

- [Periodic workers](https://github.com/kereal/rs8kvn_bot/blob/main/internal/scheduler/subscription_sync_worker.go): scheduler · Runs expiry, trial cleanup, reminders, backup, and pending sync work. · `internal/scheduler/subscription_sync_worker.go`
- [Database backup rotation](https://github.com/kereal/rs8kvn_bot/blob/main/internal/backup/backup.go): backup service · `internal/backup/backup.go`
- [Metrics & reporting](https://github.com/kereal/rs8kvn_bot/blob/main/internal/metrics/metrics.go): observability · Prometheus metrics and Sentry reporting. · `internal/metrics/metrics.go`
- [Public route protection](https://github.com/kereal/rs8kvn_bot/blob/main/internal/ratelimiter/per_user.go): rate limiter · Protects recurring reads and public trial routes. · `internal/ratelimiter/per_user.go`

## Connections

- Startup & lifecycle → Environment config: loads
- Startup & lifecycle → Telegram update router: wires
- Startup & lifecycle → HTTP endpoints: serves :8880
- Startup & lifecycle → Periodic workers: starts
- Startup & lifecycle → Metrics & reporting: initializes
- Telegram update router → Bot UI delivery: renders via
- Telegram update router → Subscription lifecycle: subscription actions
- Telegram update router → Orders & plans: commercial actions
- HTTP endpoints → Subscription server: subscription route
- HTTP endpoints → Public route protection: guards public routes
- Subscription server → Relational persistence: validates subscription
- Subscription server → Node subscription fetch: fetches active nodes
- Node subscription fetch → VPN panel adapters: retrieves node output
- Subscription lifecycle → Relational persistence: reads and writes
- Orders & plans → Relational persistence: persists orders and plans
- Node synchronization → Relational persistence: reads assignments
- Node synchronization → VPN client abstraction: provisions clients
- VPN client abstraction → VPN panel adapters: implemented by
- Relational persistence → Subscription-node assignments: stores mapping
- Periodic workers → Subscription lifecycle: expiry and reminders
- Periodic workers → Node synchronization: pending sync
- Periodic workers → Database backup rotation: runs
- Database backup rotation → Relational persistence: backs up
- HTTP endpoints → Metrics & reporting: exposes