# allekslar/zigbee-gateway_v1 architecture

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

- Interactive diagram: https://gitdiagram.com/allekslar/zigbee-gateway_v1
- Repository: https://github.com/allekslar/zigbee-gateway_v1

## Overview

This is an ESP32-C6 Zigbee gateway: firmware startup initializes the service runtime, then exposes gateway control through HTTP and optional MQTT and Matter bridge paths. The runtime centers device/network operations, gateway firmware OTA, and Zigbee reporting; RCP updates are a separate capability. The graph preserves those documented product branches and sampled HAL boundaries. Some service internals and bridge wiring are unsampled, so their relationships are omitted rather than inferred.

Main entry points: [`components/service/service_runtime.cpp`](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/service_runtime.cpp) (Service runtime), [`main/app_main.cpp`](https://github.com/allekslar/zigbee-gateway_v1/blob/main/main/app_main.cpp) (Firmware startup), [`components/web_ui/web_handlers_device.cpp`](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/web_ui/web_handlers_device.cpp) (Web UI and API), [`components/service/include/service_runtime_api.hpp`](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/include/service_runtime_api.hpp) (Runtime API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Firmware entry"]
  node_main["Firmware startup<br/>[app_main.cpp]"]
end

subgraph group_runtime["Gateway services"]
  node_runtime["Service runtime"]
  node_api["Runtime API"]
  node_network["Network manager"]
  node_config["Configuration manager<br/>[config_manager.hpp]"]
  node_ota["Gateway firmware OTA<br/>[ota_manager.cpp]"]
  node_manifest["OTA manifest validation<br/>[ota_manifest.cpp]"]
  node_rcp["Separate RCP updates"]
  node_reporting["Zigbee reporting"]
end

subgraph group_domain["Device core"]
  node_core["Core state and events<br/>[core_reducer.cpp]"]
  node_commands["Command dispatch"]
  node_registry["Core registry<br/>[core_registry.cpp]"]
end

subgraph group_interfaces["Control interfaces"]
  node_web["Web UI and API"]
  node_routes["HTTP route registration<br/>[web_routes.cpp]"]
  node_mqtt["MQTT bridge<br/>[mqtt_bridge.cpp]"]
  node_matter["Matter bridge<br/>[matter_bridge.cpp]"]
end

subgraph group_platform["Platform adapters"]
  node_zigbee_hal["Zigbee HAL<br/>[hal_zigbee.c]"]
  node_wifi_hal["Wi-Fi HAL<br/>[hal_wifi.c]"]
  node_ota_hal["OTA HAL<br/>[hal_ota.c]"]
  node_mqtt_hal["MQTT HAL<br/>[hal_mqtt.c]"]
  node_nvs_hal["NVS HAL<br/>[hal_nvs.c]"]
end

node_operator(("Operator"))

node_operator -->|"uses controls"| node_web
node_main -->|"starts"| node_runtime
node_main -->|"starts"| node_web
node_main -->|"attaches and starts"| node_mqtt
node_main -->|"attaches and starts"| node_matter
node_web -->|"submits requests"| node_api
node_routes -->|"registers handlers"| node_web
node_mqtt -->|"submits commands"| node_api
node_matter -->|"uses runtime contract"| node_api
node_runtime -.->|"implements contract"| node_api
node_runtime -.->|"processes events"| node_core
node_runtime -.->|"dispatches commands"| node_commands
node_runtime -.->|"uses registry"| node_registry
node_network -->|"uses"| node_wifi_hal
node_network -->|"uses"| node_zigbee_hal
node_ota -->|"downloads and installs"| node_ota_hal
node_ota -->|"persists status"| node_nvs_hal
node_ota -.->|"validates update"| node_manifest
node_rcp -->|"uses update transport"| node_ota_hal
node_reporting -->|"handles core events"| node_core
node_mqtt -->|"uses transport"| node_mqtt_hal

click node_main "https://github.com/allekslar/zigbee-gateway_v1/blob/main/main/app_main.cpp"
click node_web "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/web_ui/web_handlers_device.cpp"
click node_routes "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/web_ui/web_routes.cpp"
click node_mqtt "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/mqtt_bridge/mqtt_bridge.cpp"
click node_matter "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/matter_bridge/matter_bridge.cpp"
click node_runtime "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/service_runtime.cpp"
click node_api "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/include/service_runtime_api.hpp"
click node_network "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/network_manager.cpp"
click node_config "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/include/config_manager.hpp"
click node_ota "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/ota_manager.cpp"
click node_manifest "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/ota_manifest.cpp"
click node_rcp "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/rcp_update_manager.cpp"
click node_reporting "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/reporting_manager.cpp"
click node_core "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/core/core_reducer.cpp"
click node_commands "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/core/core_command_dispatcher.cpp"
click node_registry "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/core/core_registry.cpp"
click node_zigbee_hal "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/app_hal/hal_zigbee.c"
click node_wifi_hal "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/app_hal/hal_wifi.c"
click node_ota_hal "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/app_hal/hal_ota.c"
click node_mqtt_hal "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/app_hal/hal_mqtt.c"
click node_nvs_hal "https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/app_hal/hal_nvs.c"

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 toneBlue
class node_runtime,node_api,node_network,node_config,node_ota,node_manifest,node_rcp,node_reporting toneAmber
class node_core,node_commands,node_registry toneMint
class node_web,node_routes,node_mqtt,node_matter toneRose
class node_zigbee_hal,node_wifi_hal,node_ota_hal,node_mqtt_hal,node_nvs_hal,node_operator toneIndigo
```

## Components

### Firmware entry

- [Firmware startup](https://github.com/allekslar/zigbee-gateway_v1/blob/main/main/app_main.cpp): `main/app_main.cpp`

### Gateway services

- [Service runtime](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/service_runtime.cpp): `components/service/service_runtime.cpp`
- [Runtime API](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/include/service_runtime_api.hpp): `components/service/include/service_runtime_api.hpp`
- [Network manager](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/network_manager.cpp): `components/service/network_manager.cpp`
- [Configuration manager](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/include/config_manager.hpp): `components/service/include/config_manager.hpp`
- [Gateway firmware OTA](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/ota_manager.cpp): `components/service/ota_manager.cpp`
- [OTA manifest validation](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/ota_manifest.cpp): `components/service/ota_manifest.cpp`
- [Separate RCP updates](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/rcp_update_manager.cpp): `components/service/rcp_update_manager.cpp`
- [Zigbee reporting](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/service/reporting_manager.cpp): `components/service/reporting_manager.cpp`

### Device core

- [Core state and events](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/core/core_reducer.cpp): `components/core/core_reducer.cpp`
- [Command dispatch](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/core/core_command_dispatcher.cpp): `components/core/core_command_dispatcher.cpp`
- [Core registry](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/core/core_registry.cpp): `components/core/core_registry.cpp`

### Control interfaces

- [Web UI and API](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/web_ui/web_handlers_device.cpp): `components/web_ui/web_handlers_device.cpp`
- [HTTP route registration](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/web_ui/web_routes.cpp): `components/web_ui/web_routes.cpp`
- [MQTT bridge](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/mqtt_bridge/mqtt_bridge.cpp): `components/mqtt_bridge/mqtt_bridge.cpp`
- [Matter bridge](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/matter_bridge/matter_bridge.cpp): `components/matter_bridge/matter_bridge.cpp`

### Platform adapters

- [Zigbee HAL](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/app_hal/hal_zigbee.c): `components/app_hal/hal_zigbee.c`
- [Wi-Fi HAL](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/app_hal/hal_wifi.c): `components/app_hal/hal_wifi.c`
- [OTA HAL](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/app_hal/hal_ota.c): `components/app_hal/hal_ota.c`
- [MQTT HAL](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/app_hal/hal_mqtt.c): `components/app_hal/hal_mqtt.c`
- [NVS HAL](https://github.com/allekslar/zigbee-gateway_v1/blob/main/components/app_hal/hal_nvs.c): `components/app_hal/hal_nvs.c`

### Other components

- **Operator**

## Connections

- Operator → Web UI and API: uses controls
- Firmware startup → Service runtime: starts (evidence: `main/app_main.cpp`)
- Firmware startup → Web UI and API: starts (evidence: `main/app_main.cpp`)
- Firmware startup → MQTT bridge: attaches and starts (evidence: `main/app_main.cpp`)
- Firmware startup → Matter bridge: attaches and starts (evidence: `main/app_main.cpp`)
- Web UI and API → Runtime API: submits requests (evidence: `components/web_ui/web_handlers_device.cpp`)
- HTTP route registration → Web UI and API: registers handlers
- MQTT bridge → Runtime API: submits commands (evidence: `components/mqtt_bridge/mqtt_bridge.cpp`)
- Matter bridge → Runtime API: uses runtime contract
- Service runtime → Runtime API: implements contract
- Service runtime → Core state and events: processes events
- Service runtime → Command dispatch: dispatches commands
- Service runtime → Core registry: uses registry
- Network manager → Wi-Fi HAL: uses (evidence: `components/service/network_manager.cpp`)
- Network manager → Zigbee HAL: uses (evidence: `components/service/network_manager.cpp`)
- Gateway firmware OTA → OTA HAL: downloads and installs (evidence: `components/service/ota_manager.cpp`)
- Gateway firmware OTA → NVS HAL: persists status (evidence: `components/service/ota_manager.cpp`)
- Gateway firmware OTA → OTA manifest validation: validates update
- Separate RCP updates → OTA HAL: uses update transport (evidence: `components/service/rcp_update_manager.cpp`)
- Zigbee reporting → Core state and events: handles core events
- MQTT bridge → MQTT HAL: uses transport (evidence: `components/mqtt_bridge/mqtt_bridge.cpp`)