# crosstalk-solutions/unifi-toolkit architecture

> Architecture diagram of the GitHub repository crosstalk-solutions/unifi-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crosstalk-solutions/unifi-toolkit
- Repository: https://github.com/crosstalk-solutions/unifi-toolkit

## Overview

UI Toolkit is a UniFi network management and monitoring web application: users open the unified dashboard or a focused tool, which exposes status, analytics, tracking, security monitoring, and firewall lockdown workflows. The four tool applications are mounted by the shared FastAPI app; they use common UniFi, persistence, caching, and realtime facilities. README capabilities are retained, but unsampled router and scheduler internals limit confidence about their precise calls, so those links are omitted where not evidenced.

Main entry points: [`app/main.py`](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/app/main.py) (Unified web app), [`tools/house_arrest/main.py`](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/house_arrest/main.py) (House Arrest app), [`tools/network_pulse/main.py`](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/network_pulse/main.py) (Pulse app), [`tools/threat_watch/main.py`](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/threat_watch/main.py) (Threat Watch app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Application Core"]
  node_app["Unified web app<br/>[main.py]"]
  node_unifi["UniFi API client<br/>[unifi_client.py]"]
  node_session["Shared UniFi session<br/>[unifi_session.py]"]
  node_db[("Application database<br/>[database.py]")]
  node_cache["Status cache<br/>[cache.py]"]
  node_webhooks["Webhook delivery<br/>[webhooks.py]"]
  node_ws["WebSocket broadcasts"]
end

subgraph group_pulse["Network Pulse"]
  node_pulse_app["Pulse app<br/>[main.py]"]
  node_pulse_ui["Live dashboard<br/>[app.js]"]
  node_pulse_api["Stats API<br/>[stats.py]"]
  node_pulse_refresh["Refresh scheduler<br/>[scheduler.py]"]
end

subgraph group_stalker["Wi-Fi Stalker"]
  node_stalker_app["Stalker app<br/>[main.py]"]
  node_stalker_ui["Tracking dashboard<br/>[app.js]"]
  node_stalker_devices["Device tracking API<br/>[devices.py]"]
  node_stalker_refresh["Tracking scheduler<br/>[scheduler.py]"]
end

subgraph group_threats["Threat Watch"]
  node_threat_app["Threat Watch app<br/>[main.py]"]
  node_threat_ui["Threat dashboard<br/>[app.js]"]
  node_threat_events["Event monitoring<br/>[events.py]"]
  node_threat_db[("Threat event store<br/>[database.py]")]
end

subgraph group_arrest["House Arrest"]
  node_arrest_app["House Arrest app<br/>[main.py]"]
  node_arrest_ui["Lockdown dashboard<br/>[app.js]"]
  node_arrest_api["Lockdown API<br/>[arrest.py]"]
  node_policies["Firewall policies<br/>[policies.py]"]
end

node_user(("Network operator"))

node_user -->|"uses"| node_app
node_app -->|"mounts"| node_pulse_app
node_app -->|"mounts"| node_stalker_app
node_app -->|"mounts"| node_threat_app
node_app -->|"mounts"| node_arrest_app
node_pulse_app -->|"includes"| node_pulse_api
node_pulse_ui -->|"fetches stats"| node_pulse_api
node_pulse_ui -->|"opens WebSocket"| node_pulse_app
node_pulse_app -->|"manages connections"| node_ws
node_pulse_refresh -->|"broadcasts"| node_ws
node_pulse_refresh -->|"reads network"| node_unifi
node_stalker_app -->|"includes"| node_stalker_devices
node_stalker_ui -->|"requests devices"| node_stalker_devices
node_stalker_refresh -->|"reads clients"| node_unifi
node_stalker_refresh -->|"updates tracking"| node_db
node_threat_ui -->|"loads events"| node_threat_events
node_threat_app -->|"queries events"| node_threat_db
node_threat_events -->|"reads events"| node_threat_db
node_threat_app -->|"checks status"| node_cache
node_arrest_app -->|"includes"| node_arrest_api
node_arrest_ui -->|"requests lockdown"| node_arrest_api
node_arrest_app -->|"builds status"| node_policies
node_arrest_app -->|"gets client"| node_session
node_session -->|"provides client"| node_unifi
node_stalker_devices -.->|"alerts"| node_webhooks

click node_app "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/app/main.py"
click node_unifi "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/unifi_client.py"
click node_session "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/unifi_session.py"
click node_db "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/database.py"
click node_cache "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/cache.py"
click node_webhooks "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/webhooks.py"
click node_ws "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/websocket_manager.py"
click node_pulse_app "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/network_pulse/main.py"
click node_pulse_ui "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/network_pulse/static/js/app.js"
click node_pulse_api "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/network_pulse/routers/stats.py"
click node_pulse_refresh "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/network_pulse/scheduler.py"
click node_stalker_app "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/wifi_stalker/main.py"
click node_stalker_ui "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/wifi_stalker/static/js/app.js"
click node_stalker_devices "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/wifi_stalker/routers/devices.py"
click node_stalker_refresh "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/wifi_stalker/scheduler.py"
click node_threat_app "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/threat_watch/main.py"
click node_threat_ui "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/threat_watch/static/js/app.js"
click node_threat_events "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/threat_watch/routers/events.py"
click node_threat_db "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/threat_watch/database.py"
click node_arrest_app "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/house_arrest/main.py"
click node_arrest_ui "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/house_arrest/static/js/app.js"
click node_arrest_api "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/house_arrest/routers/arrest.py"
click node_policies "https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/house_arrest/policies.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_app,node_unifi,node_session,node_db,node_cache,node_webhooks,node_ws toneBlue
class node_pulse_app,node_pulse_ui,node_pulse_api,node_pulse_refresh toneAmber
class node_stalker_app,node_stalker_ui,node_stalker_devices,node_stalker_refresh toneMint
class node_threat_app,node_threat_ui,node_threat_events,node_threat_db toneRose
class node_arrest_app,node_arrest_ui,node_arrest_api,node_policies,node_user toneIndigo
```

## Components

### Application Core

- [Unified web app](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/app/main.py): `app/main.py`
- [UniFi API client](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/unifi_client.py): `shared/unifi_client.py`
- [Shared UniFi session](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/unifi_session.py): `shared/unifi_session.py`
- [Application database](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/database.py): `shared/database.py`
- [Status cache](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/cache.py): `shared/cache.py`
- [Webhook delivery](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/webhooks.py): `shared/webhooks.py`
- [WebSocket broadcasts](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/shared/websocket_manager.py): `shared/websocket_manager.py`

### Network Pulse

- [Pulse app](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/network_pulse/main.py): `tools/network_pulse/main.py`
- [Live dashboard](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/network_pulse/static/js/app.js): `tools/network_pulse/static/js/app.js`
- [Stats API](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/network_pulse/routers/stats.py): `tools/network_pulse/routers/stats.py`
- [Refresh scheduler](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/network_pulse/scheduler.py): `tools/network_pulse/scheduler.py`

### Wi-Fi Stalker

- [Stalker app](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/wifi_stalker/main.py): `tools/wifi_stalker/main.py`
- [Tracking dashboard](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/wifi_stalker/static/js/app.js): `tools/wifi_stalker/static/js/app.js`
- [Device tracking API](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/wifi_stalker/routers/devices.py): `tools/wifi_stalker/routers/devices.py`
- [Tracking scheduler](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/wifi_stalker/scheduler.py): `tools/wifi_stalker/scheduler.py`

### Threat Watch

- [Threat Watch app](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/threat_watch/main.py): `tools/threat_watch/main.py`
- [Threat dashboard](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/threat_watch/static/js/app.js): `tools/threat_watch/static/js/app.js`
- [Event monitoring](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/threat_watch/routers/events.py): `tools/threat_watch/routers/events.py`
- [Threat event store](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/threat_watch/database.py): `tools/threat_watch/database.py`

### House Arrest

- [House Arrest app](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/house_arrest/main.py): `tools/house_arrest/main.py`
- [Lockdown dashboard](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/house_arrest/static/js/app.js): `tools/house_arrest/static/js/app.js`
- [Lockdown API](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/house_arrest/routers/arrest.py): `tools/house_arrest/routers/arrest.py`
- [Firewall policies](https://github.com/crosstalk-solutions/unifi-toolkit/blob/main/tools/house_arrest/policies.py): `tools/house_arrest/policies.py`

### Other components

- **Network operator**

## Connections

- Network operator → Unified web app: uses
- Unified web app → Pulse app: mounts
- Unified web app → Stalker app: mounts
- Unified web app → Threat Watch app: mounts
- Unified web app → House Arrest app: mounts
- Pulse app → Stats API: includes
- Live dashboard → Stats API: fetches stats
- Live dashboard → Pulse app: opens WebSocket
- Pulse app → WebSocket broadcasts: manages connections
- Refresh scheduler → WebSocket broadcasts: broadcasts
- Refresh scheduler → UniFi API client: reads network
- Stalker app → Device tracking API: includes
- Tracking dashboard → Device tracking API: requests devices
- Tracking scheduler → UniFi API client: reads clients
- Tracking scheduler → Application database: updates tracking
- Threat dashboard → Event monitoring: loads events
- Threat Watch app → Threat event store: queries events
- Event monitoring → Threat event store: reads events
- Threat Watch app → Status cache: checks status
- House Arrest app → Lockdown API: includes
- Lockdown dashboard → Lockdown API: requests lockdown
- House Arrest app → Firewall policies: builds status
- House Arrest app → Shared UniFi session: gets client
- Shared UniFi session → UniFi API client: provides client
- Device tracking API → Webhook delivery: alerts