# wangtian1530/acdv-wifi-captive-potla architecture

> Architecture diagram of the GitHub repository wangtian1530/acdv-wifi-captive-potla, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wangtian1530/acdv-wifi-captive-potla
- Repository: https://github.com/wangtian1530/acdv-wifi-captive-potla

## Overview

ACDV is a Linux Wi-Fi captive portal that grants guest Internet access through time- or data-based vouchers, then monitors sessions and revokes access when they expire. Guests activate vouchers by code or QR and view status; administrators manage vouchers, devices, reports, and chat. HTTP and WebSocket services expose these workflows, while background traffic accounting maintains data balances. The README documents the major capabilities; some implementation details and route wiring are not visible in the sampled excerpts, so those links cite the README rather than implying source inspection.

Main entry points: [`backend/server.py`](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/server.py) (HTTP API), [`backend/portal.py`](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/portal.py) (Portal operations), [`main.py`](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/main.py) (Application startup), [`backend/wsserver.py`](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/wsserver.py) (Realtime WebSocket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Portal interfaces"]
  node_http["HTTP API<br/>[server.py]"]
  node_ws["Realtime WebSocket<br/>[wsserver.py]"]
  node_guest_ui["Guest interface<br/>[app.js]"]
  node_admin_ui["Admin interface<br/>[admin.js]"]
end

subgraph group_domain["Voucher and session domain"]
  node_portal["Portal operations<br/>[portal.py]"]
  node_auth["Admin sessions<br/>[auth.py]"]
end

subgraph group_network["Network access and accounting"]
  node_main["Application startup<br/>[main.py]"]
  node_data_bot["Traffic accounting bot<br/>[data_bot2.py]"]
  node_network_probe["Network discovery<br/>[network.py]"]
  node_firewall_control["Firewall control<br/>[nft.py]"]
end

subgraph group_persistence["State and configuration"]
  node_voucher_config["Voucher packages<br/>[config.py]"]
  node_json_store[("Voucher / session JSON<br/>[data.py]")]
  node_chat_store[("Chat history<br/>[chat_store.py]")]
  node_ip_store[("Per-IP data records<br/>[ip_data.py]")]
  node_cache["Runtime cache<br/>[cache.py]"]
end

node_guest(("Wi-Fi guest"))
node_admin(("Administrator"))
node_gateway["AP / gateway"]
node_internet(("Internet"))
node_firewall["nftables / iptables"]

node_guest -->|"uses"| node_guest_ui
node_admin -->|"uses"| node_admin_ui
node_guest_ui -->|"HTTP requests"| node_http
node_guest_ui -->|"realtime updates"| node_ws
node_admin_ui -->|"HTTP requests"| node_http
node_admin_ui -->|"realtime updates"| node_ws
node_gateway -->|"redirects traffic"| node_http
node_http -->|"routes operations"| node_portal
node_http -->|"checks sessions"| node_auth
node_ws -->|"runs operations"| node_portal
node_ws -->|"reads and writes"| node_chat_store
node_portal -->|"loads and saves"| node_json_store
node_portal -->|"manages data packages"| node_ip_store
node_portal -->|"grants or revokes"| node_firewall_control
node_portal -->|"uses package rules"| node_voucher_config
node_main -->|"starts server"| node_http
node_main -->|"starts server"| node_ws
node_main -->|"starts task"| node_data_bot
node_main -->|"loads active state"| node_json_store
node_main -->|"syncs active IPs"| node_firewall_control
node_data_bot -->|"reads traffic counters"| node_network_probe
node_data_bot -->|"applies traffic deltas"| node_ip_store
node_data_bot -->|"revokes exhausted IPs"| node_firewall_control
node_firewall_control -->|"updates rules"| node_firewall
node_network_probe -->|"reads counters"| node_firewall
node_firewall -->|"permits forwarding"| node_internet
node_http -->|"serves dashboard data"| node_json_store

click node_http "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/server.py"
click node_ws "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/wsserver.py"
click node_guest_ui "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/frontend/static/app.js"
click node_admin_ui "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/frontend/static/admin.js"
click node_portal "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/portal.py"
click node_auth "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/auth.py"
click node_voucher_config "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/config.py"
click node_json_store "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/data.py"
click node_chat_store "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/chat_store.py"
click node_ip_store "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/ip_data.py"
click node_cache "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/cache.py"
click node_main "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/main.py"
click node_data_bot "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/data_bot2.py"
click node_network_probe "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/network.py"
click node_firewall_control "https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/nft.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_http,node_ws,node_guest_ui,node_admin_ui toneBlue
class node_portal,node_auth toneAmber
class node_main,node_data_bot,node_network_probe,node_firewall_control toneMint
class node_voucher_config,node_json_store,node_chat_store,node_ip_store,node_cache toneRose
class node_guest,node_admin,node_gateway,node_internet,node_firewall toneIndigo
```

## Components

### Portal interfaces

- [HTTP API](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/server.py): `backend/server.py`
- [Realtime WebSocket](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/wsserver.py): `backend/wsserver.py`
- [Guest interface](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/frontend/static/app.js): `frontend/static/app.js`
- [Admin interface](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/frontend/static/admin.js): `frontend/static/admin.js`

### Voucher and session domain

- [Portal operations](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/portal.py): `backend/portal.py`
- [Admin sessions](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/auth.py): `backend/auth.py`

### Network access and accounting

- [Application startup](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/main.py): `main.py`
- [Traffic accounting bot](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/data_bot2.py): `backend/data_bot2.py`
- [Network discovery](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/network.py): `backend/network.py`
- [Firewall control](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/nft.py): `backend/nft.py`

### State and configuration

- [Voucher packages](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/config.py): `backend/config.py`
- [Voucher / session JSON](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/data.py): `backend/data.py`
- [Chat history](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/chat_store.py): `backend/chat_store.py`
- [Per-IP data records](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/ip_data.py): `backend/ip_data.py`
- [Runtime cache](https://github.com/wangtian1530/acdv-wifi-captive-potla/blob/main/backend/cache.py): `backend/cache.py`

### Other components

- **Wi-Fi guest**
- **Administrator**
- **AP / gateway**
- **Internet**
- **nftables / iptables**

## Connections

- Wi-Fi guest → Guest interface: uses (evidence: `README.md`)
- Administrator → Admin interface: uses (evidence: `README.md`)
- Guest interface → HTTP API: HTTP requests (evidence: `README.md`)
- Guest interface → Realtime WebSocket: realtime updates (evidence: `README.md`)
- Admin interface → HTTP API: HTTP requests (evidence: `README.md`)
- Admin interface → Realtime WebSocket: realtime updates (evidence: `README.md`)
- AP / gateway → HTTP API: redirects traffic (evidence: `README.md`)
- HTTP API → Portal operations: routes operations (evidence: `backend/server.py`)
- HTTP API → Admin sessions: checks sessions (evidence: `backend/server.py`)
- Realtime WebSocket → Portal operations: runs operations (evidence: `backend/wsserver.py`)
- Realtime WebSocket → Chat history: reads and writes (evidence: `backend/wsserver.py`)
- Portal operations → Voucher / session JSON: loads and saves (evidence: `backend/portal.py`)
- Portal operations → Per-IP data records: manages data packages (evidence: `backend/portal.py`)
- Portal operations → Firewall control: grants or revokes (evidence: `backend/portal.py`)
- Portal operations → Voucher packages: uses package rules (evidence: `backend/portal.py`)
- Application startup → HTTP API: starts server (evidence: `main.py`)
- Application startup → Realtime WebSocket: starts server (evidence: `main.py`)
- Application startup → Traffic accounting bot: starts task (evidence: `main.py`)
- Application startup → Voucher / session JSON: loads active state (evidence: `main.py`)
- Application startup → Firewall control: syncs active IPs (evidence: `README.md`)
- Traffic accounting bot → Network discovery: reads traffic counters (evidence: `backend/data_bot2.py`)
- Traffic accounting bot → Per-IP data records: applies traffic deltas (evidence: `backend/data_bot2.py`)
- Traffic accounting bot → Firewall control: revokes exhausted IPs (evidence: `README.md`)
- Firewall control → nftables / iptables: updates rules (evidence: `backend/nft.py`)
- Network discovery → nftables / iptables: reads counters (evidence: `backend/network.py`)
- nftables / iptables → Internet: permits forwarding (evidence: `README.md`)
- HTTP API → Voucher / session JSON: serves dashboard data (evidence: `README.md`)
