# wisilicalumos/ha-lumos architecture

> Architecture diagram of the GitHub repository wisilicalumos/ha-lumos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wisilicalumos/ha-lumos
- Repository: https://github.com/wisilicalumos/ha-lumos

## Overview

1. This repository is a Home Assistant custom integration for Lumos Smart Lighting by WiSilica. Its architectural boundary is clear: Home Assistant talks to the Lumos cloud API, not directly to local devices or a local bridge.

2. The integration lives entirely under `custom_components/lumos`, which is the standard Home Assistant plugin layout. `manifest.json` defines it as a custom integration, and the top-level `hacs.json` plus GitHub workflows show it is packaged for HACS distribution and validated with Home Assistant tooling.

3. Configuration is entry-based, not YAML-based. `config_flow.py` handles onboarding through Home Assistant’s UI, including the cloud API base URL and account credentials. The README indicates multi-account support, so each config entry represents an independent Lumos account.

4. `api.py` is the cloud boundary. It is the layer that authenticates with the Lumos backend, retrieves devices/state, and sends control commands. All device control ultimately passes through this module.

5. `coordinator.py` is the state synchronization core. It likely uses Home Assistant’s data update coordinator pattern to poll the cloud on a fixed interval, refresh device snapshots, and distribute that shared state to all entities. The README’s 30-second sync and configurable polling interval are implemented here or through this layer.

6. Device capability modeling is centralized in `device_capabilities.py`. This file maps Lumos `deviceType` values to supported features such as on/off, brightness, RGB, and color temperature. Unknown types are intentionally surfaced via warnings so the integration can be extended without breaking existing devices.

7. `light.py` is the primary entity platform and represents controllable lighting devices in Home Assistant. Based on the README, it supports brightness, RGB, and tunable-white behavior depending on the capability record for each device.

8. `cover.py`, `binary_sensor.py`, and `sensor.py` indicate additional entity surfaces beyond lights. These platforms likely expose device state, availability, or specialized controls/telemetry where Lumos device models require it. They are separate because Home Assistant treats each entity class as a distinct UI/control surface.

9. The main runtime flow is:
   - user adds the integration in Home Assistant,
   - `config_flow.py` creates a config entry,
   - `api.py` authenticates against the Lumos cloud,
   - `coordinator.py` polls and refreshes device data,
   - the platform modules create/update entities from that shared dataset,
   - user actions in Home Assistant call back through `api.py` to the cloud.

10. State reconciliation is cloud-poll driven. The README explicitly mentions optimistic updates: the UI updates immediately after a command, then the next coordinator refresh reconciles the entity state with the cloud. That design balances responsiveness with eventual consistency.

11. There is a clear distinction between “command accepted” and “device physically updated.” The README notes the Lumos cloud can accept a command even when the mesh network is the real delivery path. Architecturally, that means the integration only controls and observes the cloud layer; it does not own the downstream mesh delivery guarantees.

12. `translations/`, `strings.json`, and the brand assets under `brand`/`brands` support Home Assistant’s UI and integration branding. These files are not part of the control path, but they matter for the setup/options experience and marketplace presentation.

13. In diagram terms, the important nodes are: Home Assistant core, Lumos config flow, shared coordinator, Lumos cloud API, and the entity platforms. The main data edge is periodic polling from cloud to coordinator to entities, with command edges flowing from entities back to the cloud.

14. This is a pure integration repository, not an application server or local device daemon. The key architectural decision is that it relies on Home Assistant’s async integration framework and external SaaS/cloud connectivity, with no local broker, message queue, or hardware driver layer in the repo.

Main entry points: [`custom_components/lumos/coordinator.py`](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/coordinator.py) (Coordinator), [`custom_components/lumos/device_capabilities.py`](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/device_capabilities.py) (Capabilities), [`custom_components/lumos/api.py`](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/api.py) (Cloud API), [`custom_components/lumos/__init__.py`](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/__init__.py) (Integration Init)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_home_assistant["Home Assistant"]
  node_ha_core["Home Assistant Core<br/>platform"]
