# ngoviet/lumentreeha architecture

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

- Interactive diagram: https://gitdiagram.com/ngoviet/lumentreeha
- Repository: https://github.com/ngoviet/lumentreeha

## Overview

Lumentree Solar Inverter is a Home Assistant integration for real-time inverter telemetry and historical energy statistics. A user configures a device through the integration flow; setup initializes cloud/API and MQTT access, then Home Assistant entities expose live readings and daily, monthly, yearly, and lifetime statistics. The statistics path fetches and aggregates API data, persists cache data, and supplies period coordinators and sensors. The README documents extensive battery, grid, load, savings, and chart-series capabilities; some unsampled subsystem wiring is therefore represented only where supported by the tree and excerpts.

Main entry points: [`__init__.py`](https://github.com/ngoviet/lumentreeha/blob/main/__init__.py) (Entry lifecycle), [`core/mqtt_client.py`](https://github.com/ngoviet/lumentreeha/blob/main/core/mqtt_client.py) (MQTT client), [`services/aggregator.py`](https://github.com/ngoviet/lumentreeha/blob/main/services/aggregator.py) (Stats aggregator), [`entities/sensor.py`](https://github.com/ngoviet/lumentreeha/blob/main/entities/sensor.py) (Sensor entities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and integration"]
  node_config["Config flow<br/>[config_flow.py]"]
  node_integration["Entry lifecycle<br/>[__init__.py]"]
  node_api["HTTP API client<br/>[api_client.py]"]
end

subgraph group_realtime["Live telemetry"]
  node_mqtt["MQTT client<br/>[mqtt_client.py]"]
  node_parser["Realtime parser<br/>[realtime_parser.py]"]
end

subgraph group_statistics["Energy statistics"]
  node_daily["Daily coordinator"]
  node_monthly["Monthly coordinator"]
  node_yearly["Yearly coordinator"]
  node_total["Lifetime coordinator"]
  node_aggregator["Stats aggregator<br/>[aggregator.py]"]
  node_cache[("Stats cache<br/>[cache.py]")]
  node_backfill["Backfill services<br/>[smart_backfill.py]"]
end

subgraph group_presentation["Home Assistant entities"]
  node_sensors["Sensor entities<br/>[sensor.py]"]
  node_binary["Binary sensors<br/>[binary_sensor.py]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
end

node_user(("Home Assistant user"))
node_ha(("Home Assistant"))
node_cloud(("Lumentree API"))
node_broker(("MQTT broker"))
node_inverter(("Solar inverter"))

node_user -->|"configures"| node_config
node_config -->|"registers entry"| node_ha
node_ha -->|"sets up entry"| node_integration
node_integration -->|"fetches device info"| node_api
node_api -->|"requests data"| node_cloud
node_integration -->|"starts client"| node_mqtt
node_mqtt -->|"connects"| node_broker
node_broker -->|"delivers frames"| node_mqtt
node_inverter -->|"publishes telemetry"| node_broker
node_mqtt -->|"publishes reads"| node_inverter
node_mqtt -->|"parses payload"| node_parser
node_mqtt -->|"dispatches updates"| node_ha
node_integration -->|"creates aggregator"| node_aggregator
node_daily -->|"fetches daily stats"| node_aggregator
node_monthly -->|"fills period data"| node_aggregator
node_yearly -->|"fetches yearly data"| node_api
node_yearly -->|"reads cached totals"| node_cache
node_total -->|"reads lifetime data"| node_cache
node_aggregator -->|"fetches history"| node_api
node_aggregator -->|"updates cache"| node_cache
node_backfill -->|"runs backfill"| node_aggregator
node_backfill -->|"purges cache"| node_cache
node_integration -->|"creates coordinator"| node_daily
node_integration -->|"creates coordinator"| node_monthly
node_integration -->|"creates coordinator"| node_yearly
node_integration -->|"creates coordinator"| node_total
node_ha -->|"sets up entities"| node_sensors
node_ha -->|"sets up entities"| node_binary
node_mqtt -->|"updates live state"| node_sensors
node_mqtt -->|"updates status"| node_binary
node_daily -->|"provides stats"| node_sensors
node_monthly -->|"provides stats"| node_sensors
node_yearly -->|"provides stats"| node_sensors
node_total -->|"provides stats"| node_sensors
node_ha -->|"requests diagnostics"| node_diagnostics

click node_config "https://github.com/ngoviet/lumentreeha/blob/main/config_flow.py"
click node_integration "https://github.com/ngoviet/lumentreeha/blob/main/__init__.py"
click node_api "https://github.com/ngoviet/lumentreeha/blob/main/core/api_client.py"
click node_mqtt "https://github.com/ngoviet/lumentreeha/blob/main/core/mqtt_client.py"
click node_parser "https://github.com/ngoviet/lumentreeha/blob/main/core/realtime_parser.py"
click node_daily "https://github.com/ngoviet/lumentreeha/blob/main/coordinators/daily_coordinator.py"
click node_monthly "https://github.com/ngoviet/lumentreeha/blob/main/coordinators/monthly_coordinator.py"
click node_yearly "https://github.com/ngoviet/lumentreeha/blob/main/coordinators/yearly_coordinator.py"
click node_total "https://github.com/ngoviet/lumentreeha/blob/main/coordinators/total_coordinator.py"
click node_aggregator "https://github.com/ngoviet/lumentreeha/blob/main/services/aggregator.py"
click node_cache "https://github.com/ngoviet/lumentreeha/blob/main/services/cache.py"
click node_backfill "https://github.com/ngoviet/lumentreeha/blob/main/services/smart_backfill.py"
click node_sensors "https://github.com/ngoviet/lumentreeha/blob/main/entities/sensor.py"
click node_binary "https://github.com/ngoviet/lumentreeha/blob/main/entities/binary_sensor.py"
click node_diagnostics "https://github.com/ngoviet/lumentreeha/blob/main/diagnostics.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_config,node_integration,node_api,node_user toneBlue
class node_mqtt,node_parser toneAmber
class node_daily,node_monthly,node_yearly,node_total,node_aggregator,node_cache,node_backfill,node_cloud toneMint
class node_sensors,node_binary,node_diagnostics toneRose
class node_ha,node_broker,node_inverter toneIndigo
```

## Components

### Setup and integration

- [Config flow](https://github.com/ngoviet/lumentreeha/blob/main/config_flow.py): `config_flow.py`
- [Entry lifecycle](https://github.com/ngoviet/lumentreeha/blob/main/__init__.py): `__init__.py`
- [HTTP API client](https://github.com/ngoviet/lumentreeha/blob/main/core/api_client.py): `core/api_client.py`

### Live telemetry

- [MQTT client](https://github.com/ngoviet/lumentreeha/blob/main/core/mqtt_client.py): `core/mqtt_client.py`
- [Realtime parser](https://github.com/ngoviet/lumentreeha/blob/main/core/realtime_parser.py): `core/realtime_parser.py`

### Energy statistics

- [Daily coordinator](https://github.com/ngoviet/lumentreeha/blob/main/coordinators/daily_coordinator.py): `coordinators/daily_coordinator.py`
- [Monthly coordinator](https://github.com/ngoviet/lumentreeha/blob/main/coordinators/monthly_coordinator.py): `coordinators/monthly_coordinator.py`
- [Yearly coordinator](https://github.com/ngoviet/lumentreeha/blob/main/coordinators/yearly_coordinator.py): `coordinators/yearly_coordinator.py`
- [Lifetime coordinator](https://github.com/ngoviet/lumentreeha/blob/main/coordinators/total_coordinator.py): `coordinators/total_coordinator.py`
- [Stats aggregator](https://github.com/ngoviet/lumentreeha/blob/main/services/aggregator.py): `services/aggregator.py`
- [Stats cache](https://github.com/ngoviet/lumentreeha/blob/main/services/cache.py): `services/cache.py`
- [Backfill services](https://github.com/ngoviet/lumentreeha/blob/main/services/smart_backfill.py): `services/smart_backfill.py`

### Home Assistant entities

- [Sensor entities](https://github.com/ngoviet/lumentreeha/blob/main/entities/sensor.py): `entities/sensor.py`
- [Binary sensors](https://github.com/ngoviet/lumentreeha/blob/main/entities/binary_sensor.py): `entities/binary_sensor.py`
- [Diagnostics](https://github.com/ngoviet/lumentreeha/blob/main/diagnostics.py): `diagnostics.py`

### Other components

- **Home Assistant user**
- **Home Assistant**
- **Lumentree API**
- **MQTT broker**
- **Solar inverter**

## Connections

- Home Assistant user → Config flow: configures
- Config flow → Home Assistant: registers entry
- Home Assistant → Entry lifecycle: sets up entry
- Entry lifecycle → HTTP API client: fetches device info
- HTTP API client → Lumentree API: requests data
- Entry lifecycle → MQTT client: starts client
- MQTT client → MQTT broker: connects
- MQTT broker → MQTT client: delivers frames
- Solar inverter → MQTT broker: publishes telemetry
- MQTT client → Solar inverter: publishes reads
- MQTT client → Realtime parser: parses payload
- MQTT client → Home Assistant: dispatches updates
- Entry lifecycle → Stats aggregator: creates aggregator
- Daily coordinator → Stats aggregator: fetches daily stats
- Monthly coordinator → Stats aggregator: fills period data
- Yearly coordinator → HTTP API client: fetches yearly data
- Yearly coordinator → Stats cache: reads cached totals
- Lifetime coordinator → Stats cache: reads lifetime data
- Stats aggregator → HTTP API client: fetches history
- Stats aggregator → Stats cache: updates cache
- Backfill services → Stats aggregator: runs backfill
- Backfill services → Stats cache: purges cache
- Entry lifecycle → Daily coordinator: creates coordinator
- Entry lifecycle → Monthly coordinator: creates coordinator
- Entry lifecycle → Yearly coordinator: creates coordinator
- Entry lifecycle → Lifetime coordinator: creates coordinator
- Home Assistant → Sensor entities: sets up entities
- Home Assistant → Binary sensors: sets up entities
- MQTT client → Sensor entities: updates live state
- MQTT client → Binary sensors: updates status
- Daily coordinator → Sensor entities: provides stats
- Monthly coordinator → Sensor entities: provides stats
- Yearly coordinator → Sensor entities: provides stats
- Lifetime coordinator → Sensor entities: provides stats
- Home Assistant → Diagnostics: requests diagnostics