# prasx/vless-manager-proxy architecture

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

- Interactive diagram: https://gitdiagram.com/prasx/vless-manager-proxy
- Repository: https://github.com/prasx/vless-manager-proxy

## Overview

#### Purpose and Runtime

VLESS Manager Proxy is a Flask-based control plane for importing, validating, selecting, and operating VLESS proxies through a local Xray instance. It exposes an HTML dashboard, REST/SSE APIs, and a generated subscription endpoint for VLESS clients.

Primary process entry point: `app.py`. Flask application creation and route registration are centralized in `app/__init__.py`. Deployment is intended as a systemd service via `vless-manager.service`.

#### Web and API Boundary

Server-rendered dashboard pages are handled separately from operational APIs:
- Page routes: `app/routes/pages.py`
- REST APIs, SSE test-progress stream, subscription, Xray controls, traffic/connections endpoints: `app/routes/api.py`
- Browser clients and dashboard interactions: `static/dashboard.js`, `static/sources.js`, `static/settings.js`

The API is the control boundary between the UI/external consumers and proxy lifecycle services. `/api/subscribe.txt` is a machine-facing output consumed by VLESS-compatible clients.

#### Persistent State and Settings

SQLite is the durable source of truth for proxies, sources, settings, logs, and likely test/traffic state:
- `app/db.py`
- `config.py`

The database layer owns schema initialization/migrations and settings access. Runtime configuration combines base defaults in `config.py`, persisted UI settings, and potentially environment configuration such as import proxy settings. Generated subscription content is cached/exported as configured through the subscription stage.

#### Source Import and Proxy Normalization

Import sources may be remote URLs or stored text content. Importing supports conditional HTTP retrieval through ETags, import-proxy routing, and curl fallback; repeated source imports remove stale proxies absent from the refreshed subscription:
- `app/importer.py`
- `app/vless.py`
- `app/utils.py`

`app/vless.py` is the protocol boundary that parses `vless://` inputs into structured proxy records/configuration. Utility enrichment determines country metadata from link fragments or external IP geolocation (`ip-api.com`).

#### Validation and Background Lifecycle

The proxy manager coordinates concurrent proxy checks, scheduled DB-only versus import-and-check runs, cancellation/progress reporting, optional failed-node cleanup, speed testing, and failover reconciliation:
- `app/proxy_manager.py`
- `app/importer.py`
- `app/db.py`

Validation is not merely socket probing: each candidate is tested using a temporary Xray execution and an HTTP `generate_204` request. Working candidates may then undergo throughput tests; those measurements influence active-node ordering. Progress crosses to clients via API/SSE rather than direct worker/UI coupling.

#### Xray Configuration and Apply Boundary

The configurator translates selected database proxies and settings into Xray configuration, including SOCKS/HTTP inbounds, country filtering, GeoSite routing, sniffing, Observatory, and balancer strategy:
- `app/xray_configurator.py`
- `app/subscribe.py`
- `config.py`

It also interfaces with Xray’s local gRPC API and system service lifecycle to apply/rebuild configuration and inspect outbounds. This is the critical side-effect boundary: database candidates become live Xray outbounds, while `app/subscribe.py` emits the corresponding allowed/working VLESS links for external clients.

#### Monitoring and Host Dependencies

Operational visibility includes Xray outbound status, application logs, traffic history, active connections, and performance recommendations:
- `app/proxy_manager.py`
- `app/routes/api.py`
- `static/logs.js`

Material dependencies are Python 3.9+, Flask, SQLite, Xray 26.3+, and systemd. Xray needs installed geo assets (`geosite.dat`, `geoip.dat`) for routing. Host-level traffic and connection telemetry depends on `nftables` and `conntrack`; management may invoke `systemctl` to control the separate Xray service.

