# hoangquan90/lumentreeha architecture

> Architecture diagram of the GitHub repository hoangquan90/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/hoangquan90/lumentreeha
- Repository: https://github.com/hoangquan90/lumentreeha

## Overview

This is a Home Assistant integration for Lumentree hybrid solar inverters. A user configures a device; the integration retrieves device information over HTTP, connects to the inverter over MQTT, parses live Modbus readings, and exposes them as Home Assistant entities. Separately, HTTP statistics are fetched and cached to provide daily, monthly, yearly, and lifetime energy and savings. The graph reflects the sampled setup, client, parser, cache, and entity code plus major README capabilities; some coordinator and platform wiring is documented but not sampled, so uncertain links are omitted.

Main entry points: [`__init__.py`](https://github.com/hoangquan90/lumentreeha/blob/main/__init__.py) (Entry Runtime), [`services/aggregator.py`](https://github.com/hoangquan90/lumentreeha/blob/main/services/aggregator.py) (Stats Aggregator), [`entities/sensor.py`](https://github.com/hoangquan90/lumentreeha/blob/main/entities/sensor.py) (Sensor Entities), [`core/mqtt_client.py`](https://github.com/hoangquan90/lumentreeha/blob/main/core/mqtt_client.py) (MQTT Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Integration Setup"]
  node_config["Config Flow<br/>[config_flow.py]"]
  node_integration["Entry Runtime<br/>[__init__.py]"]
  node_http["HTTP API Client<br/>[api_client.py]"]
end

subgraph group_realtime["Live Monitoring"]
  node_mqtt_client["MQTT Client<br/>[mqtt_client.py]"]
  node_parser["Realtime Parser<br/>[realtime_parser.py]"]
  node_dispatcher["Update Dispatcher<br/>[mqtt_client.py]"]
end

subgraph group_statistics["Energy Statistics"]
  node_aggregator["Stats Aggregator<br/>[aggregator.py]"]
  node_cache[("Statistics Cache<br/>[cache.py]")]
  node_daily["Daily Coordinator"]
  node_monthly["Monthly Coordinator"]
  node_yearly["Yearly Coordinator"]
  node_total["Lifetime Coordinator"]
  node_service["Backfill Services<br/>[__init__.py]"]
end

subgraph group_platform["Home Assistant Entities"]
  node_sensor["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_api_service["Lumentree HTTP API"]
node_inverter["Lumentree Inverter"]

node_user -->|"configures"| node_config
node_config -->|"sets up entry"| node_integration
node_integration -->|"creates"| node_http
node_integration -->|"starts"| node_mqtt_client
node_integration -->|"creates"| node_aggregator
node_integration -->|"creates"| node_daily
node_integration -->|"creates"| node_monthly
node_integration -->|"creates"| node_yearly
node_integration -->|"creates"| node_total
node_http -->|"requests data"| node_api_service
node_mqtt_client -->|"connects and polls"| node_inverter
node_inverter -->|"sends readings"| node_mqtt_client
node_mqtt_client -->|"parses payload"| node_parser
node_mqtt_client -->|"dispatches updates"| node_dispatcher
node_dispatcher -->|"updates live sensors"| node_sensor
node_dispatcher -->|"updates status"| node_binary
node_aggregator -->|"fetches statistics"| node_http
node_aggregator -->|"reads and writes"| node_cache
node_daily -->|"fetches daily data"| node_http
node_daily -->|"finalizes daily data"| node_cache
node_monthly -->|"gets aggregates"| node_aggregator
node_yearly -->|"gets aggregates"| node_aggregator
node_total -->|"loads yearly data"| node_aggregator
node_sensor -->|"reads updates"| node_daily
node_sensor -->|"reads updates"| node_monthly
node_sensor -->|"reads updates"| node_yearly
node_sensor -->|"reads updates"| node_total
node_integration -->|"registers services"| node_service
node_service -->|"runs backfill"| node_aggregator
node_service -->|"purges cache"| node_cache
node_integration -.->|"provides entry data"| node_diagnostics
node_ha -->|"hosts integration"| node_integration

click node_config "https://github.com/hoangquan90/lumentreeha/blob/main/config_flow.py"
click node_integration "https://github.com/hoangquan90/lumentreeha/blob/main/__init__.py"
click node_http "https://github.com/hoangquan90/lumentreeha/blob/main/core/api_client.py"
click node_mqtt_client "https://github.com/hoangquan90/lumentreeha/blob/main/core/mqtt_client.py"
click node_parser "https://github.com/hoangquan90/lumentreeha/blob/main/core/realtime_parser.py"
click node_dispatcher "https://github.com/hoangquan90/lumentreeha/blob/main/core/mqtt_client.py"
click node_aggregator "https://github.com/hoangquan90/lumentreeha/blob/main/services/aggregator.py"
click node_cache "https://github.com/hoangquan90/lumentreeha/blob/main/services/cache.py"
click node_daily "https://github.com/hoangquan90/lumentreeha/blob/main/coordinators/daily_coordinator.py"
click node_monthly "https://github.com/hoangquan90/lumentreeha/blob/main/coordinators/monthly_coordinator.py"
click node_yearly "https://github.com/hoangquan90/lumentreeha/blob/main/coordinators/yearly_coordinator.py"
click node_total "https://github.com/hoangquan90/lumentreeha/blob/main/coordinators/total_coordinator.py"
click node_sensor "https://github.com/hoangquan90/lumentreeha/blob/main/entities/sensor.py"
click node_binary "https://github.com/hoangquan90/lumentreeha/blob/main/entities/binary_sensor.py"
click node_service "https://github.com/hoangquan90/lumentreeha/blob/main/__init__.py"
click node_diagnostics "https://github.com/hoangquan90/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_http,node_user toneBlue
class node_mqtt_client,node_parser,node_dispatcher toneAmber
class node_aggregator,node_cache,node_daily,node_monthly,node_yearly,node_total,node_service,node_api_service toneMint
class node_sensor,node_binary,node_diagnostics toneRose
class node_ha,node_inverter toneIndigo
```

## Components

### Integration Setup

- [Config Flow](https://github.com/hoangquan90/lumentreeha/blob/main/config_flow.py): `config_flow.py`
- [Entry Runtime](https://github.com/hoangquan90/lumentreeha/blob/main/__init__.py): `__init__.py`
- [HTTP API Client](https://github.com/hoangquan90/lumentreeha/blob/main/core/api_client.py): `core/api_client.py`

### Live Monitoring

- [MQTT Client](https://github.com/hoangquan90/lumentreeha/blob/main/core/mqtt_client.py): `core/mqtt_client.py`
- [Realtime Parser](https://github.com/hoangquan90/lumentreeha/blob/main/core/realtime_parser.py): `core/realtime_parser.py`
- [Update Dispatcher](https://github.com/hoangquan90/lumentreeha/blob/main/core/mqtt_client.py): `core/mqtt_client.py`

### Energy Statistics

- [Stats Aggregator](https://github.com/hoangquan90/lumentreeha/blob/main/services/aggregator.py): `services/aggregator.py`
- [Statistics Cache](https://github.com/hoangquan90/lumentreeha/blob/main/services/cache.py): `services/cache.py`
- [Daily Coordinator](https://github.com/hoangquan90/lumentreeha/blob/main/coordinators/daily_coordinator.py): `coordinators/daily_coordinator.py`
- [Monthly Coordinator](https://github.com/hoangquan90/lumentreeha/blob/main/coordinators/monthly_coordinator.py): `coordinators/monthly_coordinator.py`
- [Yearly Coordinator](https://github.com/hoangquan90/lumentreeha/blob/main/coordinators/yearly_coordinator.py): `coordinators/yearly_coordinator.py`
- [Lifetime Coordinator](https://github.com/hoangquan90/lumentreeha/blob/main/coordinators/total_coordinator.py): `coordinators/total_coordinator.py`
- [Backfill Services](https://github.com/hoangquan90/lumentreeha/blob/main/__init__.py): `__init__.py`

### Home Assistant Entities

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

### Other components

- **Home Assistant User**
- **Home Assistant**
- **Lumentree HTTP API**
- **Lumentree Inverter**

## Connections

- Home Assistant User → Config Flow: configures
- Config Flow → Entry Runtime: sets up entry
- Entry Runtime → HTTP API Client: creates
- Entry Runtime → MQTT Client: starts
- Entry Runtime → Stats Aggregator: creates
- Entry Runtime → Daily Coordinator: creates
- Entry Runtime → Monthly Coordinator: creates
- Entry Runtime → Yearly Coordinator: creates
- Entry Runtime → Lifetime Coordinator: creates
- HTTP API Client → Lumentree HTTP API: requests data
- MQTT Client → Lumentree Inverter: connects and polls
- Lumentree Inverter → MQTT Client: sends readings
- MQTT Client → Realtime Parser: parses payload
- MQTT Client → Update Dispatcher: dispatches updates
- Update Dispatcher → Sensor Entities: updates live sensors
- Update Dispatcher → Binary Sensors: updates status
- Stats Aggregator → HTTP API Client: fetches statistics
- Stats Aggregator → Statistics Cache: reads and writes
- Daily Coordinator → HTTP API Client: fetches daily data
- Daily Coordinator → Statistics Cache: finalizes daily data
- Monthly Coordinator → Stats Aggregator: gets aggregates
- Yearly Coordinator → Stats Aggregator: gets aggregates
- Lifetime Coordinator → Stats Aggregator: loads yearly data
- Sensor Entities → Daily Coordinator: reads updates
- Sensor Entities → Monthly Coordinator: reads updates
- Sensor Entities → Yearly Coordinator: reads updates
- Sensor Entities → Lifetime Coordinator: reads updates
- Entry Runtime → Backfill Services: registers services
- Backfill Services → Stats Aggregator: runs backfill
- Backfill Services → Statistics Cache: purges cache
- Entry Runtime → Diagnostics: provides entry data
- Home Assistant → Entry Runtime: hosts integration