# bramstroker/homeassistant-powercalc architecture

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

- Interactive diagram: https://gitdiagram.com/bramstroker/homeassistant-powercalc
- Repository: https://github.com/bramstroker/homeassistant-powercalc

## Overview

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.

Main entry points: [`custom_components/powercalc/power_profile`](https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/power_profile) (Profiles), [`custom_components/powercalc/__init__.py`](https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/__init__.py) (PowerCalc init), [`profile_library`](https://github.com/bramstroker/homeassistant-powercalc/tree/master/profile_library) (Profile library), [`custom_components/powercalc/sensors`](https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/sensors) (Sensors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ha_runtime["HA runtime"]
  node_custom_components_powercalc_init["PowerCalc init<br/>ha integration entry<br/>[__init__.py]"]
  node_custom_components_powercalc_manifest["Manifest<br/>integration metadata<br/>[manifest.json]"]
  node_custom_components_powercalc_config_flow["Setup flow<br/>config flow<br/>[config_flow.py]"]
  node_custom_components_powercalc_flow_helper["Flow helper<br/>flow UI support"]
  node_custom_components_powercalc_service["Services"]
  node_custom_components_powercalc_sensor["Sensor entry<br/>entity setup<br/>[sensor.py]"]
  node_custom_components_powercalc_select["Select entry<br/>entity setup<br/>[select.py]"]
  node_custom_components_powercalc_sensors["Sensors<br/>entity models"]
  node_custom_components_powercalc_strategy["Strategies<br/>power modeling"]
  node_custom_components_powercalc_discovery["Discovery<br/>binding<br/>[discovery.py]"]
  node_custom_components_powercalc_device_binding["Device binding<br/>[device_binding.py]"]
  node_custom_components_powercalc_filter["Outlier filter<br/>data quality"]
  node_custom_components_powercalc_analytics["Analytics<br/>telemetry"]
  node_custom_components_powercalc_repairs["Repairs<br/>issue handling<br/>[repairs.py]"]
  node_custom_components_powercalc_diagnostics["Diagnostics<br/>troubleshooting<br/>[diagnostics.py]"]
end

subgraph group_profiles["Device knowledge"]
  node_custom_components_powercalc_power_profile["Profiles<br/>profile resolution"]
  node_profile_library_root[("Profile library<br/>device catalog")]
  node_profile_library_schema["Library schema<br/>data schema"]
end

subgraph group_tooling["Tooling"]
  node_utils_measure["Measure app<br/>measurement pipeline"]
  node_utils_library["Library tools<br/>validation tools"]
  node_github_automation["CI scripts<br/>automation<br/>[.github]"]
  node_docs_root["Docs<br/>documentation"]
end

node_custom_components_powercalc_init -->|"declares"| node_custom_components_powercalc_manifest
node_custom_components_powercalc_init -->|"starts setup"| node_custom_components_powercalc_config_flow
node_custom_components_powercalc_init -->|"registers"| node_custom_components_powercalc_service
node_custom_components_powercalc_init -->|"sets up"| node_custom_components_powercalc_sensor
node_custom_components_powercalc_sensor -->|"creates"| node_custom_components_powercalc_sensors
node_custom_components_powercalc_sensor -->|"creates"| node_custom_components_powercalc_select
node_custom_components_powercalc_config_flow -->|"uses"| node_custom_components_powercalc_flow_helper
node_custom_components_powercalc_service -->|"orchestrates"| node_custom_components_powercalc_flow_helper
node_custom_components_powercalc_sensors -->|"consumes"| node_custom_components_powercalc_strategy
node_custom_components_powercalc_sensors -->|"consumes"| node_custom_components_powercalc_power_profile
node_custom_components_powercalc_strategy -->|"consults"| node_custom_components_powercalc_power_profile
node_custom_components_powercalc_discovery -->|"coordinates"| node_custom_components_powercalc_device_binding
node_custom_components_powercalc_discovery -->|"matches"| node_custom_components_powercalc_power_profile
node_custom_components_powercalc_device_binding -->|"resolves"| node_custom_components_powercalc_power_profile
node_custom_components_powercalc_filter -->|"supports"| node_custom_components_powercalc_sensors
node_custom_components_powercalc_analytics -->|"feeds"| node_custom_components_powercalc_diagnostics
node_custom_components_powercalc_repairs -->|"explains"| node_custom_components_powercalc_diagnostics
node_profile_library_root -->|"defined by"| node_profile_library_schema
node_custom_components_powercalc_power_profile -->|"loads"| node_profile_library_root
node_utils_measure -->|"produces"| node_profile_library_root
node_utils_library -->|"validates"| node_profile_library_root
node_github_automation -->|"runs"| node_utils_library
node_github_automation -->|"checks"| node_profile_library_root
node_github_automation -->|"tests"| node_custom_components_powercalc_init
node_docs_root -->|"documents"| node_custom_components_powercalc_strategy
node_docs_root -->|"documents"| node_custom_components_powercalc_power_profile
node_docs_root -->|"documents"| node_utils_measure

click node_custom_components_powercalc_init "https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/__init__.py"
click node_custom_components_powercalc_manifest "https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/manifest.json"
click node_custom_components_powercalc_config_flow "https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/config_flow.py"
click node_custom_components_powercalc_flow_helper "https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/flow_helper"
click node_custom_components_powercalc_service "https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/service"
click node_custom_components_powercalc_sensor "https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/sensor.py"
click node_custom_components_powercalc_select "https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/select.py"
click node_custom_components_powercalc_sensors "https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/sensors"
click node_custom_components_powercalc_strategy "https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/strategy"
click node_custom_components_powercalc_power_profile "https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/power_profile"
click node_custom_components_powercalc_discovery "https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/discovery.py"
click node_custom_components_powercalc_device_binding "https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/device_binding.py"
click node_custom_components_powercalc_filter "https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/filter"
click node_custom_components_powercalc_analytics "https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/analytics"
click node_custom_components_powercalc_repairs "https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/repairs.py"
click node_custom_components_powercalc_diagnostics "https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/diagnostics.py"
click node_profile_library_root "https://github.com/bramstroker/homeassistant-powercalc/tree/master/profile_library"
click node_profile_library_schema "https://github.com/bramstroker/homeassistant-powercalc/blob/master/profile_library/library_schema.json"
click node_utils_measure "https://github.com/bramstroker/homeassistant-powercalc/tree/master/utils/measure"
click node_utils_library "https://github.com/bramstroker/homeassistant-powercalc/tree/master/utils/library"
click node_github_automation "https://github.com/bramstroker/homeassistant-powercalc/blob/master/.github"
click node_docs_root "https://github.com/bramstroker/homeassistant-powercalc/tree/master/docs"

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_custom_components_powercalc_init,node_custom_components_powercalc_manifest,node_custom_components_powercalc_config_flow,node_custom_components_powercalc_flow_helper,node_custom_components_powercalc_service,node_custom_components_powercalc_sensor,node_custom_components_powercalc_select,node_custom_components_powercalc_sensors,node_custom_components_powercalc_strategy,node_custom_components_powercalc_discovery,node_custom_components_powercalc_device_binding,node_custom_components_powercalc_filter,node_custom_components_powercalc_analytics,node_custom_components_powercalc_repairs,node_custom_components_powercalc_diagnostics toneBlue
class node_custom_components_powercalc_power_profile,node_profile_library_root,node_profile_library_schema toneAmber
class node_utils_measure,node_utils_library,node_github_automation,node_docs_root toneMint
```

## Components

### HA runtime

Home Assistant custom integration that creates virtual power and energy entities.

- [PowerCalc init](https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/__init__.py): ha integration entry · Integration bootstrap and config entry lifecycle inside Home Assistant. · `custom_components/powercalc/__init__.py`
- [Manifest](https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/manifest.json): integration metadata · Home Assistant manifest and package identity. · `custom_components/powercalc/manifest.json`
- [Setup flow](https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/config_flow.py): config flow · User-facing setup, edit, and sensor-creation flows. · `custom_components/powercalc/config_flow.py`
- [Flow helper](https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/flow_helper): flow UI support · Shared flow builders, schemas, previews, and step orchestration. · `custom_components/powercalc/flow_helper`
- [Services](https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/service): ha services · Service registration and GUI configuration actions exposed to Home Assistant. · `custom_components/powercalc/service`
- [Sensor entry](https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/sensor.py): entity setup · Top-level entity/platform registration for sensors and selects. · `custom_components/powercalc/sensor.py`
- [Select entry](https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/select.py): entity setup · Select entity/platform registration for user controls. · `custom_components/powercalc/select.py`
- [Sensors](https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/sensors): entity models · Power, energy, daily-energy, utility meter, and aggregation entities. · `custom_components/powercalc/sensors`
- [Strategies](https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/strategy): power modeling · Virtual power algorithms that turn HA state into watt estimates. · `custom_components/powercalc/strategy`
- [Discovery](https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/discovery.py): binding · Matches HA entities and integrations to supported device profiles. · `custom_components/powercalc/discovery.py`
- [Device binding](https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/device_binding.py): binding · Infers device capabilities and profile matches from registry and entity metadata. · `custom_components/powercalc/device_binding.py`
- [Outlier filter](https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/filter): data quality · Smoothing and outlier rejection for noisy measurements and profile data. · `custom_components/powercalc/filter`
- [Analytics](https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/analytics): telemetry · Observability and usage analytics hooks. · `custom_components/powercalc/analytics`
- [Repairs](https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/repairs.py): issue handling · User-facing repair flows for broken config or unexpected state. · `custom_components/powercalc/repairs.py`
- [Diagnostics](https://github.com/bramstroker/homeassistant-powercalc/blob/master/custom_components/powercalc/diagnostics.py): troubleshooting · Diagnostic payload generation for support and debugging. · `custom_components/powercalc/diagnostics.py`

### Device knowledge

Bundled profile library and the loader/resolution layer that turns device data into models.

- [Profiles](https://github.com/bramstroker/homeassistant-powercalc/tree/master/custom_components/powercalc/power_profile): profile resolution · Loads and resolves device profiles and sub-profiles. · `custom_components/powercalc/power_profile`
- [Profile library](https://github.com/bramstroker/homeassistant-powercalc/tree/master/profile_library): device catalog · Bundled manufacturer/model/sub-profile database of curated power models. · `profile_library`
- [Library schema](https://github.com/bramstroker/homeassistant-powercalc/blob/master/profile_library/library_schema.json): data schema · Catalog and model schemas plus top-level library metadata. · `profile_library/library_schema.json`

### Tooling

Measurement, validation, documentation, and CI automation around the library and integration.

- [Measure app](https://github.com/bramstroker/homeassistant-powercalc/tree/master/utils/measure): measurement pipeline · Offline measurement tooling that captures device behavior and generates profiles. · `utils/measure`
- [Library tools](https://github.com/bramstroker/homeassistant-powercalc/tree/master/utils/library): validation tools · Scripts for scanning LUT quality, validating model JSON, and building library reports. · `utils/library`
- [CI scripts](https://github.com/bramstroker/homeassistant-powercalc/blob/master/.github): automation · GitHub workflows and scripts that validate LUTs, translations, HACS metadata, and releases. · `.github`
- [Docs](https://github.com/bramstroker/homeassistant-powercalc/tree/master/docs): documentation · Repository documentation for setup, strategies, library structure, and measurement workflows. · `docs`

## Connections

- PowerCalc init → Manifest: declares · Integration metadata used by Home Assistant.
- PowerCalc init → Setup flow: starts setup · Config entry setup and edit flow entry point.
- PowerCalc init → Services: registers · Exposes integration services.
- PowerCalc init → Sensor entry: sets up · Registers entity platforms and config entry runtime.
- Sensor entry → Sensors: creates · Instantiates power, energy, and group sensors.
- Sensor entry → Select entry: creates · Instantiates select entities for controls.
- Setup flow → Flow helper: uses · Shares schemas, helpers, and previews across flows.
- Services → Flow helper: orchestrates · Uses shared flow/UI logic for service-driven changes.
- Sensors → Strategies: consumes · Power sensors depend on selected modeling strategies.
- Sensors → Profiles: consumes · Library-backed sensors derive power from device profiles.
- Strategies → Profiles: consults · Some strategies rely on profile data or sub-profile selection.
- Discovery → Device binding: coordinates · Discovery feeds binding decisions and supported-device inference.
- Discovery → Profiles: matches · Maps discovered entities to catalog profiles.
- Device binding → Profiles: resolves · Binds entities to the best-fit profile or sub-profile.
- Outlier filter → Sensors: supports · Used to smooth measurements before entity exposure.
- Analytics → Diagnostics: feeds · Support and troubleshooting data complement analytics.
- Repairs → Diagnostics: explains · Repairs help users resolve diagnosed problems.
- Profile library → Library schema: defined by · Catalog structure and model format are schema-driven.
- Profiles → Profile library: loads · Runtime resolves bundled device knowledge from the library.
- Measure app → Profile library: produces · Measurement runs generate model data for the library.
- Library tools → Profile library: validates · Checks LUTs, model JSON, and catalog consistency.
- CI scripts → Library tools: runs · CI invokes validation and release helper scripts.
- CI scripts → Profile library: checks · Workflows validate the bundled library before release.
- CI scripts → PowerCalc init: tests · CI verifies integration behavior and packaging.
- Docs → Strategies: documents · Explains the virtual power modeling approaches.
- Docs → Profiles: documents · Describes the curated device profile system.
- Docs → Measure app: documents · Covers offline measurement and profile generation workflows.