# mr-addict/homekit-devices architecture

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

- Interactive diagram: https://gitdiagram.com/mr-addict/homekit-devices
- Repository: https://github.com/mr-addict/homekit-devices

## Overview

This repository combines HomeSpan ESP32 devices, two Go-based HomeKit services, and a browser-based BLE provisioning tool. The main user workflow is to select a HomeSpan device, connect over BLE, authenticate with its OTA password, then send Wi-Fi credentials and confirm completion. The graph also preserves the documented fan, lamp, Wake-on-LAN, and temperature capabilities. Go and firmware internals are represented from the tree and README; their detailed call relationships were not sampled, so those links are omitted.

Main entry points: [`src/web/ble-provision/src/workflows/controller.ts`](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/workflows/controller.ts) (Provision controller), [`src/web/ble-provision/src/services/ble-session.ts`](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/services/ble-session.ts) (BLE session), [`src/go/cmd/homekit-wol/main.go`](https://github.com/mr-addict/homekit-devices/blob/main/src/go/cmd/homekit-wol/main.go) (Go WOL service), [`src/go/cmd/homekit-temperature/main.go`](https://github.com/mr-addict/homekit-devices/blob/main/src/go/cmd/homekit-temperature/main.go) (Temperature service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provisioning["BLE provisioning"]
  node_browser["Provisioning page<br/>[app.ts]"]
  node_controller["Provision controller<br/>[controller.ts]"]
  node_view["Provision UI<br/>[view.ts]"]
  node_flow["Phase rules<br/>[flow.ts]"]
  node_session["BLE session<br/>[ble-session.ts]"]
  node_frames["Frame encoding<br/>[frames.ts]"]
  node_status["Status parsing<br/>[status.ts]"]
  node_send_frame["Frame exchange<br/>[send-frame.ts]"]
  node_credentials["Wi-Fi credential read<br/>[credentials.ts]"]
  node_ota_storage[("Saved OTA password<br/>[ota-storage.ts]")]
end

subgraph group_firmware["HomeSpan firmware"]
  node_device_ble["HomeSpan BLE device<br/>[ble_provision.h]"]
  node_fan["Fan accessory<br/>[fan.h]"]
  node_lamp["Lamp accessory<br/>[lamp.h]"]
  node_firmware_wol["Firmware Wake-on-LAN<br/>[wol.h]"]
end

subgraph group_go_wol["Go Wake-on-LAN"]
  node_wol_main["Go WOL service<br/>[main.go]"]
  node_wol_accessories["WOL accessories<br/>[accessories.go]"]
  node_wol_switch["WOL switch<br/>[switch.go]"]
  node_wol_sender["Magic packet sender<br/>[sender.go]"]
end

subgraph group_go_temperature["Go temperature"]
  node_temperature_main["Temperature service<br/>[main.go]"]
  node_temperature_accessory["Temperature accessory<br/>[accessory.go]"]
  node_temperature_sensor["Temperature sensor<br/>[sensor.go]"]
end

subgraph group_go_shared["Go HomeKit base"]
  node_hap_server["HomeKit server<br/>[server.go]"]
  node_hap_config["Server configuration<br/>[config.go]"]
end

node_user(("Device user"))

node_user -->|"uses"| node_browser
node_browser -->|"starts"| node_controller
node_controller -->|"binds and renders"| node_view
node_view -->|"uses phase rules"| node_flow
node_controller -->|"controls connection"| node_session
node_controller -->|"creates frames"| node_frames
node_controller -->|"loads and saves"| node_ota_storage
node_session -->|"sends frames"| node_send_frame
node_session -->|"parses device status"| node_status
node_session -->|"reads Wi-Fi data"| node_credentials
node_send_frame -->|"parses replies"| node_status
node_session -->|"communicates over BLE"| node_device_ble
node_wol_main -.->|"provides service"| node_wol_accessories
node_temperature_main -.->|"provides service"| node_temperature_accessory
node_wol_main -.->|"uses shared HomeKit base"| node_hap_server
node_temperature_main -.->|"uses shared HomeKit base"| node_hap_server

click node_browser "https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/app.ts"
click node_controller "https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/workflows/controller.ts"
click node_view "https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/ui/view.ts"
click node_flow "https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/workflows/flow.ts"
click node_session "https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/services/ble-session.ts"
click node_frames "https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/protocol/frames.ts"
click node_status "https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/protocol/status.ts"
click node_send_frame "https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/services/send-frame.ts"
click node_credentials "https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/services/credentials.ts"
click node_ota_storage "https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/services/ota-storage.ts"
click node_device_ble "https://github.com/mr-addict/homekit-devices/blob/main/src/homespan/common/ble_provision.h"
click node_fan "https://github.com/mr-addict/homekit-devices/blob/main/src/homespan/fan/fan.h"
click node_lamp "https://github.com/mr-addict/homekit-devices/blob/main/src/homespan/lamp/lamp.h"
click node_firmware_wol "https://github.com/mr-addict/homekit-devices/blob/main/src/homespan/wol/wol.h"
click node_wol_main "https://github.com/mr-addict/homekit-devices/blob/main/src/go/cmd/homekit-wol/main.go"
click node_wol_accessories "https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/wol/accessories.go"
click node_wol_switch "https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/wol/switch.go"
click node_wol_sender "https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/wol/sender.go"
click node_temperature_main "https://github.com/mr-addict/homekit-devices/blob/main/src/go/cmd/homekit-temperature/main.go"
click node_temperature_accessory "https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/temperature/accessory.go"
click node_temperature_sensor "https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/temperature/sensor.go"
click node_hap_server "https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/hapserver/server.go"
click node_hap_config "https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/hapserver/config.go"

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_browser,node_controller,node_view,node_flow,node_session,node_frames,node_status,node_send_frame,node_credentials,node_ota_storage,node_user toneBlue
class node_device_ble,node_fan,node_lamp,node_firmware_wol toneAmber
class node_wol_main,node_wol_accessories,node_wol_switch,node_wol_sender toneMint
class node_temperature_main,node_temperature_accessory,node_temperature_sensor toneRose
class node_hap_server,node_hap_config toneIndigo
```

## Components

### BLE provisioning

- [Provisioning page](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/app.ts): `src/web/ble-provision/src/app.ts`
- [Provision controller](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/workflows/controller.ts): `src/web/ble-provision/src/workflows/controller.ts`
- [Provision UI](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/ui/view.ts): `src/web/ble-provision/src/ui/view.ts`
- [Phase rules](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/workflows/flow.ts): `src/web/ble-provision/src/workflows/flow.ts`
- [BLE session](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/services/ble-session.ts): `src/web/ble-provision/src/services/ble-session.ts`
- [Frame encoding](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/protocol/frames.ts): `src/web/ble-provision/src/protocol/frames.ts`
- [Status parsing](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/protocol/status.ts): `src/web/ble-provision/src/protocol/status.ts`
- [Frame exchange](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/services/send-frame.ts): `src/web/ble-provision/src/services/send-frame.ts`
- [Wi-Fi credential read](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/services/credentials.ts): `src/web/ble-provision/src/services/credentials.ts`
- [Saved OTA password](https://github.com/mr-addict/homekit-devices/blob/main/src/web/ble-provision/src/services/ota-storage.ts): `src/web/ble-provision/src/services/ota-storage.ts`

### HomeSpan firmware

- [HomeSpan BLE device](https://github.com/mr-addict/homekit-devices/blob/main/src/homespan/common/ble_provision.h): `src/homespan/common/ble_provision.h`
- [Fan accessory](https://github.com/mr-addict/homekit-devices/blob/main/src/homespan/fan/fan.h): `src/homespan/fan/fan.h`
- [Lamp accessory](https://github.com/mr-addict/homekit-devices/blob/main/src/homespan/lamp/lamp.h): `src/homespan/lamp/lamp.h`
- [Firmware Wake-on-LAN](https://github.com/mr-addict/homekit-devices/blob/main/src/homespan/wol/wol.h): `src/homespan/wol/wol.h`

### Go Wake-on-LAN

- [Go WOL service](https://github.com/mr-addict/homekit-devices/blob/main/src/go/cmd/homekit-wol/main.go): `src/go/cmd/homekit-wol/main.go`
- [WOL accessories](https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/wol/accessories.go): `src/go/internal/wol/accessories.go`
- [WOL switch](https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/wol/switch.go): `src/go/internal/wol/switch.go`
- [Magic packet sender](https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/wol/sender.go): `src/go/internal/wol/sender.go`

### Go temperature

- [Temperature service](https://github.com/mr-addict/homekit-devices/blob/main/src/go/cmd/homekit-temperature/main.go): `src/go/cmd/homekit-temperature/main.go`
- [Temperature accessory](https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/temperature/accessory.go): `src/go/internal/temperature/accessory.go`
- [Temperature sensor](https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/temperature/sensor.go): `src/go/internal/temperature/sensor.go`

### Go HomeKit base

- [HomeKit server](https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/hapserver/server.go): `src/go/internal/hapserver/server.go`
- [Server configuration](https://github.com/mr-addict/homekit-devices/blob/main/src/go/internal/hapserver/config.go): `src/go/internal/hapserver/config.go`

### Other components

- **Device user**

## Connections

- Device user → Provisioning page: uses (evidence: `README.md`)
- Provisioning page → Provision controller: starts (evidence: `src/web/ble-provision/src/app.ts`)
- Provision controller → Provision UI: binds and renders (evidence: `src/web/ble-provision/src/workflows/controller.ts`)
- Provision UI → Phase rules: uses phase rules (evidence: `src/web/ble-provision/src/ui/view.ts`)
- Provision controller → BLE session: controls connection (evidence: `src/web/ble-provision/src/workflows/controller.ts`)
- Provision controller → Frame encoding: creates frames (evidence: `src/web/ble-provision/src/workflows/controller.ts`)
- Provision controller → Saved OTA password: loads and saves (evidence: `src/web/ble-provision/src/workflows/controller.ts`)
- BLE session → Frame exchange: sends frames (evidence: `src/web/ble-provision/src/services/ble-session.ts`)
- BLE session → Status parsing: parses device status (evidence: `src/web/ble-provision/src/services/ble-session.ts`)
- BLE session → Wi-Fi credential read: reads Wi-Fi data (evidence: `src/web/ble-provision/src/services/ble-session.ts`)
- Frame exchange → Status parsing: parses replies (evidence: `src/web/ble-provision/src/services/send-frame.ts`)
- BLE session → HomeSpan BLE device: communicates over BLE (evidence: `src/web/ble-provision/src/services/ble-session.ts`)
- Go WOL service → WOL accessories: provides service (evidence: `README.md`)
- Temperature service → Temperature accessory: provides service (evidence: `README.md`)
- Go WOL service → HomeKit server: uses shared HomeKit base (evidence: `README.md`)
- Temperature service → HomeKit server: uses shared HomeKit base (evidence: `README.md`)
