# partach/ha_felicity architecture

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

- Interactive diagram: https://gitdiagram.com/partach/ha_felicity
- Repository: https://github.com/partach/ha_felicity

## Overview

HA-Felicity is a Home Assistant integration for monitoring and controlling Felicity inverters over Modbus, with an optional energy-management workflow that schedules charging, selling, and flexible loads from prices, solar forecasts, and battery state. Users add an inverter through the UI, then Home Assistant polls and exposes device entities; the coordinator applies EMS schedules and controls the inverter. The README also documents two Lovelace cards, multi-inverter support, and serial/TCP connectivity. EMS logic and entity wiring are only partially sampled, so uncertain implementation links are omitted.

Main entry points: [`custom_components/ha_felicity/coordinator.py`](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/coordinator.py) (Update coordinator), [`custom_components/ha_felicity/type_specific.py`](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/type_specific.py) (Model register maps), [`custom_components/ha_felicity/config_flow.py`](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/config_flow.py) (Config flow), [`custom_components/ha_felicity/__init__.py`](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/__init__.py) (Integration setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and lifecycle"]
  node_config["Config flow<br/>[config_flow.py]"]
  node_integration["Integration setup<br/>[__init__.py]"]
  node_coordinator["Update coordinator<br/>[coordinator.py]"]
end

subgraph group_device["Inverter access"]
  node_registers["Model register maps<br/>[type_specific.py]"]
  node_trex5["T-REX 5K map<br/>[trex_five.py]"]
  node_trex10["T-REX 10K map<br/>[trex_ten.py]"]
  node_trex25["T-REX 25K map"]
  node_trex50["T-REX 50K map<br/>[trex_fifty.py]"]
  node_ivgm["IVGM maps<br/>[ivgm.py]"]
end

subgraph group_ems["Energy management"]
  node_ems["EMS scheduler<br/>[ems.py]"]
  node_milp["MILP engine<br/>[milp.py]"]
end

subgraph group_interface["Home Assistant interface"]
  node_entities["Device entities<br/>[sensor.py]"]
  node_controls["Control entities<br/>[number.py]"]
  node_boost["EV boost button<br/>[button.py]"]
  node_card["Inverter dashboard card<br/>[ha_felicity.js]"]
  node_emscard["EMS dashboard card<br/>[ha_felicity_ems.js]"]
end

node_user(("Home Assistant user"))
node_ha["Home Assistant"]
node_inverter["Felicity inverter"]
node_energy_inputs["Price and forecast inputs"]

node_user -->|"configures"| node_config
node_config -->|"creates entry"| node_integration
node_integration -->|"sets up"| node_coordinator
node_coordinator -->|"selects model"| node_registers
node_registers -->|"uses map"| node_trex5
node_registers -->|"uses map"| node_trex10
node_registers -->|"uses map"| node_trex25
node_registers -->|"uses map"| node_trex50
node_registers -->|"uses map"| node_ivgm
node_coordinator -->|"reads and writes Modbus"| node_inverter
node_coordinator -->|"reads prices and forecasts"| node_energy_inputs
node_coordinator -->|"calculates schedule"| node_ems
node_coordinator -.->|"invokes when selected"| node_milp
node_coordinator -->|"updates state"| node_entities
node_coordinator -->|"handles control"| node_controls
node_coordinator -->|"handles boost"| node_boost
node_ha -->|"runs integration"| node_coordinator
node_ha -->|"hosts card"| node_card
node_ha -->|"hosts card"| node_emscard
node_card -->|"reads entities and calls services"| node_ha
node_emscard -->|"reads entities and calls services"| node_ha
node_energy_inputs -.->|"provided by integrations"| node_ha

click node_config "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/config_flow.py"
click node_integration "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/__init__.py"
click node_coordinator "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/coordinator.py"
click node_registers "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/type_specific.py"
click node_trex5 "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/trex_five.py"
click node_trex10 "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/trex_ten.py"
click node_trex25 "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/trex_twenty_five.py"
click node_trex50 "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/trex_fifty.py"
click node_ivgm "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/ivgm.py"
click node_ems "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/ems.py"
click node_milp "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/milp.py"
click node_entities "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/sensor.py"
click node_controls "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/number.py"
click node_boost "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/button.py"
click node_card "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/frontend/ha_felicity.js"
click node_emscard "https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/frontend/ha_felicity_ems.js"

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_coordinator,node_user toneBlue
class node_registers,node_trex5,node_trex10,node_trex25,node_trex50,node_ivgm toneAmber
class node_ems,node_milp toneMint
class node_entities,node_controls,node_boost,node_card,node_emscard toneRose
class node_ha,node_inverter,node_energy_inputs toneIndigo
```

## Components

### Setup and lifecycle

- [Config flow](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/config_flow.py): `custom_components/ha_felicity/config_flow.py`
- [Integration setup](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/__init__.py): `custom_components/ha_felicity/__init__.py`
- [Update coordinator](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/coordinator.py): `custom_components/ha_felicity/coordinator.py`

### Inverter access

- [Model register maps](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/type_specific.py): `custom_components/ha_felicity/type_specific.py`
- [T-REX 5K map](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/trex_five.py): `custom_components/ha_felicity/trex_five.py`
- [T-REX 10K map](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/trex_ten.py): `custom_components/ha_felicity/trex_ten.py`
- [T-REX 25K map](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/trex_twenty_five.py): `custom_components/ha_felicity/trex_twenty_five.py`
- [T-REX 50K map](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/trex_fifty.py): `custom_components/ha_felicity/trex_fifty.py`
- [IVGM maps](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/ivgm.py): `custom_components/ha_felicity/ivgm.py`

### Energy management

- [EMS scheduler](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/ems.py): `custom_components/ha_felicity/ems.py`
- [MILP engine](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/milp.py): `custom_components/ha_felicity/milp.py`

### Home Assistant interface

- [Device entities](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/sensor.py): `custom_components/ha_felicity/sensor.py`
- [Control entities](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/number.py): `custom_components/ha_felicity/number.py`
- [EV boost button](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/button.py): `custom_components/ha_felicity/button.py`
- [Inverter dashboard card](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/frontend/ha_felicity.js): `custom_components/ha_felicity/frontend/ha_felicity.js`
- [EMS dashboard card](https://github.com/partach/ha_felicity/blob/main/custom_components/ha_felicity/frontend/ha_felicity_ems.js): `custom_components/ha_felicity/frontend/ha_felicity_ems.js`

### Other components

- **Home Assistant user**
- **Home Assistant**
- **Felicity inverter**
- **Price and forecast inputs**

## Connections

- Home Assistant user → Config flow: configures
- Config flow → Integration setup: creates entry
- Integration setup → Update coordinator: sets up
- Update coordinator → Model register maps: selects model
- Model register maps → T-REX 5K map: uses map
- Model register maps → T-REX 10K map: uses map
- Model register maps → T-REX 25K map: uses map
- Model register maps → T-REX 50K map: uses map
- Model register maps → IVGM maps: uses map
- Update coordinator → Felicity inverter: reads and writes Modbus
- Update coordinator → Price and forecast inputs: reads prices and forecasts
- Update coordinator → EMS scheduler: calculates schedule
- Update coordinator → MILP engine: invokes when selected
- Update coordinator → Device entities: updates state
- Update coordinator → Control entities: handles control
- Update coordinator → EV boost button: handles boost
- Home Assistant → Update coordinator: runs integration
- Home Assistant → Inverter dashboard card: hosts card
- Home Assistant → EMS dashboard card: hosts card
- Inverter dashboard card → Home Assistant: reads entities and calls services
- EMS dashboard card → Home Assistant: reads entities and calls services
- Price and forecast inputs → Home Assistant: provided by integrations