# minlor/lumisync architecture

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

- Interactive diagram: https://gitdiagram.com/minlor/lumisync
- Repository: https://github.com/minlor/lumisync

## Overview

LumiSync is a desktop smart-device controller and ambient-light synchronization app. Users discover or link devices, inspect capabilities, control supported features, and optionally run screen- or music-driven lighting; local and cloud transports provide distinct device paths. The graph also includes account authorization and plug-energy reporting, plus the synchronization processing layer. Relationships are limited to README statements and source-index references; several UI and integration details are unsampled, so their internal links are not inferred.

Main entry points: [`lumisync/gui/controllers/device_controller.py`](https://github.com/minlor/lumisync/blob/main/lumisync/gui/controllers/device_controller.py) (Device management), [`lumisync/drivers/registry.py`](https://github.com/minlor/lumisync/blob/main/lumisync/drivers/registry.py) (Driver selection), [`lumisync/gui/main_window.py`](https://github.com/minlor/lumisync/blob/main/lumisync/gui/main_window.py) (Main window), [`lumisync/gui/controllers/sync_controller.py`](https://github.com/minlor/lumisync/blob/main/lumisync/gui/controllers/sync_controller.py) (Sync controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop app"]
  node_window["Main window<br/>[main_window.py]"]
  node_device_ui["Device management"]
  node_sync_ui["Sync controls<br/>[sync_controller.py]"]
  node_accounts_ui["Account dialog<br/>[accounts_dialog.py]"]
  node_logging["Logging<br/>[logging.py]"]
end

subgraph group_devices["Devices and accounts"]
  node_account_mgr["Account sessions<br/>[manager.py]"]
  node_govee["Govee accounts<br/>[govee.py]"]
  node_tuya["Tuya accounts<br/>[tuya.py]"]
  node_tuya_energy["Energy history<br/>[tuya_energy.py]"]
  node_discovery["LAN discovery<br/>[connection.py]"]
  node_device_catalog["Device inventory<br/>[devices.py]"]
  node_settings["Runtime settings<br/>[options.py]"]
end

subgraph group_sync["Light synchronization"]
  node_mapping["LED mapping<br/>[led_mapping.py]"]
  node_monitor["Monitor sync<br/>[monitor.py]"]
  node_music["Music sync<br/>[music.py]"]
  node_audio["Audio analysis<br/>[audio.py]"]
  node_processing["Color processing<br/>[processing.py]"]
  node_colors["Color utilities<br/>[colors.py]"]
end

subgraph group_transport["Device transports"]
  node_pool["Driver pool<br/>[pool.py]"]
  node_registry["Driver selection<br/>[registry.py]"]
  node_driver_base["Transport interface<br/>[base.py]"]
  node_lan_driver["LAN drivers<br/>[govee_lan.py]"]
  node_ble_driver["Bluetooth driver<br/>[idotmatrix_ble.py]"]
  node_cloud_driver["Cloud driver<br/>[cloud.py]"]
  node_tuya_driver["Tuya LAN driver<br/>[tuya_lan.py]"]
end

node_user(("User"))
node_device{{"Smart devices"}}
node_audio_input(("Audio input"))

node_user -->|"uses"| node_window
node_window -->|"connects"| node_device_ui
node_window -->|"connects"| node_sync_ui
node_window -->|"opens"| node_accounts_ui
node_device_ui -->|"discovers"| node_discovery
node_device_ui -->|"merges devices"| node_device_catalog
node_device_ui -->|"controls through"| node_pool
node_accounts_ui -->|"manages sessions"| node_account_mgr
node_account_mgr -->|"creates clients"| node_govee
node_account_mgr -->|"creates clients"| node_tuya
node_tuya -->|"loads readings"| node_tuya_energy
node_device_ui -->|"refreshes accounts"| node_account_mgr
node_sync_ui -->|"runs"| node_monitor
node_sync_ui -->|"runs"| node_music
node_sync_ui -->|"sends output via"| node_pool
node_monitor -->|"maps display regions"| node_mapping
node_monitor -->|"processes frames"| node_processing
node_music -->|"analyzes audio"| node_audio
node_music -->|"processes frames"| node_processing
node_music -->|"uses layouts"| node_mapping
node_audio_input -.->|"provides samples"| node_audio
node_pool -->|"selects drivers"| node_registry
node_registry -->|"implements interface"| node_driver_base
node_registry -->|"selects"| node_lan_driver
node_registry -->|"selects"| node_ble_driver
node_registry -->|"selects"| node_cloud_driver
node_registry -->|"selects"| node_tuya_driver
node_pool -.->|"commands"| node_device
node_device_ui -->|"uses configuration"| node_settings
node_sync_ui -->|"reads tunables"| node_settings
node_processing -.->|"uses color helpers"| node_colors
node_window -->|"logs activity"| node_logging

click node_window "https://github.com/minlor/lumisync/blob/main/lumisync/gui/main_window.py"
click node_device_ui "https://github.com/minlor/lumisync/blob/main/lumisync/gui/controllers/device_controller.py"
click node_sync_ui "https://github.com/minlor/lumisync/blob/main/lumisync/gui/controllers/sync_controller.py"
click node_accounts_ui "https://github.com/minlor/lumisync/blob/main/lumisync/gui/dialogs/accounts_dialog.py"
click node_account_mgr "https://github.com/minlor/lumisync/blob/main/lumisync/accounts/manager.py"
click node_govee "https://github.com/minlor/lumisync/blob/main/lumisync/accounts/govee.py"
click node_tuya "https://github.com/minlor/lumisync/blob/main/lumisync/accounts/tuya.py"
click node_tuya_energy "https://github.com/minlor/lumisync/blob/main/lumisync/accounts/tuya_energy.py"
click node_discovery "https://github.com/minlor/lumisync/blob/main/lumisync/connection.py"
click node_device_catalog "https://github.com/minlor/lumisync/blob/main/lumisync/devices.py"
click node_settings "https://github.com/minlor/lumisync/blob/main/lumisync/config/options.py"
click node_mapping "https://github.com/minlor/lumisync/blob/main/lumisync/led_mapping.py"
click node_monitor "https://github.com/minlor/lumisync/blob/main/lumisync/sync/monitor.py"
click node_music "https://github.com/minlor/lumisync/blob/main/lumisync/sync/music.py"
click node_audio "https://github.com/minlor/lumisync/blob/main/lumisync/sync/audio.py"
click node_processing "https://github.com/minlor/lumisync/blob/main/lumisync/sync/processing.py"
click node_pool "https://github.com/minlor/lumisync/blob/main/lumisync/drivers/pool.py"
click node_registry "https://github.com/minlor/lumisync/blob/main/lumisync/drivers/registry.py"
click node_driver_base "https://github.com/minlor/lumisync/blob/main/lumisync/drivers/base.py"
click node_lan_driver "https://github.com/minlor/lumisync/blob/main/lumisync/drivers/govee_lan.py"
click node_ble_driver "https://github.com/minlor/lumisync/blob/main/lumisync/drivers/idotmatrix_ble.py"
click node_cloud_driver "https://github.com/minlor/lumisync/blob/main/lumisync/drivers/cloud.py"
click node_tuya_driver "https://github.com/minlor/lumisync/blob/main/lumisync/drivers/tuya_lan.py"
click node_colors "https://github.com/minlor/lumisync/blob/main/lumisync/utils/colors.py"
click node_logging "https://github.com/minlor/lumisync/blob/main/lumisync/utils/logging.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_window,node_device_ui,node_sync_ui,node_accounts_ui,node_logging,node_user toneBlue
class node_account_mgr,node_govee,node_tuya,node_tuya_energy,node_discovery,node_device_catalog,node_settings toneAmber
class node_mapping,node_monitor,node_music,node_audio,node_processing,node_colors toneMint
class node_pool,node_registry,node_driver_base,node_lan_driver,node_ble_driver,node_cloud_driver,node_tuya_driver toneRose
class node_device,node_audio_input toneIndigo
```

## Components

### Desktop app

- [Main window](https://github.com/minlor/lumisync/blob/main/lumisync/gui/main_window.py): `lumisync/gui/main_window.py`
- [Device management](https://github.com/minlor/lumisync/blob/main/lumisync/gui/controllers/device_controller.py): `lumisync/gui/controllers/device_controller.py`
- [Sync controls](https://github.com/minlor/lumisync/blob/main/lumisync/gui/controllers/sync_controller.py): `lumisync/gui/controllers/sync_controller.py`
- [Account dialog](https://github.com/minlor/lumisync/blob/main/lumisync/gui/dialogs/accounts_dialog.py): `lumisync/gui/dialogs/accounts_dialog.py`
- [Logging](https://github.com/minlor/lumisync/blob/main/lumisync/utils/logging.py): `lumisync/utils/logging.py`

### Devices and accounts

- [Account sessions](https://github.com/minlor/lumisync/blob/main/lumisync/accounts/manager.py): `lumisync/accounts/manager.py`
- [Govee accounts](https://github.com/minlor/lumisync/blob/main/lumisync/accounts/govee.py): `lumisync/accounts/govee.py`
- [Tuya accounts](https://github.com/minlor/lumisync/blob/main/lumisync/accounts/tuya.py): `lumisync/accounts/tuya.py`
- [Energy history](https://github.com/minlor/lumisync/blob/main/lumisync/accounts/tuya_energy.py): `lumisync/accounts/tuya_energy.py`
- [LAN discovery](https://github.com/minlor/lumisync/blob/main/lumisync/connection.py): `lumisync/connection.py`
- [Device inventory](https://github.com/minlor/lumisync/blob/main/lumisync/devices.py): `lumisync/devices.py`
- [Runtime settings](https://github.com/minlor/lumisync/blob/main/lumisync/config/options.py): `lumisync/config/options.py`

### Light synchronization

- [LED mapping](https://github.com/minlor/lumisync/blob/main/lumisync/led_mapping.py): `lumisync/led_mapping.py`
- [Monitor sync](https://github.com/minlor/lumisync/blob/main/lumisync/sync/monitor.py): `lumisync/sync/monitor.py`
- [Music sync](https://github.com/minlor/lumisync/blob/main/lumisync/sync/music.py): `lumisync/sync/music.py`
- [Audio analysis](https://github.com/minlor/lumisync/blob/main/lumisync/sync/audio.py): `lumisync/sync/audio.py`
- [Color processing](https://github.com/minlor/lumisync/blob/main/lumisync/sync/processing.py): `lumisync/sync/processing.py`
- [Color utilities](https://github.com/minlor/lumisync/blob/main/lumisync/utils/colors.py): `lumisync/utils/colors.py`

### Device transports

- [Driver pool](https://github.com/minlor/lumisync/blob/main/lumisync/drivers/pool.py): `lumisync/drivers/pool.py`
- [Driver selection](https://github.com/minlor/lumisync/blob/main/lumisync/drivers/registry.py): `lumisync/drivers/registry.py`
- [Transport interface](https://github.com/minlor/lumisync/blob/main/lumisync/drivers/base.py): `lumisync/drivers/base.py`
- [LAN drivers](https://github.com/minlor/lumisync/blob/main/lumisync/drivers/govee_lan.py): `lumisync/drivers/govee_lan.py`
- [Bluetooth driver](https://github.com/minlor/lumisync/blob/main/lumisync/drivers/idotmatrix_ble.py): `lumisync/drivers/idotmatrix_ble.py`
- [Cloud driver](https://github.com/minlor/lumisync/blob/main/lumisync/drivers/cloud.py): `lumisync/drivers/cloud.py`
- [Tuya LAN driver](https://github.com/minlor/lumisync/blob/main/lumisync/drivers/tuya_lan.py): `lumisync/drivers/tuya_lan.py`

### Other components

- **User**
- **Smart devices**
- **Audio input**

## Connections

- User → Main window: uses (evidence: `README.md`)
- Main window → Device management: connects (evidence: `lumisync/gui/main_window.py`)
- Main window → Sync controls: connects (evidence: `lumisync/gui/main_window.py`)
- Main window → Account dialog: opens (evidence: `README.md`)
- Device management → LAN discovery: discovers (evidence: `lumisync/gui/controllers/device_controller.py`)
- Device management → Device inventory: merges devices (evidence: `lumisync/gui/controllers/device_controller.py`)
- Device management → Driver pool: controls through (evidence: `lumisync/gui/controllers/device_controller.py`)
- Account dialog → Account sessions: manages sessions (evidence: `lumisync/gui/dialogs/accounts_dialog.py`)
- Account sessions → Govee accounts: creates clients (evidence: `lumisync/accounts/manager.py`)
- Account sessions → Tuya accounts: creates clients (evidence: `lumisync/accounts/manager.py`)
- Tuya accounts → Energy history: loads readings (evidence: `lumisync/accounts/tuya.py`)
- Device management → Account sessions: refreshes accounts (evidence: `lumisync/gui/controllers/device_controller.py`)
- Sync controls → Monitor sync: runs (evidence: `lumisync/gui/controllers/sync_controller.py`)
- Sync controls → Music sync: runs (evidence: `lumisync/gui/controllers/sync_controller.py`)
- Sync controls → Driver pool: sends output via (evidence: `lumisync/gui/controllers/sync_controller.py`)
- Monitor sync → LED mapping: maps display regions (evidence: `lumisync/sync/monitor.py`)
- Monitor sync → Color processing: processes frames (evidence: `lumisync/sync/monitor.py`)
- Music sync → Audio analysis: analyzes audio (evidence: `lumisync/sync/music.py`)
- Music sync → Color processing: processes frames (evidence: `lumisync/sync/music.py`)
- Music sync → LED mapping: uses layouts
- Audio input → Audio analysis: provides samples
- Driver pool → Driver selection: selects drivers (evidence: `lumisync/drivers/pool.py`)
- Driver selection → Transport interface: implements interface (evidence: `lumisync/drivers/registry.py`)
- Driver selection → LAN drivers: selects (evidence: `lumisync/drivers/registry.py`)
- Driver selection → Bluetooth driver: selects (evidence: `lumisync/drivers/registry.py`)
- Driver selection → Cloud driver: selects (evidence: `lumisync/drivers/registry.py`)
- Driver selection → Tuya LAN driver: selects (evidence: `lumisync/drivers/registry.py`)
- Driver pool → Smart devices: commands
- Device management → Runtime settings: uses configuration (evidence: `lumisync/gui/controllers/device_controller.py`)
- Sync controls → Runtime settings: reads tunables (evidence: `lumisync/gui/controllers/sync_controller.py`)
- Color processing → Color utilities: uses color helpers
- Main window → Logging: logs activity (evidence: `lumisync/gui/main_window.py`)
