# returnfi/blitz architecture

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

- Interactive diagram: https://gitdiagram.com/returnfi/blitz
- Repository: https://github.com/returnfi/blitz

## Overview

Blitz is a Hysteria2 server management panel. The main workflow is an operator issuing management commands through the CLI, which delegates operations to its API layer; users can also manage the server through the WebPanel’s routed interface. The repository additionally includes traffic accounting, subscriptions, node configuration, Telegram management, WARP, and user storage. Several implementations are not sampled, so those capability branches are shown without inferred call links; edges reflect only visible calls or documented routing.

Main entry points: [`core/scripts/webpanel/app.py`](https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/app.py) (Web Application), [`core/scripts/webpanel/middleware/auth.py`](https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/middleware/auth.py) (Authentication Middleware), [`core/cli_api.py`](https://github.com/returnfi/blitz/blob/main/core/cli_api.py) (CLI API), [`core/cli.py`](https://github.com/returnfi/blitz/blob/main/core/cli.py) (Management CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Operator Entry"]
  node_cli["Management CLI<br/>[cli.py]"]
  node_cli_api["CLI API<br/>[cli_api.py]"]
end

subgraph group_web["WebPanel"]
  node_web_app["Web Application<br/>[app.py]"]
  node_web_auth["Authentication Middleware<br/>[auth.py]"]
  node_sessions["Session Management<br/>[session.py]"]
  node_web_config["Web Configuration<br/>[config.py]"]
  node_web_deps["Web Dependencies<br/>[dependency.py]"]
  node_web_routes["Web Routes"]
  node_hysteria_api["Hysteria API Routes<br/>[hysteria.py]"]
  node_server_routes["Server API Routes<br/>[server.py]"]
  node_user_routes["User Management Routes<br/>[user.py]"]
end

subgraph group_proxy["Proxy Management"]
  node_hysteria_ops["Hysteria Operations"]
  node_user_auth["User Authentication<br/>[user_auth.go]"]
  node_traffic["Traffic Accounting<br/>[traffic.py]"]
  node_subscriptions["Subscription Formats<br/>[normalsub.py]"]
  node_nodes["Node Management<br/>[node.py]"]
end

subgraph group_services["Companion Services"]
  node_telegram["Telegram Bot<br/>[runbot.py]"]
  node_warp["WARP Integration<br/>[warp.py]"]
  node_scheduler["Scheduled Tasks<br/>[scheduler.py]"]
end

subgraph group_state["Runtime State"]
  node_database[("User Database<br/>[database.py]")]
  node_paths["Shared Paths<br/>[paths.py]"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"delegates operations"| node_cli_api
node_web_app -->|"loads settings"| node_web_config
node_web_app -->|"registers middleware"| node_web_auth
node_web_app -->|"gets sessions"| node_web_deps
node_web_app -->|"mounts routers"| node_web_routes
node_web_auth -->|"validates sessions"| node_sessions
node_web_auth -->|"checks settings"| node_web_config
node_web_deps -->|"creates manager"| node_sessions
node_hysteria_api -->|"invokes operations"| node_cli_api
node_server_routes -->|"invokes operations"| node_cli_api
node_traffic -->|"reads and updates"| node_database

click node_cli "https://github.com/returnfi/blitz/blob/main/core/cli.py"
click node_cli_api "https://github.com/returnfi/blitz/blob/main/core/cli_api.py"
click node_web_app "https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/app.py"
click node_web_auth "https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/middleware/auth.py"
click node_sessions "https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/session/session.py"
click node_web_config "https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/config/config.py"
click node_web_deps "https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/dependency/dependency.py"
click node_web_routes "https://github.com/returnfi/blitz/tree/main/core/scripts/webpanel/routers"
click node_hysteria_api "https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/routers/api/v1/config/hysteria.py"
click node_server_routes "https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/routers/api/v1/server.py"
click node_user_routes "https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/routers/user/user.py"
click node_hysteria_ops "https://github.com/returnfi/blitz/tree/main/core/scripts/hysteria2"
click node_user_auth "https://github.com/returnfi/blitz/blob/main/core/scripts/auth/user_auth.go"
click node_traffic "https://github.com/returnfi/blitz/blob/main/core/traffic.py"
click node_subscriptions "https://github.com/returnfi/blitz/blob/main/core/scripts/normalsub/normalsub.py"
click node_nodes "https://github.com/returnfi/blitz/blob/main/core/scripts/nodes/node.py"
click node_telegram "https://github.com/returnfi/blitz/blob/main/core/scripts/telegrambot/runbot.py"
click node_warp "https://github.com/returnfi/blitz/blob/main/core/scripts/warp/warp.py"
click node_scheduler "https://github.com/returnfi/blitz/blob/main/core/scripts/scheduler.py"
click node_database "https://github.com/returnfi/blitz/blob/main/core/scripts/db/database.py"
click node_paths "https://github.com/returnfi/blitz/blob/main/core/scripts/paths.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_cli,node_cli_api toneBlue
class node_web_app,node_web_auth,node_sessions,node_web_config,node_web_deps,node_web_routes,node_hysteria_api,node_server_routes,node_user_routes toneAmber
class node_hysteria_ops,node_user_auth,node_traffic,node_subscriptions,node_nodes toneMint
class node_telegram,node_warp,node_scheduler toneRose
class node_database,node_paths,node_operator toneIndigo
```

## Components

### Operator Entry

- [Management CLI](https://github.com/returnfi/blitz/blob/main/core/cli.py): `core/cli.py`
- [CLI API](https://github.com/returnfi/blitz/blob/main/core/cli_api.py): `core/cli_api.py`

### WebPanel

- [Web Application](https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/app.py): `core/scripts/webpanel/app.py`
- [Authentication Middleware](https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/middleware/auth.py): `core/scripts/webpanel/middleware/auth.py`
- [Session Management](https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/session/session.py): `core/scripts/webpanel/session/session.py`
- [Web Configuration](https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/config/config.py): `core/scripts/webpanel/config/config.py`
- [Web Dependencies](https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/dependency/dependency.py): `core/scripts/webpanel/dependency/dependency.py`
- [Web Routes](https://github.com/returnfi/blitz/tree/main/core/scripts/webpanel/routers): `core/scripts/webpanel/routers`
- [Hysteria API Routes](https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/routers/api/v1/config/hysteria.py): `core/scripts/webpanel/routers/api/v1/config/hysteria.py`
- [Server API Routes](https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/routers/api/v1/server.py): `core/scripts/webpanel/routers/api/v1/server.py`
- [User Management Routes](https://github.com/returnfi/blitz/blob/main/core/scripts/webpanel/routers/user/user.py): `core/scripts/webpanel/routers/user/user.py`

### Proxy Management

- [Hysteria Operations](https://github.com/returnfi/blitz/tree/main/core/scripts/hysteria2): `core/scripts/hysteria2`
- [User Authentication](https://github.com/returnfi/blitz/blob/main/core/scripts/auth/user_auth.go): `core/scripts/auth/user_auth.go`
- [Traffic Accounting](https://github.com/returnfi/blitz/blob/main/core/traffic.py): `core/traffic.py`
- [Subscription Formats](https://github.com/returnfi/blitz/blob/main/core/scripts/normalsub/normalsub.py): `core/scripts/normalsub/normalsub.py`
- [Node Management](https://github.com/returnfi/blitz/blob/main/core/scripts/nodes/node.py): `core/scripts/nodes/node.py`

### Companion Services

- [Telegram Bot](https://github.com/returnfi/blitz/blob/main/core/scripts/telegrambot/runbot.py): `core/scripts/telegrambot/runbot.py`
- [WARP Integration](https://github.com/returnfi/blitz/blob/main/core/scripts/warp/warp.py): `core/scripts/warp/warp.py`
- [Scheduled Tasks](https://github.com/returnfi/blitz/blob/main/core/scripts/scheduler.py): `core/scripts/scheduler.py`

### Runtime State

- [User Database](https://github.com/returnfi/blitz/blob/main/core/scripts/db/database.py): `core/scripts/db/database.py`
- [Shared Paths](https://github.com/returnfi/blitz/blob/main/core/scripts/paths.py): `core/scripts/paths.py`

### Other components

- **Operator**

## Connections

- Operator → Management CLI: runs commands (evidence: `core/cli.py`)
- Management CLI → CLI API: delegates operations (evidence: `core/cli.py`)
- Web Application → Web Configuration: loads settings (evidence: `core/scripts/webpanel/app.py`)
- Web Application → Authentication Middleware: registers middleware (evidence: `core/scripts/webpanel/app.py`)
- Web Application → Web Dependencies: gets sessions (evidence: `core/scripts/webpanel/app.py`)
- Web Application → Web Routes: mounts routers (evidence: `core/scripts/webpanel/app.py`)
- Authentication Middleware → Session Management: validates sessions (evidence: `core/scripts/webpanel/middleware/auth.py`)
- Authentication Middleware → Web Configuration: checks settings (evidence: `core/scripts/webpanel/middleware/auth.py`)
- Web Dependencies → Session Management: creates manager (evidence: `core/scripts/webpanel/dependency/dependency.py`)
- Hysteria API Routes → CLI API: invokes operations (evidence: `core/scripts/webpanel/routers/api/v1/config/hysteria.py`)
- Server API Routes → CLI API: invokes operations (evidence: `core/scripts/webpanel/routers/api/v1/server.py`)
- Traffic Accounting → User Database: reads and updates (evidence: `core/traffic.py`)