# arselzer/solix-link architecture

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

- Interactive diagram: https://gitdiagram.com/arselzer/solix-link
- Repository: https://github.com/arselzer/solix-link

## Overview

SOLIX Link provides local station monitoring and controls through Bluetooth, native MQTT over an isolated AP, a Python CLI/TUI, an optional HTTP/SSE gateway and browser dashboard, and Home Assistant. The main workflow connects to stations, normalizes telemetry, exposes guarded controls, and optionally records history or derives energy estimates; policy previews and fleet/AP management are separate capabilities. A separate Web Bluetooth app explores supported station protocols. Edges are limited to README statements and source-index references; several subsystem implementations were not sampled, so uncertain links are omitted.

Main entry points: [`python/solix_link/server.py`](https://github.com/arselzer/solix-link/blob/main/python/solix_link/server.py) (HTTP gateway), [`python/solix_link/ap_service.py`](https://github.com/arselzer/solix-link/blob/main/python/solix_link/ap_service.py) (AP service), [`src/protocol/connection.ts`](https://github.com/arselzer/solix-link/blob/main/src/protocol/connection.ts) (Browser BLE protocol), [`python/solix_link/manager.py`](https://github.com/arselzer/solix-link/blob/main/python/solix_link/manager.py) (Station manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connect["Station connectivity"]
  node_ble["Bluetooth client<br/>[client.py]"]
  node_protocol["Station protocol<br/>[protocol.py]"]
  node_apservice["AP service<br/>[ap_service.py]"]
  node_mqtt["MQTT interception<br/>[mqtt_intercept.py]"]
  node_webconnection["Browser BLE protocol<br/>[connection.ts]"]
  node_webtelemetry["Telemetry parser<br/>[telemetry.ts]"]
end

subgraph group_services["Python services"]
  node_manager["Station manager<br/>[manager.py]"]
  node_gateway["HTTP gateway<br/>[server.py]"]
  node_access["Scoped access<br/>[access.py]"]
  node_coordination["Write coordination"]
  node_activity["UPS activity<br/>[activity.py]"]
  node_history[("Saved history<br/>[history.py]")]
end

subgraph group_policy["Controls and energy"]
  node_commands["Device commands<br/>[commands.py]"]
  node_energy["Energy estimates<br/>[energy_values.py]"]
  node_tou["Time-of-use plans<br/>[tou.py]"]
  node_charging["Charging policies<br/>[charging_policy.py]"]
  node_controller["Policy controller"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI and TUI<br/>[cli.py]"]
  node_webdash["Gateway dashboard<br/>[App.vue]"]
  node_gatewayhook["Gateway client<br/>[useGateway.ts]"]
  node_bleapp["Web Bluetooth explorer<br/>[App.vue]"]
end

subgraph group_ha["Home Assistant"]
  node_haapi["HA integration API<br/>[api.py]"]
  node_hasensor["HA entities<br/>[sensor.py]"]
  node_haenergy["Native energy entities<br/>[native_energy.py]"]
end

node_operator(("Operator"))
node_station(("SOLIX station"))
node_ap(("Isolated AP"))

node_operator -->|"runs"| node_cli
node_cli -.->|"manages stations"| node_manager
node_manager -->|"connects over BLE"| node_ble
node_ble -->|"uses protocol"| node_protocol
node_manager -->|"dispatches controls"| node_commands
node_station -->|"joins locally"| node_ap
node_apservice -->|"uses interception"| node_mqtt
node_apservice -->|"uses protocol"| node_protocol
node_apservice -->|"uses schedules"| node_tou
node_apservice -->|"uses commands"| node_commands
node_operator -->|"requests dashboard"| node_gateway
node_gateway -->|"authenticates requests"| node_access
node_gateway -->|"coordinates writes"| node_coordination
node_gateway -->|"exposes observations"| node_activity
node_gateway -->|"records readings"| node_history
node_gateway -->|"exposes estimates"| node_energy
node_gateway -->|"serves plans"| node_tou
node_gateway -->|"serves previews"| node_charging
node_gateway -->|"serves previews"| node_controller
node_operator -->|"reviews stations"| node_webdash
node_webdash -->|"uses gateway client"| node_gatewayhook
node_gatewayhook -.->|"fetches gateway data"| node_gateway
node_operator -->|"configures integration"| node_haapi
node_haapi -->|"provides native energy"| node_haenergy
node_haapi -.->|"provides telemetry"| node_hasensor
node_operator -->|"uses browser app"| node_bleapp
node_bleapp -->|"connects to station"| node_webconnection
node_webconnection -->|"parses telemetry"| node_webtelemetry
node_webconnection -->|"communicates by Bluetooth"| node_station

click node_cli "https://github.com/arselzer/solix-link/blob/main/python/solix_link/cli.py"
click node_manager "https://github.com/arselzer/solix-link/blob/main/python/solix_link/manager.py"
click node_ble "https://github.com/arselzer/solix-link/blob/main/python/solix_link/client.py"
click node_protocol "https://github.com/arselzer/solix-link/blob/main/python/solix_link/protocol.py"
click node_commands "https://github.com/arselzer/solix-link/blob/main/python/solix_link/commands.py"
click node_apservice "https://github.com/arselzer/solix-link/blob/main/python/solix_link/ap_service.py"
click node_mqtt "https://github.com/arselzer/solix-link/blob/main/python/solix_link/mqtt_intercept.py"
click node_gateway "https://github.com/arselzer/solix-link/blob/main/python/solix_link/server.py"
click node_access "https://github.com/arselzer/solix-link/blob/main/python/solix_link/access.py"
click node_coordination "https://github.com/arselzer/solix-link/blob/main/python/solix_link/command_coordination.py"
click node_activity "https://github.com/arselzer/solix-link/blob/main/python/solix_link/activity.py"
click node_history "https://github.com/arselzer/solix-link/blob/main/python/solix_link/history.py"
click node_energy "https://github.com/arselzer/solix-link/blob/main/python/solix_link/energy_values.py"
click node_tou "https://github.com/arselzer/solix-link/blob/main/python/solix_link/tou.py"
click node_charging "https://github.com/arselzer/solix-link/blob/main/python/solix_link/charging_policy.py"
click node_controller "https://github.com/arselzer/solix-link/blob/main/python/solix_link/charging_controller.py"
click node_webdash "https://github.com/arselzer/solix-link/blob/main/dashboard/src/App.vue"
click node_gatewayhook "https://github.com/arselzer/solix-link/blob/main/dashboard/src/useGateway.ts"
click node_haapi "https://github.com/arselzer/solix-link/blob/main/custom_components/solix_link/api.py"
click node_hasensor "https://github.com/arselzer/solix-link/blob/main/custom_components/solix_link/sensor.py"
click node_haenergy "https://github.com/arselzer/solix-link/blob/main/custom_components/solix_link/native_energy.py"
click node_bleapp "https://github.com/arselzer/solix-link/blob/main/src/App.vue"
click node_webconnection "https://github.com/arselzer/solix-link/blob/main/src/protocol/connection.ts"
click node_webtelemetry "https://github.com/arselzer/solix-link/blob/main/src/protocol/telemetry.ts"

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_ble,node_protocol,node_apservice,node_mqtt,node_webconnection,node_webtelemetry toneBlue
class node_manager,node_gateway,node_access,node_coordination,node_activity,node_history toneAmber
class node_commands,node_energy,node_tou,node_charging,node_controller toneMint
class node_cli,node_webdash,node_gatewayhook,node_bleapp toneRose
class node_haapi,node_hasensor,node_haenergy,node_operator,node_station,node_ap toneIndigo
```

## Components

### Station connectivity

- [Bluetooth client](https://github.com/arselzer/solix-link/blob/main/python/solix_link/client.py): `python/solix_link/client.py`
- [Station protocol](https://github.com/arselzer/solix-link/blob/main/python/solix_link/protocol.py): `python/solix_link/protocol.py`
- [AP service](https://github.com/arselzer/solix-link/blob/main/python/solix_link/ap_service.py): `python/solix_link/ap_service.py`
- [MQTT interception](https://github.com/arselzer/solix-link/blob/main/python/solix_link/mqtt_intercept.py): `python/solix_link/mqtt_intercept.py`
- [Browser BLE protocol](https://github.com/arselzer/solix-link/blob/main/src/protocol/connection.ts): `src/protocol/connection.ts`
- [Telemetry parser](https://github.com/arselzer/solix-link/blob/main/src/protocol/telemetry.ts): `src/protocol/telemetry.ts`

### Python services

- [Station manager](https://github.com/arselzer/solix-link/blob/main/python/solix_link/manager.py): `python/solix_link/manager.py`
- [HTTP gateway](https://github.com/arselzer/solix-link/blob/main/python/solix_link/server.py): `python/solix_link/server.py`
- [Scoped access](https://github.com/arselzer/solix-link/blob/main/python/solix_link/access.py): `python/solix_link/access.py`
- [Write coordination](https://github.com/arselzer/solix-link/blob/main/python/solix_link/command_coordination.py): `python/solix_link/command_coordination.py`
- [UPS activity](https://github.com/arselzer/solix-link/blob/main/python/solix_link/activity.py): `python/solix_link/activity.py`
- [Saved history](https://github.com/arselzer/solix-link/blob/main/python/solix_link/history.py): `python/solix_link/history.py`

### Controls and energy

- [Device commands](https://github.com/arselzer/solix-link/blob/main/python/solix_link/commands.py): `python/solix_link/commands.py`
- [Energy estimates](https://github.com/arselzer/solix-link/blob/main/python/solix_link/energy_values.py): `python/solix_link/energy_values.py`
- [Time-of-use plans](https://github.com/arselzer/solix-link/blob/main/python/solix_link/tou.py): `python/solix_link/tou.py`
- [Charging policies](https://github.com/arselzer/solix-link/blob/main/python/solix_link/charging_policy.py): `python/solix_link/charging_policy.py`
- [Policy controller](https://github.com/arselzer/solix-link/blob/main/python/solix_link/charging_controller.py): `python/solix_link/charging_controller.py`

### User interfaces

- [CLI and TUI](https://github.com/arselzer/solix-link/blob/main/python/solix_link/cli.py): `python/solix_link/cli.py`
- [Gateway dashboard](https://github.com/arselzer/solix-link/blob/main/dashboard/src/App.vue): `dashboard/src/App.vue`
- [Gateway client](https://github.com/arselzer/solix-link/blob/main/dashboard/src/useGateway.ts): `dashboard/src/useGateway.ts`
- [Web Bluetooth explorer](https://github.com/arselzer/solix-link/blob/main/src/App.vue): `src/App.vue`

### Home Assistant

- [HA integration API](https://github.com/arselzer/solix-link/blob/main/custom_components/solix_link/api.py): `custom_components/solix_link/api.py`
- [HA entities](https://github.com/arselzer/solix-link/blob/main/custom_components/solix_link/sensor.py): `custom_components/solix_link/sensor.py`
- [Native energy entities](https://github.com/arselzer/solix-link/blob/main/custom_components/solix_link/native_energy.py): `custom_components/solix_link/native_energy.py`

### Other components

- **Operator**
- **SOLIX station**
- **Isolated AP**

## Connections

- Operator → CLI and TUI: runs
- CLI and TUI → Station manager: manages stations
- Station manager → Bluetooth client: connects over BLE (evidence: `python/solix_link/manager.py`)
- Bluetooth client → Station protocol: uses protocol (evidence: `python/solix_link/client.py`)
- Station manager → Device commands: dispatches controls (evidence: `python/solix_link/manager.py`)
- SOLIX station → Isolated AP: joins locally
- AP service → MQTT interception: uses interception (evidence: `python/solix_link/ap_service.py`)
- AP service → Station protocol: uses protocol (evidence: `python/solix_link/ap_service.py`)
- AP service → Time-of-use plans: uses schedules (evidence: `python/solix_link/ap_service.py`)
- AP service → Device commands: uses commands (evidence: `python/solix_link/ap_service.py`)
- Operator → HTTP gateway: requests dashboard
- HTTP gateway → Scoped access: authenticates requests (evidence: `python/solix_link/server.py`)
- HTTP gateway → Write coordination: coordinates writes (evidence: `python/solix_link/server.py`)
- HTTP gateway → UPS activity: exposes observations (evidence: `python/solix_link/server.py`)
- HTTP gateway → Saved history: records readings (evidence: `python/solix_link/server.py`)
- HTTP gateway → Energy estimates: exposes estimates (evidence: `python/solix_link/server.py`)
- HTTP gateway → Time-of-use plans: serves plans (evidence: `python/solix_link/server.py`)
- HTTP gateway → Charging policies: serves previews (evidence: `python/solix_link/server.py`)
- HTTP gateway → Policy controller: serves previews (evidence: `python/solix_link/server.py`)
- Operator → Gateway dashboard: reviews stations (evidence: `dashboard/src/App.vue`)
- Gateway dashboard → Gateway client: uses gateway client (evidence: `dashboard/src/App.vue`)
- Gateway client → HTTP gateway: fetches gateway data
- Operator → HA integration API: configures integration
- HA integration API → Native energy entities: provides native energy (evidence: `custom_components/solix_link/api.py`)
- HA integration API → HA entities: provides telemetry
- Operator → Web Bluetooth explorer: uses browser app
- Web Bluetooth explorer → Browser BLE protocol: connects to station (evidence: `src/App.vue`)
- Browser BLE protocol → Telemetry parser: parses telemetry (evidence: `src/protocol/connection.ts`)
- Browser BLE protocol → SOLIX station: communicates by Bluetooth
