bramstroker/homeassistant-powercalc

1. Repository shape

- This is a Home Assistant custom integration centered in custom_components/powercalc.

- The repo also contains a large bundled device profile library under profile_library/, documentation under docs/, measurement tooling under utils/measure/, and CI/validation automation in .github/.

2. Runtime boundary: Home Assistant integration

- The main runtime lives inside Home Assistant and follows the standard custom integration lifecycle: manifest, config flow, config entries, entity platforms, services, diagnostics, and repairs.

- There is no standalone server; PowerCalc is loaded into HA and creates entities there.

3. User-facing entry points

- config_flow.py and flow_helper/ implement the setup and editing UI for different sensor types and power-modeling modes.

- service/ exposes HA services for operations like reloading, switching profiles, recalibrating, and GUI configuration changes.

- sensor.py, select.py, and services.yaml are the main HA-facing entity/service registration points.

4. Core domain model: estimated power and derived energy

- The integration’s job is to estimate power consumption and expose it as HA sensors.

- sensors/ contains the entity implementations for power, energy, daily energy, utility meter integration, and group sensors.

- Energy-related flows are derived from power estimates plus HA’s energy/utility-meter concepts, rather than direct metering hardware.

5. Power modeling subsystem

- strategy/ contains the algorithms used to compute virtual power: fixed, linear, LUT-based, multi-switch, playbook, WLED, and composite strategies.

- strategy/factory.py and selector.py choose the correct strategy based on configuration and entity state.

- This is the main calculation boundary: raw HA state in, watt estimate out.

6. Device profile subsystem

- power_profile/ resolves manufacturer/model-specific power profiles and their sub-profiles.

- Profiles can come from local bundled data, local filesystem content, or remote sources via the loader layer in power_profile/loader/.

- The profile format is data-driven: JSON model descriptors plus LUT CSVs (brightness, color_temp, hs, effect, etc.), often gzipped.

7. Profile library as a data product

- profile_library/ is effectively a structured database of supported devices.

- Its hierarchy is manufacturer → model → optional sub-profile, with manufacturer.json, library.json, and schema files defining the catalog structure.

- This library is consumed by the integration and validated by scripts/tests/CI; it is a key architectural boundary between code and device knowledge.

8. Discovery and automatic binding

- discovery.py and device_binding.py connect HA entities to known profiles and supported device types.

- The integration can infer capabilities from entity attributes, registry metadata, or discovered integrations, reducing manual configuration.

9. Group power aggregation

- sensors/group/ and group_include/ implement aggregation and inclusion rules for group sensors.

- Different group modes handle custom groups, domain-based groups, subtractive groups, standby-aware groups, and tracked/untracked entity sets.

- This is the main “many entities to one virtual sensor” boundary.

10. Data quality and correction

- filter/ contains outlier filtering used to smooth noisy measurements or profile data.

- analytics/, repairs.py, diagnostics.py, and errors.py provide observability, user-facing fixes, and troubleshooting support around bad config or unexpected data.

11. Offline tooling and measurement pipeline

- utils/measure/ is a separate Python application used to gather real-world device measurements and generate the profile data that powers the library.

- It includes controllers for lights, fans, media players, chargers, and power meters, plus OCR/manual capture paths and runners that execute measurement flows.

- This tooling is outside the HA runtime but directly feeds the profile library and model quality.

12. Library validation and release automation

- .github/scripts/, utils/library/, and CI workflows validate LUT files, JSON model schemas, translations, and HACS metadata.

- Release, docs, plot generation, and profile-library update workflows indicate the repo ships both code and curated data as a maintained package.

- For an architecture diagram, this repo should be shown as a code-and-data system: Home Assistant integration runtime on one side, curated device model library and measurement/validation toolchain on the other.

13. Supporting concerns

- translations/ and Crowdin workflows support multi-language UI strings.

- migrate.py, configuration/, and migrate/update scripts handle config evolution and library maintenance.

- Tests mirror the major subsystems, especially strategies, power profile loading, config flows, sensors, and utility scripts, which reflects the repo’s modular architecture.