# wayne-willey/ha-emerald-ems architecture

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

- Interactive diagram: https://gitdiagram.com/wayne-willey/ha-emerald-ems
- Repository: https://github.com/wayne-willey/ha-emerald-ems

## Overview

Emerald EMS is a Home Assistant integration that authenticates an account, lets the user select a metering device, then polls Emerald’s cloud and exposes live sensors while importing completed hourly energy and cost statistics. The graph also includes device diagnostics and the recorder as distinct product capabilities. Edges follow the excerpts or README; unsampled behavior is represented only where documented, and no tests or delivery tooling are included.

Main entry points: [`custom_components/emerald_ems/coordinator.py`](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/coordinator.py) (Polling coordinator), [`custom_components/emerald_ems/api.py`](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/api.py) (Emerald API client), [`custom_components/emerald_ems/__init__.py`](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/__init__.py) (Integration setup), [`custom_components/emerald_ems/sensor.py`](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/sensor.py) (Live sensors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Account setup"]
  node_config_flow["Account and device flow<br/>[config_flow.py]"]
  node_entry_setup["Integration setup<br/>[__init__.py]"]
end

subgraph group_polling["Cloud polling"]
  node_api["Emerald API client<br/>[api.py]"]
  node_models["Payload models<br/>[models.py]"]
  node_coordinator["Polling coordinator<br/>[coordinator.py]"]
  node_constants["Integration constants<br/>[const.py]"]
end

subgraph group_ha["Home Assistant output"]
  node_sensor["Live sensors<br/>[sensor.py]"]
  node_entity["Device entity base<br/>[entity.py]"]
  node_statistics["Hourly statistics import<br/>[statistics.py]"]
end

subgraph group_support["Diagnostics"]
  node_diagnostics["Redacted diagnostics<br/>[diagnostics.py]"]
end

node_user(("Home Assistant user"))
node_cloud{{"Emerald cloud API"}}
node_recorder[("Home Assistant recorder")]

node_user -->|"configures account"| node_config_flow
node_config_flow -->|"validates credentials"| node_api
node_api -->|"sends API requests"| node_cloud
node_api -->|"parses responses"| node_models
node_entry_setup -->|"creates client"| node_api
node_entry_setup -->|"starts polling"| node_coordinator
node_entry_setup -->|"forwards sensor setup"| node_sensor
node_coordinator -->|"fetches energy"| node_api
node_coordinator -->|"imports completed buckets"| node_statistics
node_sensor -->|"reads polled data"| node_coordinator
node_sensor -->|"extends device entity"| node_entity
node_statistics -->|"writes statistics"| node_recorder
node_diagnostics -->|"reads runtime data"| node_coordinator
node_coordinator -->|"uses polling settings"| node_constants

click node_config_flow "https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/config_flow.py"
click node_api "https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/api.py"
click node_models "https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/models.py"
click node_coordinator "https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/coordinator.py"
click node_constants "https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/const.py"
click node_entry_setup "https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/__init__.py"
click node_sensor "https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/sensor.py"
click node_entity "https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/entity.py"
click node_statistics "https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/statistics.py"
click node_diagnostics "https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/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_flow,node_entry_setup,node_user toneBlue
class node_api,node_models,node_coordinator,node_constants,node_recorder toneAmber
class node_sensor,node_entity,node_statistics,node_cloud toneMint
class node_diagnostics toneRose
```

## Components

### Account setup

- [Account and device flow](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/config_flow.py): `custom_components/emerald_ems/config_flow.py`
- [Integration setup](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/__init__.py): `custom_components/emerald_ems/__init__.py`

### Cloud polling

- [Emerald API client](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/api.py): `custom_components/emerald_ems/api.py`
- [Payload models](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/models.py): `custom_components/emerald_ems/models.py`
- [Polling coordinator](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/coordinator.py): `custom_components/emerald_ems/coordinator.py`
- [Integration constants](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/const.py): `custom_components/emerald_ems/const.py`

### Home Assistant output

- [Live sensors](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/sensor.py): `custom_components/emerald_ems/sensor.py`
- [Device entity base](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/entity.py): `custom_components/emerald_ems/entity.py`
- [Hourly statistics import](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/statistics.py): `custom_components/emerald_ems/statistics.py`

### Diagnostics

- [Redacted diagnostics](https://github.com/wayne-willey/ha-emerald-ems/blob/main/custom_components/emerald_ems/diagnostics.py): `custom_components/emerald_ems/diagnostics.py`

### Other components

- **Home Assistant user**
- **Emerald cloud API**
- **Home Assistant recorder**

## Connections

- Home Assistant user → Account and device flow: configures account (evidence: `README.md`)
- Account and device flow → Emerald API client: validates credentials (evidence: `custom_components/emerald_ems/config_flow.py`)
- Emerald API client → Emerald cloud API: sends API requests (evidence: `custom_components/emerald_ems/api.py`)
- Emerald API client → Payload models: parses responses (evidence: `custom_components/emerald_ems/api.py`)
- Integration setup → Emerald API client: creates client (evidence: `custom_components/emerald_ems/__init__.py`)
- Integration setup → Polling coordinator: starts polling (evidence: `custom_components/emerald_ems/__init__.py`)
- Integration setup → Live sensors: forwards sensor setup (evidence: `custom_components/emerald_ems/__init__.py`)
- Polling coordinator → Emerald API client: fetches energy (evidence: `custom_components/emerald_ems/coordinator.py`)
- Polling coordinator → Hourly statistics import: imports completed buckets (evidence: `custom_components/emerald_ems/coordinator.py`)
- Live sensors → Polling coordinator: reads polled data (evidence: `custom_components/emerald_ems/sensor.py`)
- Live sensors → Device entity base: extends device entity (evidence: `custom_components/emerald_ems/sensor.py`)
- Hourly statistics import → Home Assistant recorder: writes statistics (evidence: `custom_components/emerald_ems/statistics.py`)
- Redacted diagnostics → Polling coordinator: reads runtime data (evidence: `custom_components/emerald_ems/diagnostics.py`)
- Polling coordinator → Integration constants: uses polling settings (evidence: `custom_components/emerald_ems/coordinator.py`)