end

subgraph group_lumos_integration["Lumos Integration"]
  node_entry_setup["Config Flow<br/>entry_setup<br/>[config_flow.py]"]
  node_integration_init["Integration Init<br/>bootstrap<br/>[__init__.py]"]
  node_state_sync["Coordinator<br/>polling_sync<br/>[coordinator.py]"]
  node_cloud_api["Cloud API<br/>backend_client<br/>[api.py]"]
  node_capabilities["Capabilities<br/>device_model"]
  node_lights(("Lights<br/>entity_platform<br/>[light.py]"))
  node_covers(("Covers<br/>entity_platform<br/>[cover.py]"))
  node_binary_sensors(("Binary Sensors<br/>entity_platform<br/>[binary_sensor.py]"))
  node_sensors(("Sensors<br/>entity_platform<br/>[sensor.py]"))
  node_manifest["Manifest<br/>integration_meta<br/>[manifest.json]"]
  node_strings["Strings<br/>ui_text<br/>[strings.json]"]
  node_brand_assets["Branding<br/>asset_pack"]
  node_translations["Translations<br/>localization<br/>[en.json]"]
end

subgraph group_distribution["Packaging"]
  node_hacs_packaging["HACS Pack<br/>distribution<br/>[hacs.json]"]
  node_gha_validation["Validation<br/>ci_workflow<br/>[hacs.yml]"]
end

node_ha_core -->|"starts setup"| node_entry_setup
node_entry_setup -->|"creates entry"| node_integration_init
node_integration_init -->|"builds client"| node_cloud_api
node_integration_init -->|"starts coordinator"| node_state_sync
node_state_sync -->|"polls cloud"| node_cloud_api
node_state_sync -->|"classifies devices"| node_capabilities
node_capabilities -->|"enables features"| node_lights
node_capabilities -->|"enables features"| node_covers
node_capabilities -->|"enables features"| node_binary_sensors
node_capabilities -->|"enables features"| node_sensors
node_state_sync -->|"updates state"| node_lights
node_state_sync -->|"updates state"| node_covers
node_state_sync -->|"updates state"| node_binary_sensors
node_state_sync -->|"updates state"| node_sensors
node_lights -->|"sends commands"| node_cloud_api
node_covers -->|"sends commands"| node_cloud_api
node_ha_core -->|"loads metadata"| node_manifest
node_ha_core -->|"shows UI text"| node_translations
node_ha_core -->|"shows branding"| node_brand_assets
node_hacs_packaging -->|"validated by"| node_gha_validation
node_manifest -->|"published with"| node_hacs_packaging

