How vannyratanak/pivpn-webui works
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: db.py Postgres state · privileged.py Privileged commands · routes.py Web routes · api.py API handlers
Components 28
Web interface
- Web routes
app/routes.py - API handlers
app/api.py - Client pages
app/static/js/clients-page.js - Firewall page
app/static/js/firewall-page.js - Logs page
app/static/js/logs-page.js - Overview page
app/static/js/overview-page.js - Users page
app/static/js/users-page.js - VPN routes page
app/static/js/vpn-routes-page.js
VPN management
- PiVPN control
app/pivpn_ctl.py - Firewall rules
app/firewall.py - Tunnel routes
app/vpn_routes.py
State and logs
- Postgres state
app/db.py - Log and session views
app/vpnlog.py - Client status ingest
deploy/ingest_clients.py - Log ingest
deploy/ingest_logs.py - IP organization lookup
app/iplookup.py
Remote operations
- Privileged commands
app/privileged.py - Hub socket client
app/hub_client.py - Agent gateway
hub_gateway.py - Remote agent
agent.py - Runtime configuration
config.py
Accounts and overview
- Authentication
app/auth.py - Overview service
app/overview.py - Health checks
app/overview_health.py - Overview notifications
app/overview_notify.py
Other components
- Admin / moderator
- PiVPN / host
- Browser
Connections 39
- Admin / moderator → Browser: uses
README.md - Browser → Web routes: requests pages
README.md - Web routes → PiVPN control: manages clients
app/routes.py - Web routes → Firewall rules: manages rules
app/routes.py - Web routes → Tunnel routes: manages routes
app/routes.py - Web routes → Postgres state: reads / writes
app/routes.py - Web routes → Authentication: checks access
app/routes.py - API handlers → Postgres state: reads / writes
app/api.py - API handlers → Firewall rules: manages rules
app/api.py - API handlers → PiVPN control: controls clients
app/api.py - API handlers → Tunnel routes: manages routes
app/api.py - API handlers → Authentication: checks access
app/api.py - PiVPN control → Privileged commands: runs commands
app/pivpn_ctl.py - Firewall rules → Postgres state: persists rules
app/firewall.py - Firewall rules → Privileged commands: applies rules
app/firewall.py - Tunnel routes → Privileged commands: runs helper
app/vpn_routes.py - Privileged commands → Hub socket client: dispatches remotely
app/privileged.py - Hub socket client → Agent gateway: sends requests
app/hub_client.py - Agent gateway → Remote agent: routes commands
hub_gateway.py - Remote agent → Privileged commands: runs commands
agent.py - Privileged commands → PiVPN / host: executes locally
app/privileged.py - Client status ingest → PiVPN control: fetches status
deploy/ingest_clients.py - Client status ingest → Postgres state: replaces cache
deploy/ingest_clients.py - Log ingest → Postgres state: stores events
deploy/ingest_logs.py - Log ingest → IP organization lookup: gets cached orgs
deploy/ingest_logs.py - Log and session views → Postgres state: reads log data
app/vpnlog.py - Overview service → Postgres state: reads state
app/overview.py - Overview service → Health checks: checks health
app/overview.py - Overview service → Log and session views: reads sessions
app/overview.py - Overview service → Hub socket client: queries hub
app/overview.py - Overview notifications → Postgres state: reads state
app/overview_notify.py - Authentication → Postgres state: loads accounts
app/auth.py - Client pages → Browser: renders client controls
README.md - Firewall page → Browser: renders rule controls
README.md - Logs page → Browser: renders log tabs
README.md - Overview page → Browser: renders overview
README.md - Users page → Browser: renders account controls
README.md - VPN routes page → Browser: renders route controls
README.md - Runtime configuration → Privileged commands: configures execution
app/privileged.py