# starsden/gate architecture

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

- Interactive diagram: https://gitdiagram.com/starsden/gate
- Repository: https://github.com/starsden/gate

## Overview

GATE turns a Linux mini-PC into a managed Wi-Fi VPN gateway. An administrator uses the web controller to complete onboarding and manage gateway services; Wi-Fi clients then receive DHCP/DNS and their traffic is filtered and policy-routed through the VLESS/REALITY tunnel, with a direct WAN route for the VPN server to prevent loops. The graph includes the documented data plane and major management capabilities. Several backend call relationships are supported by the SOURCE INDEX; unsampled frontend/API wiring is shown only as unverified.

Main entry points: [`backend/api.py`](https://github.com/starsden/gate/blob/main/backend/api.py) (REST and SSE API), [`backend/services/setup.py`](https://github.com/starsden/gate/blob/main/backend/services/setup.py) (Onboarding wizard), [`backend/services/diagnostics.py`](https://github.com/starsden/gate/blob/main/backend/services/diagnostics.py) (Diagnostics and repair), [`backend/services/vpn.py`](https://github.com/starsden/gate/blob/main/backend/services/vpn.py) (VLESS VPN service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Web control"]
  node_web["Web controller<br/>[app.js]"]
  node_app["FastAPI application<br/>[app.py]"]
  node_api["REST and SSE API<br/>[api.py]"]
end

subgraph group_onboarding["Setup and security"]
  node_setup["Onboarding wizard<br/>[setup.py]"]
  node_auth["Admin authentication<br/>[auth.py]"]
end

subgraph group_gateway["Gateway services"]
  node_wifi["Wi-Fi management<br/>[wifi.py]"]
  node_network["Network and routing<br/>[network.py]"]
  node_firewall["Firewall and NAT<br/>[firewall.py]"]
  node_vpn["VLESS VPN service<br/>[vpn.py]"]
  node_subscription["VPN subscriptions<br/>[subscription.py]"]
  node_clients["Connected clients<br/>[clients.py]"]
  node_system["System status<br/>[system.py]"]
end

subgraph group_operations["Health and recovery"]
  node_diagnostics["Diagnostics and repair<br/>[diagnostics.py]"]
  node_backups["Backup and rollback<br/>[backups.py]"]
  node_logs["Gateway logs<br/>[logs.py]"]
end

subgraph group_dataplane["Traffic data plane"]
  node_ap["Wi-Fi access point<br/>[hostapd.conf]"]
  node_dhcpdns["DHCP and DNS<br/>[dnsmasq.conf]"]
  node_nftables["nftables rules<br/>[nftables.conf]"]
  node_routing["Policy routing<br/>[network.py]"]
  node_tun["Xray TUN tunnel<br/>[vpn.py]"]
end

node_admin(("Administrator"))
node_devices(("Wi-Fi clients"))
node_wan(("WAN and Internet"))

node_admin -->|"manages"| node_web
node_web -.->|"uses API"| node_api
node_app -->|"registers router"| node_api
node_api -->|"routes setup"| node_setup
node_api -->|"routes authentication"| node_auth
node_api -->|"routes Wi-Fi"| node_wifi
node_api -->|"routes network"| node_network
node_api -->|"routes firewall"| node_firewall
node_api -->|"routes VPN"| node_vpn
node_api -->|"routes subscriptions"| node_subscription
node_api -->|"routes clients"| node_clients
node_api -->|"routes system"| node_system
node_api -->|"routes diagnostics"| node_diagnostics
node_api -->|"routes backups"| node_backups
node_api -->|"routes logs"| node_logs
node_setup -->|"configures Wi-Fi"| node_wifi
node_setup -->|"detects interfaces"| node_network
node_setup -->|"checks onboarding"| node_auth
node_setup -->|"configures VPN"| node_subscription
node_setup -->|"deploys firewall"| node_firewall
node_wifi -->|"counts clients"| node_clients
node_network -->|"reads VPN profile"| node_vpn
node_subscription -->|"updates VPN endpoint"| node_vpn
node_diagnostics -->|"checks and syncs routes"| node_network
node_diagnostics -->|"applies firewall"| node_firewall
node_diagnostics -->|"checks system"| node_system
node_diagnostics -->|"checks VPN"| node_vpn
node_backups -->|"restores configuration"| node_wifi
node_backups -->|"restores configuration"| node_vpn
node_backups -->|"reapplies rules"| node_firewall
node_devices -->|"connect over Wi-Fi"| node_ap
node_ap -->|"uses DHCP and DNS"| node_dhcpdns
node_dhcpdns -->|"serves LAN traffic"| node_nftables
node_nftables -->|"filters and NATs"| node_routing
node_routing -->|"routes LAN traffic"| node_tun
node_tun -->|"tunnels VLESS traffic"| node_wan
node_routing -->|"bypasses VPN server"| node_wan

click node_web "https://github.com/starsden/gate/blob/main/web/app.js"
click node_app "https://github.com/starsden/gate/blob/main/backend/app.py"
click node_api "https://github.com/starsden/gate/blob/main/backend/api.py"
click node_setup "https://github.com/starsden/gate/blob/main/backend/services/setup.py"
click node_auth "https://github.com/starsden/gate/blob/main/backend/services/auth.py"
click node_wifi "https://github.com/starsden/gate/blob/main/backend/services/wifi.py"
click node_network "https://github.com/starsden/gate/blob/main/backend/services/network.py"
click node_firewall "https://github.com/starsden/gate/blob/main/backend/services/firewall.py"
click node_vpn "https://github.com/starsden/gate/blob/main/backend/services/vpn.py"
click node_subscription "https://github.com/starsden/gate/blob/main/backend/services/subscription.py"
click node_clients "https://github.com/starsden/gate/blob/main/backend/services/clients.py"
click node_system "https://github.com/starsden/gate/blob/main/backend/services/system.py"
click node_diagnostics "https://github.com/starsden/gate/blob/main/backend/services/diagnostics.py"
click node_backups "https://github.com/starsden/gate/blob/main/backend/services/backups.py"
click node_logs "https://github.com/starsden/gate/blob/main/backend/services/logs.py"
click node_ap "https://github.com/starsden/gate/blob/main/configs/hostapd.conf"
click node_dhcpdns "https://github.com/starsden/gate/blob/main/configs/dnsmasq.conf"
click node_nftables "https://github.com/starsden/gate/blob/main/configs/nftables.conf"
click node_routing "https://github.com/starsden/gate/blob/main/backend/services/network.py"
click node_tun "https://github.com/starsden/gate/blob/main/backend/services/vpn.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,node_app,node_api,node_devices toneBlue
class node_setup,node_auth toneAmber
class node_wifi,node_network,node_firewall,node_vpn,node_subscription,node_clients,node_system toneMint
class node_diagnostics,node_backups,node_logs toneRose
class node_ap,node_dhcpdns,node_nftables,node_routing,node_tun,node_admin,node_wan toneIndigo
```

## Components

### Web control

- [Web controller](https://github.com/starsden/gate/blob/main/web/app.js): `web/app.js`
- [FastAPI application](https://github.com/starsden/gate/blob/main/backend/app.py): `backend/app.py`
- [REST and SSE API](https://github.com/starsden/gate/blob/main/backend/api.py): `backend/api.py`

### Setup and security

- [Onboarding wizard](https://github.com/starsden/gate/blob/main/backend/services/setup.py): `backend/services/setup.py`
- [Admin authentication](https://github.com/starsden/gate/blob/main/backend/services/auth.py): `backend/services/auth.py`

### Gateway services

- [Wi-Fi management](https://github.com/starsden/gate/blob/main/backend/services/wifi.py): `backend/services/wifi.py`
- [Network and routing](https://github.com/starsden/gate/blob/main/backend/services/network.py): `backend/services/network.py`
- [Firewall and NAT](https://github.com/starsden/gate/blob/main/backend/services/firewall.py): `backend/services/firewall.py`
- [VLESS VPN service](https://github.com/starsden/gate/blob/main/backend/services/vpn.py): `backend/services/vpn.py`
- [VPN subscriptions](https://github.com/starsden/gate/blob/main/backend/services/subscription.py): `backend/services/subscription.py`
- [Connected clients](https://github.com/starsden/gate/blob/main/backend/services/clients.py): `backend/services/clients.py`
- [System status](https://github.com/starsden/gate/blob/main/backend/services/system.py): `backend/services/system.py`

### Health and recovery

- [Diagnostics and repair](https://github.com/starsden/gate/blob/main/backend/services/diagnostics.py): `backend/services/diagnostics.py`
- [Backup and rollback](https://github.com/starsden/gate/blob/main/backend/services/backups.py): `backend/services/backups.py`
- [Gateway logs](https://github.com/starsden/gate/blob/main/backend/services/logs.py): `backend/services/logs.py`

### Traffic data plane

- [Wi-Fi access point](https://github.com/starsden/gate/blob/main/configs/hostapd.conf): `configs/hostapd.conf`
- [DHCP and DNS](https://github.com/starsden/gate/blob/main/configs/dnsmasq.conf): `configs/dnsmasq.conf`
- [nftables rules](https://github.com/starsden/gate/blob/main/configs/nftables.conf): `configs/nftables.conf`
- [Policy routing](https://github.com/starsden/gate/blob/main/backend/services/network.py): `backend/services/network.py`
- [Xray TUN tunnel](https://github.com/starsden/gate/blob/main/backend/services/vpn.py): `backend/services/vpn.py`

### Other components

- **Administrator**
- **Wi-Fi clients**
- **WAN and Internet**

## Connections

- Administrator → Web controller: manages (evidence: `README.md`)
- Web controller → REST and SSE API: uses API
- FastAPI application → REST and SSE API: registers router (evidence: `backend/app.py`)
- REST and SSE API → Onboarding wizard: routes setup (evidence: `backend/api.py`)
- REST and SSE API → Admin authentication: routes authentication (evidence: `backend/api.py`)
- REST and SSE API → Wi-Fi management: routes Wi-Fi (evidence: `backend/api.py`)
- REST and SSE API → Network and routing: routes network (evidence: `backend/api.py`)
- REST and SSE API → Firewall and NAT: routes firewall (evidence: `backend/api.py`)
- REST and SSE API → VLESS VPN service: routes VPN (evidence: `backend/api.py`)
- REST and SSE API → VPN subscriptions: routes subscriptions (evidence: `backend/api.py`)
- REST and SSE API → Connected clients: routes clients (evidence: `backend/api.py`)
- REST and SSE API → System status: routes system (evidence: `backend/api.py`)
- REST and SSE API → Diagnostics and repair: routes diagnostics (evidence: `backend/api.py`)
- REST and SSE API → Backup and rollback: routes backups (evidence: `backend/api.py`)
- REST and SSE API → Gateway logs: routes logs (evidence: `backend/api.py`)
- Onboarding wizard → Wi-Fi management: configures Wi-Fi (evidence: `backend/services/setup.py`)
- Onboarding wizard → Network and routing: detects interfaces (evidence: `backend/services/setup.py`)
- Onboarding wizard → Admin authentication: checks onboarding (evidence: `backend/services/setup.py`)
- Onboarding wizard → VPN subscriptions: configures VPN (evidence: `backend/services/setup.py`)
- Onboarding wizard → Firewall and NAT: deploys firewall (evidence: `backend/services/setup.py`)
- Wi-Fi management → Connected clients: counts clients (evidence: `backend/services/wifi.py`)
- Network and routing → VLESS VPN service: reads VPN profile (evidence: `backend/services/network.py`)
- VPN subscriptions → VLESS VPN service: updates VPN endpoint (evidence: `backend/services/subscription.py`)
- Diagnostics and repair → Network and routing: checks and syncs routes (evidence: `backend/services/diagnostics.py`)
- Diagnostics and repair → Firewall and NAT: applies firewall (evidence: `backend/services/diagnostics.py`)
- Diagnostics and repair → System status: checks system (evidence: `backend/services/diagnostics.py`)
- Diagnostics and repair → VLESS VPN service: checks VPN (evidence: `backend/services/diagnostics.py`)
- Backup and rollback → Wi-Fi management: restores configuration (evidence: `backend/services/backups.py`)
- Backup and rollback → VLESS VPN service: restores configuration (evidence: `backend/services/backups.py`)
- Backup and rollback → Firewall and NAT: reapplies rules (evidence: `backend/services/backups.py`)
- Wi-Fi clients → Wi-Fi access point: connect over Wi-Fi (evidence: `README.md`)
- Wi-Fi access point → DHCP and DNS: uses DHCP and DNS (evidence: `README.md`)
- DHCP and DNS → nftables rules: serves LAN traffic (evidence: `README.md`)
- nftables rules → Policy routing: filters and NATs (evidence: `README.md`)
- Policy routing → Xray TUN tunnel: routes LAN traffic (evidence: `README.md`)
- Xray TUN tunnel → WAN and Internet: tunnels VLESS traffic (evidence: `README.md`)
- Policy routing → WAN and Internet: bypasses VPN server (evidence: `README.md`)