Main entry points: [`app/routes/api.py`](https://github.com/prasx/vless-manager-proxy/blob/main/app/routes/api.py) (Control API and SSE), [`app/proxy_manager.py`](https://github.com/prasx/vless-manager-proxy/blob/main/app/proxy_manager.py) (Proxy manager), [`app/xray_configurator.py`](https://github.com/prasx/vless-manager-proxy/blob/main/app/xray_configurator.py) (Xray configurator), [`app/db.py`](https://github.com/prasx/vless-manager-proxy/blob/main/app/db.py) (SQLite state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web boundary"]
  node_entry["Application entry<br/>Python entrypoint<br/>[app.py]"]
  node_flask["Flask application<br/>application factory<br/>[__init__.py]"]
  node_pages["Dashboard pages<br/>page routes<br/>[pages.py]"]
  node_api["Control API and SSE<br/>REST/SSE routes<br/>[api.py]"]
  node_browser["Browser dashboard<br/>browser clients<br/>[dashboard.js]"]
end

subgraph group_state["State and import"]
  node_database[("SQLite state<br/>database layer<br/>[db.py]")]
  node_defaults["Base configuration<br/>[config.py]"]
  node_importer["Source importer<br/>import service<br/>[importer.py]"]
  node_vless["VLESS parser<br/>protocol normalization<br/>[vless.py]"]
  node_enrichment["Proxy enrichment<br/>metadata utility<br/>[utils.py]"]
end

subgraph group_lifecycle["Validation and apply"]
  node_manager["Proxy manager<br/>background coordinator<br/>[proxy_manager.py]"]
  node_validator{{"Temporary Xray validation<br/>candidate check"}}
  node_configurator["Xray configurator<br/>configuration and control"]
  node_subscription["Subscription generator<br/>VLESS export<br/>[subscribe.py]"]
end

subgraph group_runtime["Host runtime"]
  node_xray{{"Xray service<br/>proxy runtime"}}
  node_systemd["systemd<br/>service manager"]
  node_telemetry["Host telemetry<br/>nftables and conntrack"]
end

node_clients(("VLESS clients<br/>subscription consumers"))

node_entry -->|"starts"| node_flask
node_flask -->|"registers"| node_pages
node_flask -->|"registers"| node_api
node_browser -->|"loads dashboard"| node_pages
node_browser -->|"uses controls and SSE"| node_api
node_api -->|"operates"| node_manager
node_api -->|"serves subscribe.txt"| node_subscription
node_api -->|"reads state and logs"| node_database
node_importer -->|"normalizes links"| node_vless
node_importer -->|"enriches proxies"| node_enrichment
node_importer -->|"persists refreshed sources"| node_database
node_manager -->|"runs import-and-check"| node_importer
node_manager -->|"selects and records results"| node_database
node_manager -->|"checks candidates"| node_validator
node_validator -->|"temporary execution"| node_xray
node_manager -->|"reconciles active nodes"| node_configurator
node_database -->|"selected proxies and settings"| node_configurator
node_defaults -->|"routing defaults"| node_configurator
node_configurator -->|"applies configuration and gRPC control"| node_xray
node_subscription -->|"exports working proxies"| node_database
node_subscription -->|"VLESS links"| node_clients
node_api -->|"queries traffic and connections"| node_telemetry
node_systemd -->|"runs manager service"| node_entry
node_configurator -->|"controls Xray service"| node_systemd

click node_entry "https://github.com/prasx/vless-manager-proxy/blob/main/app.py"
click node_flask "https://github.com/prasx/vless-manager-proxy/blob/main/app/__init__.py"
click node_pages "https://github.com/prasx/vless-manager-proxy/blob/main/app/routes/pages.py"
click node_api "https://github.com/prasx/vless-manager-proxy/blob/main/app/routes/api.py"
click node_browser "https://github.com/prasx/vless-manager-proxy/blob/main/static/dashboard.js"
click node_database "https://github.com/prasx/vless-manager-proxy/blob/main/app/db.py"
click node_defaults "https://github.com/prasx/vless-manager-proxy/blob/main/config.py"
click node_importer "https://github.com/prasx/vless-manager-proxy/blob/main/app/importer.py"
click node_vless "https://github.com/prasx/vless-manager-proxy/blob/main/app/vless.py"
click node_enrichment "https://github.com/prasx/vless-manager-proxy/blob/main/app/utils.py"
click node_manager "https://github.com/prasx/vless-manager-proxy/blob/main/app/proxy_manager.py"
click node_configurator "https://github.com/prasx/vless-manager-proxy/blob/main/app/xray_configurator.py"
click node_subscription "https://github.com/prasx/vless-manager-proxy/blob/main/app/subscribe.py"
click node_systemd "https://github.com/prasx/vless-manager-proxy/blob/main/vless-manager.service"

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_flask,node_pages,node_api,node_browser toneBlue
class node_database,node_defaults,node_importer,node_vless,node_enrichment toneAmber
class node_manager,node_validator,node_configurator,node_subscription toneMint
class node_xray,node_systemd,node_telemetry toneRose
class node_clients toneNeutral
```

## Components

### Web boundary

- [Application entry](https://github.com/prasx/vless-manager-proxy/blob/main/app.py): Python entrypoint · `app.py`
- [Flask application](https://github.com/prasx/vless-manager-proxy/blob/main/app/__init__.py): application factory · Registers dashboard and operational routes. · `app/__init__.py`
- [Dashboard pages](https://github.com/prasx/vless-manager-proxy/blob/main/app/routes/pages.py): page routes · `app/routes/pages.py`
- [Control API and SSE](https://github.com/prasx/vless-manager-proxy/blob/main/app/routes/api.py): REST/SSE routes · Serves controls, telemetry, progress, and subscriptions. · `app/routes/api.py`
- [Browser dashboard](https://github.com/prasx/vless-manager-proxy/blob/main/static/dashboard.js): browser clients · `static/dashboard.js`

### State and import

- [SQLite state](https://github.com/prasx/vless-manager-proxy/blob/main/app/db.py): database layer · Owns schema, proxies, sources, settings, logs, and measurements. · `app/db.py`
- [Base configuration](https://github.com/prasx/vless-manager-proxy/blob/main/config.py): configuration · `config.py`
- [Source importer](https://github.com/prasx/vless-manager-proxy/blob/main/app/importer.py): import service · Refreshes URL or text sources and removes stale source proxies. · `app/importer.py`
- [VLESS parser](https://github.com/prasx/vless-manager-proxy/blob/main/app/vless.py): protocol normalization · Parses VLESS links into structured proxy records. · `app/vless.py`
- [Proxy enrichment](https://github.com/prasx/vless-manager-proxy/blob/main/app/utils.py): metadata utility · Derives country metadata from fragments or IP geolocation. · `app/utils.py`

### Validation and apply

- [Proxy manager](https://github.com/prasx/vless-manager-proxy/blob/main/app/proxy_manager.py): background coordinator · Runs checks, scheduling, cancellation, speed tests, and failover. · `app/proxy_manager.py`
- **Temporary Xray validation**: candidate check · Tests candidates through Xray with an HTTP generate_204 request.
- [Xray configurator](https://github.com/prasx/vless-manager-proxy/blob/main/app/xray_configurator.py): configuration and control · Builds Xray outbounds, routing, balancing, and applies runtime changes. · `app/xray_configurator.py`
- [Subscription generator](https://github.com/prasx/vless-manager-proxy/blob/main/app/subscribe.py): VLESS export · Emits allowed working VLESS links for client consumption. · `app/subscribe.py`

### Host runtime

- **Xray service**: proxy runtime · Local Xray process with gRPC API and geo routing assets.
- [systemd](https://github.com/prasx/vless-manager-proxy/blob/main/vless-manager.service): service manager · Runs the manager and controls the separate Xray service. · `vless-manager.service`
- **Host telemetry**: nftables and conntrack · Provides traffic history and active connection data.

### Other components

- **VLESS clients**: subscription consumers

## Connections

- Application entry → Flask application: starts
- Flask application → Dashboard pages: registers
- Flask application → Control API and SSE: registers
- Browser dashboard → Dashboard pages: loads dashboard
- Browser dashboard → Control API and SSE: uses controls and SSE
- Control API and SSE → Proxy manager: operates
- Control API and SSE → Subscription generator: serves subscribe.txt
- Control API and SSE → SQLite state: reads state and logs
- Source importer → VLESS parser: normalizes links
- Source importer → Proxy enrichment: enriches proxies
- Source importer → SQLite state: persists refreshed sources
- Proxy manager → Source importer: runs import-and-check
- Proxy manager → SQLite state: selects and records results
- Proxy manager → Temporary Xray validation: checks candidates
- Temporary Xray validation → Xray service: temporary execution
- Proxy manager → Xray configurator: reconciles active nodes
- SQLite state → Xray configurator: selected proxies and settings
- Base configuration → Xray configurator: routing defaults
- Xray configurator → Xray service: applies configuration and gRPC control
- Subscription generator → SQLite state: exports working proxies
- Subscription generator → VLESS clients: VLESS links
- Control API and SSE → Host telemetry: queries traffic and connections
- systemd → Application entry: runs manager service
- Xray configurator → systemd: controls Xray service