# krotrn/apsta architecture

> Architecture diagram of the GitHub repository krotrn/apsta, 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/krotrn/apsta
- Repository: https://github.com/krotrn/apsta

## Overview

apsta is a Linux AP+STA Wi-Fi hotspot manager, exposed through a CLI and GTK desktop app. The main workflow is to inspect Wi-Fi hardware and channel constraints, resolve configuration into a hotspot method, apply network changes, and persist runtime state so the hotspot can be inspected and stopped. The README also documents client controls, boot/resume recovery, QR sharing, and a GUI. Several relationships below are supported by README statements; unsampled modules are represented only at their documented subsystem level.

Main entry points: [`apsta_cli/services/hotspot.py`](https://github.com/krotrn/apsta/blob/main/apsta_cli/services/hotspot.py) (Hotspot lifecycle), [`apsta_cli/cli.py`](https://github.com/krotrn/apsta/blob/main/apsta_cli/cli.py) (CLI router), [`apsta_cli/cmd/detect.py`](https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/detect.py) (Hardware detection), [`apsta_cli/cmd/clients.py`](https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/clients.py) (Client commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI router<br/>[cli.py]"]
  node_config_cmd["Config and profiles<br/>[config.py]"]
  node_detect_cmd["Hardware detection<br/>[detect.py]"]
  node_hotspot_cmd["Hotspot commands<br/>[hotspot.py]"]
  node_status_cmd["Status and QR<br/>[status.py]"]
  node_client_cmd["Client commands<br/>[clients.py]"]
end

subgraph group_setup["Configuration and detection"]
  node_config[("Config store<br/>[store.py]")]
  node_validation["Config model<br/>[model.py]"]
  node_interfaces["Wi-Fi interfaces<br/>[interfaces.py]"]
  node_capability["Radio capability<br/>[capability.py]"]
  node_channels["Channel planning<br/>[channels.py]"]
end

subgraph group_network["Hotspot networking"]
  node_hotspot["Hotspot lifecycle<br/>[hotspot.py]"]
  node_strategies["Method strategies<br/>[strategies.py]"]
  node_network_services["Network setup"]
end

subgraph group_runtime["Runtime management"]
  node_state[("Runtime state<br/>[state.py]")]
  node_watcher["Recovery watcher<br/>[watch.py]"]
  node_autostart["Boot integration<br/>[autostart.py]"]
  node_clients["Client management<br/>[clients.py]"]
end

subgraph group_desktop["Desktop app"]
  node_gui_app["GTK application<br/>[app.py]"]
  node_gui_backend["GUI backend<br/>[backend.py]"]
  node_gui_pages["GUI pages"]
  node_gui_compat["GTK compatibility<br/>[compat.py]"]
end

node_user(("User"))
node_system{{"Linux networking"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"routes hotspot"| node_hotspot_cmd
node_cli -->|"routes detect"| node_detect_cmd
node_cli -->|"routes config"| node_config_cmd
node_cli -.->|"routes status"| node_status_cmd
node_cli -->|"routes clients"| node_client_cmd
node_config_cmd -.->|"reads and writes"| node_config
node_config -->|"validates fields"| node_validation
node_detect_cmd -->|"checks capability"| node_capability
node_detect_cmd -->|"lists interfaces"| node_interfaces
node_capability -->|"inspects radios"| node_interfaces
node_hotspot_cmd -.->|"starts or stops"| node_hotspot
node_hotspot -->|"loads settings"| node_config
node_hotspot -->|"selects interface"| node_interfaces
node_hotspot -->|"checks support"| node_capability
node_hotspot -->|"plans channel"| node_channels
node_hotspot -->|"tries methods"| node_strategies
node_strategies -->|"configures networking"| node_network_services
node_network_services -->|"applies changes"| node_system
node_hotspot -->|"saves result"| node_state
node_status_cmd -.->|"gets status"| node_hotspot
node_watcher -->|"recovers hotspot"| node_hotspot
node_autostart -.->|"starts at boot"| node_hotspot
node_client_cmd -->|"checks running"| node_hotspot
node_client_cmd -->|"manages clients"| node_clients
node_clients -->|"queries or limits"| node_system
node_user -->|"uses desktop app"| node_gui_app
node_gui_app -->|"uses backend"| node_gui_backend
node_gui_app -.->|"shows pages"| node_gui_pages
node_gui_pages -->|"uses widgets"| node_gui_compat
node_gui_backend -.->|"controls hotspot"| node_hotspot

click node_cli "https://github.com/krotrn/apsta/blob/main/apsta_cli/cli.py"
click node_config_cmd "https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/config.py"
click node_detect_cmd "https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/detect.py"
click node_hotspot_cmd "https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/hotspot.py"
click node_status_cmd "https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/status.py"
click node_client_cmd "https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/clients.py"
click node_config "https://github.com/krotrn/apsta/blob/main/apsta_cli/config/store.py"
click node_validation "https://github.com/krotrn/apsta/blob/main/apsta_cli/config/model.py"
click node_interfaces "https://github.com/krotrn/apsta/blob/main/apsta_cli/hw/interfaces.py"
click node_capability "https://github.com/krotrn/apsta/blob/main/apsta_cli/hw/capability.py"
click node_channels "https://github.com/krotrn/apsta/blob/main/apsta_cli/net/channels.py"
click node_hotspot "https://github.com/krotrn/apsta/blob/main/apsta_cli/services/hotspot.py"
click node_strategies "https://github.com/krotrn/apsta/blob/main/apsta_cli/net/strategies.py"
click node_network_services "https://github.com/krotrn/apsta/tree/main/apsta_cli/net"
click node_state "https://github.com/krotrn/apsta/blob/main/apsta_cli/state.py"
click node_watcher "https://github.com/krotrn/apsta/blob/main/apsta_cli/services/watch.py"
click node_autostart "https://github.com/krotrn/apsta/blob/main/apsta_cli/services/autostart.py"
click node_clients "https://github.com/krotrn/apsta/blob/main/apsta_cli/net/clients.py"
click node_gui_app "https://github.com/krotrn/apsta/blob/main/apsta_gui/app.py"
click node_gui_backend "https://github.com/krotrn/apsta/blob/main/apsta_gui/backend.py"
click node_gui_pages "https://github.com/krotrn/apsta/tree/main/apsta_gui/pages"
click node_gui_compat "https://github.com/krotrn/apsta/blob/main/apsta_gui/compat.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_cli,node_config_cmd,node_detect_cmd,node_hotspot_cmd,node_status_cmd,node_client_cmd,node_user toneBlue
class node_config,node_validation,node_interfaces,node_capability,node_channels toneAmber
class node_hotspot,node_strategies,node_network_services toneMint
class node_state,node_watcher,node_autostart,node_clients toneRose
class node_gui_app,node_gui_backend,node_gui_pages,node_gui_compat,node_system toneIndigo
```

## Components

### User interfaces

- [CLI router](https://github.com/krotrn/apsta/blob/main/apsta_cli/cli.py): `apsta_cli/cli.py`
- [Config and profiles](https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/config.py): `apsta_cli/cmd/config.py`
- [Hardware detection](https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/detect.py): `apsta_cli/cmd/detect.py`
- [Hotspot commands](https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/hotspot.py): `apsta_cli/cmd/hotspot.py`
- [Status and QR](https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/status.py): `apsta_cli/cmd/status.py`
- [Client commands](https://github.com/krotrn/apsta/blob/main/apsta_cli/cmd/clients.py): `apsta_cli/cmd/clients.py`

### Configuration and detection

- [Config store](https://github.com/krotrn/apsta/blob/main/apsta_cli/config/store.py): `apsta_cli/config/store.py`
- [Config model](https://github.com/krotrn/apsta/blob/main/apsta_cli/config/model.py): `apsta_cli/config/model.py`
- [Wi-Fi interfaces](https://github.com/krotrn/apsta/blob/main/apsta_cli/hw/interfaces.py): `apsta_cli/hw/interfaces.py`
- [Radio capability](https://github.com/krotrn/apsta/blob/main/apsta_cli/hw/capability.py): `apsta_cli/hw/capability.py`
- [Channel planning](https://github.com/krotrn/apsta/blob/main/apsta_cli/net/channels.py): `apsta_cli/net/channels.py`

### Hotspot networking

- [Hotspot lifecycle](https://github.com/krotrn/apsta/blob/main/apsta_cli/services/hotspot.py): `apsta_cli/services/hotspot.py`
- [Method strategies](https://github.com/krotrn/apsta/blob/main/apsta_cli/net/strategies.py): `apsta_cli/net/strategies.py`
- [Network setup](https://github.com/krotrn/apsta/tree/main/apsta_cli/net): `apsta_cli/net`

### Runtime management

- [Runtime state](https://github.com/krotrn/apsta/blob/main/apsta_cli/state.py): `apsta_cli/state.py`
- [Recovery watcher](https://github.com/krotrn/apsta/blob/main/apsta_cli/services/watch.py): `apsta_cli/services/watch.py`
- [Boot integration](https://github.com/krotrn/apsta/blob/main/apsta_cli/services/autostart.py): `apsta_cli/services/autostart.py`
- [Client management](https://github.com/krotrn/apsta/blob/main/apsta_cli/net/clients.py): `apsta_cli/net/clients.py`

### Desktop app

- [GTK application](https://github.com/krotrn/apsta/blob/main/apsta_gui/app.py): `apsta_gui/app.py`
- [GUI backend](https://github.com/krotrn/apsta/blob/main/apsta_gui/backend.py): `apsta_gui/backend.py`
- [GUI pages](https://github.com/krotrn/apsta/tree/main/apsta_gui/pages): `apsta_gui/pages`
- [GTK compatibility](https://github.com/krotrn/apsta/blob/main/apsta_gui/compat.py): `apsta_gui/compat.py`

### Other components

- **User**
- **Linux networking**

## Connections

- User → CLI router: runs commands
- CLI router → Hotspot commands: routes hotspot (evidence: `apsta_cli/cli.py`)
- CLI router → Hardware detection: routes detect (evidence: `apsta_cli/cli.py`)
- CLI router → Config and profiles: routes config (evidence: `apsta_cli/cli.py`)
- CLI router → Status and QR: routes status (evidence: `apsta_cli/cli.py`)
- CLI router → Client commands: routes clients (evidence: `apsta_cli/cli.py`)
- Config and profiles → Config store: reads and writes
- Config store → Config model: validates fields (evidence: `apsta_cli/config/store.py`)
- Hardware detection → Radio capability: checks capability (evidence: `apsta_cli/cmd/detect.py`)
- Hardware detection → Wi-Fi interfaces: lists interfaces (evidence: `apsta_cli/cmd/detect.py`)
- Radio capability → Wi-Fi interfaces: inspects radios (evidence: `apsta_cli/hw/capability.py`)
- Hotspot commands → Hotspot lifecycle: starts or stops
- Hotspot lifecycle → Config store: loads settings (evidence: `apsta_cli/services/hotspot.py`)
- Hotspot lifecycle → Wi-Fi interfaces: selects interface (evidence: `apsta_cli/services/hotspot.py`)
- Hotspot lifecycle → Radio capability: checks support (evidence: `apsta_cli/services/hotspot.py`)
- Hotspot lifecycle → Channel planning: plans channel (evidence: `apsta_cli/services/hotspot.py`)
- Hotspot lifecycle → Method strategies: tries methods (evidence: `apsta_cli/services/hotspot.py`)
- Method strategies → Network setup: configures networking (evidence: `apsta_cli/net/strategies.py`)
- Network setup → Linux networking: applies changes
- Hotspot lifecycle → Runtime state: saves result (evidence: `apsta_cli/services/hotspot.py`)
- Status and QR → Hotspot lifecycle: gets status
- Recovery watcher → Hotspot lifecycle: recovers hotspot (evidence: `apsta_cli/services/watch.py`)
- Boot integration → Hotspot lifecycle: starts at boot (evidence: `apsta_cli/services/hotspot.py`)
- Client commands → Hotspot lifecycle: checks running (evidence: `apsta_cli/cmd/clients.py`)
- Client commands → Client management: manages clients (evidence: `apsta_cli/cmd/clients.py`)
- Client management → Linux networking: queries or limits (evidence: `apsta_cli/net/clients.py`)
- User → GTK application: uses desktop app
- GTK application → GUI backend: uses backend (evidence: `apsta_gui/app.py`)
- GTK application → GUI pages: shows pages
- GUI pages → GTK compatibility: uses widgets (evidence: `apsta_gui/pages/hotspot.py`)
- GUI backend → Hotspot lifecycle: controls hotspot
