# vannyratanak/pivpn-webui architecture

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

- Interactive diagram: https://gitdiagram.com/vannyratanak/pivpn-webui
- Repository: https://github.com/vannyratanak/pivpn-webui

## Overview

PiVPN Web UI is a Flask administration panel for VPN clients, firewall/NAT rules, tunnel routes, logs, and user accounts. The principal workflow is an administrator or moderator using the browser UI, whose requests reach Flask routes or API handlers, invoke domain services, and persist or retrieve state in Postgres or through privileged PiVPN/system commands. Separate ingestion jobs cache client status and logs for the UI. The source index establishes several module dependencies, but many implementation details and frontend-to-endpoint mappings were not excerpted, so those relationships are omitted.

Main entry points: [`app/db.py`](https://github.com/vannyratanak/pivpn-webui/blob/main/app/db.py) (Postgres state), [`app/privileged.py`](https://github.com/vannyratanak/pivpn-webui/blob/main/app/privileged.py) (Privileged commands), [`app/routes.py`](https://github.com/vannyratanak/pivpn-webui/blob/main/app/routes.py) (Web routes), [`app/api.py`](https://github.com/vannyratanak/pivpn-webui/blob/main/app/api.py) (API handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web interface"]
  node_web_routes["Web routes<br/>[routes.py]"]
  node_api["API handlers<br/>[api.py]"]
  node_client_ui["Client pages<br/>[clients-page.js]"]
  node_firewall_ui["Firewall page<br/>[firewall-page.js]"]
  node_logs_ui["Logs page<br/>[logs-page.js]"]
  node_overview_ui["Overview page<br/>[overview-page.js]"]
  node_users_ui["Users page<br/>[users-page.js]"]
  node_routes_ui["VPN routes page<br/>[vpn-routes-page.js]"]
end

subgraph group_management["VPN management"]
  node_pivpn["PiVPN control<br/>[pivpn_ctl.py]"]
  node_firewall["Firewall rules<br/>[firewall.py]"]
  node_vpn_routes["Tunnel routes<br/>[vpn_routes.py]"]
end

subgraph group_state["State and logs"]
  node_database[("Postgres state<br/>[db.py]")]
  node_vpn_logs["Log and session views<br/>[vpnlog.py]"]
  node_client_ingest["Client status ingest<br/>[ingest_clients.py]"]
  node_log_ingest["Log ingest<br/>[ingest_logs.py]"]
  node_iplookup["IP organization lookup<br/>[iplookup.py]"]
end

subgraph group_operations["Remote operations"]
  node_privileged["Privileged commands<br/>[privileged.py]"]
  node_hub_client["Hub socket client<br/>[hub_client.py]"]
  node_gateway["Agent gateway<br/>[hub_gateway.py]"]
  node_agent["Remote agent<br/>[agent.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_identity["Accounts and overview"]
  node_auth["Authentication<br/>[auth.py]"]
  node_overview["Overview service<br/>[overview.py]"]
  node_health["Health checks<br/>[overview_health.py]"]
  node_notify["Overview notifications<br/>[overview_notify.py]"]
end

node_admin(("Admin / moderator"))
node_pivpn_system{{"PiVPN / host"}}
node_browser(("Browser"))

node_admin -->|"uses"| node_browser
node_browser -->|"requests pages"| node_web_routes
node_web_routes -->|"manages clients"| node_pivpn
node_web_routes -->|"manages rules"| node_firewall
node_web_routes -->|"manages routes"| node_vpn_routes
node_web_routes -->|"reads / writes"| node_database
node_web_routes -->|"checks access"| node_auth
node_api -->|"reads / writes"| node_database
node_api -->|"manages rules"| node_firewall
node_api -->|"controls clients"| node_pivpn
node_api -->|"manages routes"| node_vpn_routes
node_api -->|"checks access"| node_auth
node_pivpn -->|"runs commands"| node_privileged
node_firewall -->|"persists rules"| node_database
node_firewall -->|"applies rules"| node_privileged
node_vpn_routes -->|"runs helper"| node_privileged
node_privileged -->|"dispatches remotely"| node_hub_client
node_hub_client -->|"sends requests"| node_gateway
node_gateway -->|"routes commands"| node_agent
node_agent -->|"runs commands"| node_privileged
node_privileged -->|"executes locally"| node_pivpn_system
node_client_ingest -->|"fetches status"| node_pivpn
node_client_ingest -->|"replaces cache"| node_database
node_log_ingest -->|"stores events"| node_database
node_log_ingest -->|"gets cached orgs"| node_iplookup
node_vpn_logs -->|"reads log data"| node_database
node_overview -->|"reads state"| node_database
node_overview -->|"checks health"| node_health
node_overview -->|"reads sessions"| node_vpn_logs
node_overview -->|"queries hub"| node_hub_client
node_notify -->|"reads state"| node_database
node_auth -->|"loads accounts"| node_database
node_client_ui -->|"renders client controls"| node_browser
node_firewall_ui -->|"renders rule controls"| node_browser
node_logs_ui -->|"renders log tabs"| node_browser
node_overview_ui -->|"renders overview"| node_browser
node_users_ui -->|"renders account controls"| node_browser
node_routes_ui -->|"renders route controls"| node_browser
node_config -->|"configures execution"| node_privileged

click node_web_routes "https://github.com/vannyratanak/pivpn-webui/blob/main/app/routes.py"
click node_api "https://github.com/vannyratanak/pivpn-webui/blob/main/app/api.py"
click node_client_ui "https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/clients-page.js"
click node_firewall_ui "https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/firewall-page.js"
click node_logs_ui "https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/logs-page.js"
click node_overview_ui "https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/overview-page.js"
click node_users_ui "https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/users-page.js"
click node_routes_ui "https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/vpn-routes-page.js"
click node_pivpn "https://github.com/vannyratanak/pivpn-webui/blob/main/app/pivpn_ctl.py"
click node_firewall "https://github.com/vannyratanak/pivpn-webui/blob/main/app/firewall.py"
click node_vpn_routes "https://github.com/vannyratanak/pivpn-webui/blob/main/app/vpn_routes.py"
click node_auth "https://github.com/vannyratanak/pivpn-webui/blob/main/app/auth.py"
click node_overview "https://github.com/vannyratanak/pivpn-webui/blob/main/app/overview.py"
click node_health "https://github.com/vannyratanak/pivpn-webui/blob/main/app/overview_health.py"
click node_notify "https://github.com/vannyratanak/pivpn-webui/blob/main/app/overview_notify.py"
click node_database "https://github.com/vannyratanak/pivpn-webui/blob/main/app/db.py"
click node_vpn_logs "https://github.com/vannyratanak/pivpn-webui/blob/main/app/vpnlog.py"
click node_client_ingest "https://github.com/vannyratanak/pivpn-webui/blob/main/deploy/ingest_clients.py"
click node_log_ingest "https://github.com/vannyratanak/pivpn-webui/blob/main/deploy/ingest_logs.py"
click node_iplookup "https://github.com/vannyratanak/pivpn-webui/blob/main/app/iplookup.py"
click node_privileged "https://github.com/vannyratanak/pivpn-webui/blob/main/app/privileged.py"
click node_hub_client "https://github.com/vannyratanak/pivpn-webui/blob/main/app/hub_client.py"
click node_gateway "https://github.com/vannyratanak/pivpn-webui/blob/main/hub_gateway.py"
click node_agent "https://github.com/vannyratanak/pivpn-webui/blob/main/agent.py"
click node_config "https://github.com/vannyratanak/pivpn-webui/blob/main/config.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_web_routes,node_api,node_client_ui,node_firewall_ui,node_logs_ui,node_overview_ui,node_users_ui,node_routes_ui,node_browser toneBlue
class node_pivpn,node_firewall,node_vpn_routes toneAmber
class node_database,node_vpn_logs,node_client_ingest,node_log_ingest,node_iplookup toneMint
class node_privileged,node_hub_client,node_gateway,node_agent,node_config toneRose
class node_auth,node_overview,node_health,node_notify,node_admin,node_pivpn_system toneIndigo
```

## Components

### Web interface

- [Web routes](https://github.com/vannyratanak/pivpn-webui/blob/main/app/routes.py): `app/routes.py`
- [API handlers](https://github.com/vannyratanak/pivpn-webui/blob/main/app/api.py): `app/api.py`
- [Client pages](https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/clients-page.js): `app/static/js/clients-page.js`
- [Firewall page](https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/firewall-page.js): `app/static/js/firewall-page.js`
- [Logs page](https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/logs-page.js): `app/static/js/logs-page.js`
- [Overview page](https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/overview-page.js): `app/static/js/overview-page.js`
- [Users page](https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/users-page.js): `app/static/js/users-page.js`
- [VPN routes page](https://github.com/vannyratanak/pivpn-webui/blob/main/app/static/js/vpn-routes-page.js): `app/static/js/vpn-routes-page.js`

### VPN management

- [PiVPN control](https://github.com/vannyratanak/pivpn-webui/blob/main/app/pivpn_ctl.py): `app/pivpn_ctl.py`
- [Firewall rules](https://github.com/vannyratanak/pivpn-webui/blob/main/app/firewall.py): `app/firewall.py`
- [Tunnel routes](https://github.com/vannyratanak/pivpn-webui/blob/main/app/vpn_routes.py): `app/vpn_routes.py`

### State and logs

- [Postgres state](https://github.com/vannyratanak/pivpn-webui/blob/main/app/db.py): `app/db.py`
- [Log and session views](https://github.com/vannyratanak/pivpn-webui/blob/main/app/vpnlog.py): `app/vpnlog.py`
- [Client status ingest](https://github.com/vannyratanak/pivpn-webui/blob/main/deploy/ingest_clients.py): `deploy/ingest_clients.py`
- [Log ingest](https://github.com/vannyratanak/pivpn-webui/blob/main/deploy/ingest_logs.py): `deploy/ingest_logs.py`
- [IP organization lookup](https://github.com/vannyratanak/pivpn-webui/blob/main/app/iplookup.py): `app/iplookup.py`

### Remote operations

- [Privileged commands](https://github.com/vannyratanak/pivpn-webui/blob/main/app/privileged.py): `app/privileged.py`
- [Hub socket client](https://github.com/vannyratanak/pivpn-webui/blob/main/app/hub_client.py): `app/hub_client.py`
- [Agent gateway](https://github.com/vannyratanak/pivpn-webui/blob/main/hub_gateway.py): `hub_gateway.py`
- [Remote agent](https://github.com/vannyratanak/pivpn-webui/blob/main/agent.py): `agent.py`
- [Runtime configuration](https://github.com/vannyratanak/pivpn-webui/blob/main/config.py): `config.py`

### Accounts and overview

- [Authentication](https://github.com/vannyratanak/pivpn-webui/blob/main/app/auth.py): `app/auth.py`
- [Overview service](https://github.com/vannyratanak/pivpn-webui/blob/main/app/overview.py): `app/overview.py`
- [Health checks](https://github.com/vannyratanak/pivpn-webui/blob/main/app/overview_health.py): `app/overview_health.py`
- [Overview notifications](https://github.com/vannyratanak/pivpn-webui/blob/main/app/overview_notify.py): `app/overview_notify.py`

### Other components

- **Admin / moderator**
- **PiVPN / host**
- **Browser**

## Connections

- Admin / moderator → Browser: uses (evidence: `README.md`)
- Browser → Web routes: requests pages (evidence: `README.md`)
- Web routes → PiVPN control: manages clients (evidence: `app/routes.py`)
- Web routes → Firewall rules: manages rules (evidence: `app/routes.py`)
- Web routes → Tunnel routes: manages routes (evidence: `app/routes.py`)
- Web routes → Postgres state: reads / writes (evidence: `app/routes.py`)
- Web routes → Authentication: checks access (evidence: `app/routes.py`)
- API handlers → Postgres state: reads / writes (evidence: `app/api.py`)
- API handlers → Firewall rules: manages rules (evidence: `app/api.py`)
- API handlers → PiVPN control: controls clients (evidence: `app/api.py`)
- API handlers → Tunnel routes: manages routes (evidence: `app/api.py`)
- API handlers → Authentication: checks access (evidence: `app/api.py`)
- PiVPN control → Privileged commands: runs commands (evidence: `app/pivpn_ctl.py`)
- Firewall rules → Postgres state: persists rules (evidence: `app/firewall.py`)
- Firewall rules → Privileged commands: applies rules (evidence: `app/firewall.py`)
- Tunnel routes → Privileged commands: runs helper (evidence: `app/vpn_routes.py`)
- Privileged commands → Hub socket client: dispatches remotely (evidence: `app/privileged.py`)
- Hub socket client → Agent gateway: sends requests (evidence: `app/hub_client.py`)
- Agent gateway → Remote agent: routes commands (evidence: `hub_gateway.py`)
- Remote agent → Privileged commands: runs commands (evidence: `agent.py`)
- Privileged commands → PiVPN / host: executes locally (evidence: `app/privileged.py`)
- Client status ingest → PiVPN control: fetches status (evidence: `deploy/ingest_clients.py`)
- Client status ingest → Postgres state: replaces cache (evidence: `deploy/ingest_clients.py`)
- Log ingest → Postgres state: stores events (evidence: `deploy/ingest_logs.py`)
- Log ingest → IP organization lookup: gets cached orgs (evidence: `deploy/ingest_logs.py`)
- Log and session views → Postgres state: reads log data (evidence: `app/vpnlog.py`)
- Overview service → Postgres state: reads state (evidence: `app/overview.py`)
- Overview service → Health checks: checks health (evidence: `app/overview.py`)
- Overview service → Log and session views: reads sessions (evidence: `app/overview.py`)
- Overview service → Hub socket client: queries hub (evidence: `app/overview.py`)
- Overview notifications → Postgres state: reads state (evidence: `app/overview_notify.py`)
- Authentication → Postgres state: loads accounts (evidence: `app/auth.py`)
- Client pages → Browser: renders client controls (evidence: `README.md`)
- Firewall page → Browser: renders rule controls (evidence: `README.md`)
- Logs page → Browser: renders log tabs (evidence: `README.md`)
- Overview page → Browser: renders overview (evidence: `README.md`)
- Users page → Browser: renders account controls (evidence: `README.md`)
- VPN routes page → Browser: renders route controls (evidence: `README.md`)
- Runtime configuration → Privileged commands: configures execution (evidence: `app/privileged.py`)
