# okdunli/windows-hotspot-butler architecture

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

- Interactive diagram: https://gitdiagram.com/okdunli/windows-hotspot-butler
- Repository: https://github.com/okdunli/windows-hotspot-butler

## Overview

Windows Hotspot Butler is a Windows hotspot-management desktop application. The primary workflow runs from the user interface through the web backend to hotspot control, then gathers client and traffic data for device views and reporting. Separate capabilities provide guest access through a captive portal and LAN utilities such as file sharing and port forwarding. The graph also shows shared configuration, persistence, and Windows command layers. Source excerpts and the SOURCE INDEX support the listed links; several feature internals were not sampled, so their detailed interactions are omitted.

Main entry points: [`hotspot/webui/backend.py`](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/webui/backend.py) (Web backend), [`hotspot/core/hotspot.py`](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/hotspot.py) (Hotspot controller), [`hotspot/core/deviceman.py`](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/deviceman.py) (Device manager), [`hotspot/webui/app.py`](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/webui/app.py) (Web UI host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_main["Application entry<br/>[main.py]"]
  node_webapp["Web UI host<br/>[app.py]"]
  node_webfront["Web UI<br/>[app.js]"]
  node_webbackend["Web backend<br/>[backend.py]"]
  node_legacyui["Tk interface<br/>[app.py]"]
  node_tray["Tray and hotkey<br/>[tray.py]"]
end

subgraph group_hotspot["Hotspot control"]
  node_hotspotctl["Hotspot controller<br/>[hotspot.py]"]
  node_wificaps["Wi-Fi capabilities<br/>[wificaps.py]"]
  node_netinfo["Network information<br/>[netinfo.py]"]
  node_pshell["Windows commands<br/>[pshell.py]"]
end

subgraph group_clients["Client and traffic management"]
  node_devman["Device manager<br/>[deviceman.py]"]
  node_traffic["Traffic accounting<br/>[traffic.py]"]
  node_storage[("Profiles and history<br/>[storage.py]")]
  node_oui["Device identification<br/>[oui.py]"]
end

subgraph group_guest["Guest access"]
  node_portal["Captive portal<br/>[portal.py]"]
  node_captive["DNS interception<br/>[captive.py]"]
  node_templates["Welcome templates"]
end

subgraph group_utilities["LAN utilities and settings"]
  node_config["Configuration<br/>[config.py]"]
  node_sharing["LAN file sharing<br/>[share.py]"]
  node_forwarding["Port forwarding<br/>[portforward.py]"]
  node_speedtest["Download speed test<br/>[speedtest.py]"]
end

node_user(("User"))

node_user -->|"starts"| node_main
node_main -->|"launches"| node_webapp
node_main -->|"launches fallback"| node_legacyui
node_webapp -->|"hosts"| node_webbackend
node_webapp -->|"sets up"| node_tray
node_webfront -.->|"requests state and actions"| node_webbackend
node_webbackend -->|"controls"| node_hotspotctl
node_webbackend -->|"manages clients"| node_devman
node_webbackend -->|"reads and exports"| node_traffic
node_webbackend -->|"manages access"| node_portal
node_webbackend -->|"configures interception"| node_captive
node_webbackend -->|"controls"| node_sharing
node_webbackend -->|"controls"| node_forwarding
node_webbackend -->|"runs"| node_speedtest
node_hotspotctl -->|"detects capabilities"| node_wificaps
node_hotspotctl -->|"runs commands"| node_pshell
node_hotspotctl -->|"reads adapter info"| node_netinfo
node_devman -->|"merges network data"| node_netinfo
node_devman -->|"identifies vendors"| node_oui
node_devman -->|"reads and updates profiles"| node_storage
node_devman -->|"uses traffic data"| node_traffic
node_traffic -->|"persists accounting"| node_storage
node_portal -->|"records acceptances"| node_storage
node_portal -->|"renders"| node_templates
node_captive -->|"routes guests"| node_portal
node_sharing -->|"serves LAN files"| node_user
node_forwarding -->|"configures portproxy"| node_pshell
node_hotspotctl -->|"uses settings"| node_config
node_webapp -->|"loads UI settings"| node_config

click node_main "https://github.com/okdunli/windows-hotspot-butler/blob/main/main.py"
click node_webapp "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/webui/app.py"
click node_webfront "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/webui/ui/app.js"
click node_webbackend "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/webui/backend.py"
click node_legacyui "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/ui/app.py"
click node_hotspotctl "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/hotspot.py"
click node_wificaps "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/wificaps.py"
click node_netinfo "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/netinfo.py"
click node_pshell "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/pshell.py"
click node_devman "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/deviceman.py"
click node_traffic "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/traffic.py"
click node_storage "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/storage.py"
click node_oui "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/oui.py"
click node_portal "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/portal.py"
click node_captive "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/captive.py"
click node_templates "https://github.com/okdunli/windows-hotspot-butler/tree/main/hotspot/templates"
click node_config "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/config.py"
click node_sharing "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/share.py"
click node_forwarding "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/portforward.py"
click node_speedtest "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/speedtest.py"
click node_tray "https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/webui/tray.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_main,node_webapp,node_webfront,node_webbackend,node_legacyui,node_tray,node_user toneBlue
class node_hotspotctl,node_wificaps,node_netinfo,node_pshell toneAmber
class node_devman,node_traffic,node_storage,node_oui toneMint
class node_portal,node_captive,node_templates toneRose
class node_config,node_sharing,node_forwarding,node_speedtest toneIndigo
```

## Components

### User interfaces

- [Application entry](https://github.com/okdunli/windows-hotspot-butler/blob/main/main.py): `main.py`
- [Web UI host](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/webui/app.py): `hotspot/webui/app.py`
- [Web UI](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/webui/ui/app.js): `hotspot/webui/ui/app.js`
- [Web backend](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/webui/backend.py): `hotspot/webui/backend.py`
- [Tk interface](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/ui/app.py): `hotspot/ui/app.py`
- [Tray and hotkey](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/webui/tray.py): `hotspot/webui/tray.py`

### Hotspot control

- [Hotspot controller](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/hotspot.py): `hotspot/core/hotspot.py`
- [Wi-Fi capabilities](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/wificaps.py): `hotspot/core/wificaps.py`
- [Network information](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/netinfo.py): `hotspot/core/netinfo.py`
- [Windows commands](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/pshell.py): `hotspot/core/pshell.py`

### Client and traffic management

- [Device manager](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/deviceman.py): `hotspot/core/deviceman.py`
- [Traffic accounting](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/traffic.py): `hotspot/core/traffic.py`
- [Profiles and history](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/storage.py): `hotspot/core/storage.py`
- [Device identification](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/oui.py): `hotspot/core/oui.py`

### Guest access

- [Captive portal](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/portal.py): `hotspot/core/portal.py`
- [DNS interception](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/captive.py): `hotspot/core/captive.py`
- [Welcome templates](https://github.com/okdunli/windows-hotspot-butler/tree/main/hotspot/templates): `hotspot/templates`

### LAN utilities and settings

- [Configuration](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/config.py): `hotspot/core/config.py`
- [LAN file sharing](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/share.py): `hotspot/core/share.py`
- [Port forwarding](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/portforward.py): `hotspot/core/portforward.py`
- [Download speed test](https://github.com/okdunli/windows-hotspot-butler/blob/main/hotspot/core/speedtest.py): `hotspot/core/speedtest.py`

### Other components

- **User**

## Connections

- User → Application entry: starts (evidence: `README.md`)
- Application entry → Web UI host: launches (evidence: `main.py`)
- Application entry → Tk interface: launches fallback (evidence: `README.md`)
- Web UI host → Web backend: hosts (evidence: `hotspot/webui/app.py`)
- Web UI host → Tray and hotkey: sets up (evidence: `hotspot/webui/app.py`)
- Web UI → Web backend: requests state and actions
- Web backend → Hotspot controller: controls (evidence: `hotspot/webui/backend.py`)
- Web backend → Device manager: manages clients (evidence: `hotspot/webui/backend.py`)
- Web backend → Traffic accounting: reads and exports (evidence: `hotspot/webui/backend.py`)
- Web backend → Captive portal: manages access (evidence: `hotspot/webui/backend.py`)
- Web backend → DNS interception: configures interception (evidence: `hotspot/webui/backend.py`)
- Web backend → LAN file sharing: controls (evidence: `hotspot/webui/backend.py`)
- Web backend → Port forwarding: controls (evidence: `hotspot/webui/backend.py`)
- Web backend → Download speed test: runs (evidence: `hotspot/webui/backend.py`)
- Hotspot controller → Wi-Fi capabilities: detects capabilities (evidence: `hotspot/core/hotspot.py`)
- Hotspot controller → Windows commands: runs commands (evidence: `hotspot/core/hotspot.py`)
- Hotspot controller → Network information: reads adapter info (evidence: `hotspot/core/hotspot.py`)
- Device manager → Network information: merges network data (evidence: `hotspot/core/deviceman.py`)
- Device manager → Device identification: identifies vendors (evidence: `hotspot/core/deviceman.py`)
- Device manager → Profiles and history: reads and updates profiles (evidence: `hotspot/core/deviceman.py`)
- Device manager → Traffic accounting: uses traffic data (evidence: `hotspot/core/deviceman.py`)
- Traffic accounting → Profiles and history: persists accounting (evidence: `hotspot/core/traffic.py`)
- Captive portal → Profiles and history: records acceptances (evidence: `hotspot/core/portal.py`)
- Captive portal → Welcome templates: renders (evidence: `README.md`)
- DNS interception → Captive portal: routes guests (evidence: `hotspot/core/captive.py`)
- LAN file sharing → User: serves LAN files (evidence: `README.md`)
- Port forwarding → Windows commands: configures portproxy (evidence: `hotspot/core/portforward.py`)
- Hotspot controller → Configuration: uses settings (evidence: `hotspot/core/hotspot.py`)
- Web UI host → Configuration: loads UI settings (evidence: `hotspot/webui/app.py`)