click node_entry_setup "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/config_flow.py"
click node_integration_init "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/__init__.py"
click node_state_sync "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/coordinator.py"
click node_cloud_api "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/api.py"
click node_capabilities "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/device_capabilities.py"
click node_lights "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/light.py"
click node_covers "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/cover.py"
click node_binary_sensors "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/binary_sensor.py"
click node_sensors "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/sensor.py"
click node_manifest "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/manifest.json"
click node_strings "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/strings.json"
click node_brand_assets "https://github.com/wisilicalumos/ha-lumos/tree/main/custom_components/lumos/brand"
click node_translations "https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/translations/en.json"
click node_hacs_packaging "https://github.com/wisilicalumos/ha-lumos/blob/main/hacs.json"
click node_gha_validation "https://github.com/wisilicalumos/ha-lumos/blob/main/.github/workflows/hacs.yml"

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_ha_core toneBlue
class node_entry_setup,node_integration_init,node_state_sync,node_cloud_api,node_capabilities,node_lights,node_covers,node_binary_sensors,node_sensors,node_manifest,node_strings,node_brand_assets,node_translations toneAmber
class node_hacs_packaging,node_gha_validation toneMint
```

## Components

### Home Assistant

Runtime and integration host

- **Home Assistant Core**: platform · Hosts the custom integration runtime and entity framework

### Lumos Integration

Custom integration under custom_components/lumos

- [Config Flow](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/config_flow.py): entry_setup · UI-based setup and account onboarding · `custom_components/lumos/config_flow.py`
- [Integration Init](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/__init__.py): bootstrap · Config-entry startup and wiring for each account · `custom_components/lumos/__init__.py`
- [Coordinator](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/coordinator.py): polling_sync · Shared polling and state distribution layer · `custom_components/lumos/coordinator.py`
- [Cloud API](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/api.py): backend_client · Authenticates, fetches devices, and sends commands to Lumos cloud · `custom_components/lumos/api.py`
- [Capabilities](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/device_capabilities.py): device_model · Maps Lumos device types to supported features · `custom_components/lumos/device_capabilities.py`
- [Lights](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/light.py): entity_platform · Primary lighting entities with brightness and color support · `custom_components/lumos/light.py`
- [Covers](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/cover.py): entity_platform · Cover-style entities for supported Lumos devices · `custom_components/lumos/cover.py`
- [Binary Sensors](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/binary_sensor.py): entity_platform · Boolean state surfaces for device conditions and availability · `custom_components/lumos/binary_sensor.py`
- [Sensors](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/sensor.py): entity_platform · Telemetry and status entities · `custom_components/lumos/sensor.py`
- [Manifest](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/manifest.json): integration_meta · Declares the Home Assistant custom integration · `custom_components/lumos/manifest.json`
- [Strings](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/strings.json): ui_text · Localized setup and entity text · `custom_components/lumos/strings.json`
- [Branding](https://github.com/wisilicalumos/ha-lumos/tree/main/custom_components/lumos/brand): asset_pack · Brand and logo assets for UI presentation · `custom_components/lumos/brand`
- [Translations](https://github.com/wisilicalumos/ha-lumos/blob/main/custom_components/lumos/translations/en.json): localization · Localized strings for the integration UI · `custom_components/lumos/translations/en.json`

### Packaging

HACS and validation support

- [HACS Pack](https://github.com/wisilicalumos/ha-lumos/blob/main/hacs.json): distribution · HACS metadata and repository packaging · `hacs.json`
- [Validation](https://github.com/wisilicalumos/ha-lumos/blob/main/.github/workflows/hacs.yml): ci_workflow · GitHub workflows for HACS and Home Assistant checks · `.github/workflows/hacs.yml`

## Connections

- Home Assistant Core → Config Flow: starts setup · Home Assistant launches the config flow
- Config Flow → Integration Init: creates entry · A successful flow creates a config entry
- Integration Init → Cloud API: builds client · Startup wires the cloud API client for the account
- Integration Init → Coordinator: starts coordinator · Config entry startup creates the shared refresh layer
- Coordinator → Cloud API: polls cloud · Coordinator refreshes device data from Lumos cloud
- Coordinator → Capabilities: classifies devices · Device snapshots are interpreted through capability mapping
- Capabilities → Lights: enables features · Capability records decide light feature support
- Capabilities → Covers: enables features · Capability records decide cover support
- Capabilities → Binary Sensors: enables features · Capability records decide binary sensor support
- Capabilities → Sensors: enables features · Capability records decide sensor support
- Coordinator → Lights: updates state · Entities read the shared coordinator snapshot
- Coordinator → Covers: updates state · Entities read the shared coordinator snapshot
- Coordinator → Binary Sensors: updates state · Entities read the shared coordinator snapshot
- Coordinator → Sensors: updates state · Entities read the shared coordinator snapshot
- Lights → Cloud API: sends commands · User actions are forwarded to the Lumos backend
- Covers → Cloud API: sends commands · Supported cover actions are forwarded to the cloud
- Home Assistant Core → Manifest: loads metadata · Home Assistant discovers the integration through its manifest
- Home Assistant Core → Translations: shows UI text · Home Assistant uses localized strings in setup and entities
- Home Assistant Core → Branding: shows branding · Brand assets support integration presentation
- HACS Pack → Validation: validated by · Packaging is checked by repository workflows
- Manifest → HACS Pack: published with · The integration is distributed as a HACS package
