# davidusb-geek/emhass architecture

> Architecture diagram of the GitHub repository davidusb-geek/emhass, 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/davidusb-geek/emhass
- Repository: https://github.com/davidusb-geek/emhass

## Overview

EMHASS is a home-energy management service for Home Assistant. A user configures an optimization through the web interface or API; the server dispatches a run, which retrieves household data, prepares forecasts, optimizes device schedules, and returns results for use in Home Assistant. The graph also shows the optional coordinator backend and its site-metering model, plus calibration and learning capabilities. Edges follow README statements and SOURCE INDEX references; unsampled subsystems are included where the tree supports them, without inferring their internal call paths.

Main entry points: [`src/emhass/command_line.py`](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/command_line.py) (Run orchestration), [`src/emhass/web_server.py`](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/web_server.py) (Web server), [`src/emhass/forecast.py`](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/forecast.py) (Forecast generation), [`src/emhass/coordinator/master.py`](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/coordinator/master.py) (Coordinator solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Access and orchestration"]
  node_web["Web server<br/>[web_server.py]"]
  node_auth["API access control<br/>[api_auth.py]"]
  node_cli["Run orchestration<br/>[command_line.py]"]
  node_ui["Web UI<br/>[script.js]"]
end

subgraph group_inputs["Data and forecasts"]
  node_retrieve["Home data retrieval<br/>[retrieve_hass.py]"]
  node_ws["WebSocket client"]
  node_forecast["Forecast generation<br/>[forecast.py]"]
  node_mlforecast["ML forecaster"]
  node_mlregressor["ML regressor"]
end

subgraph group_planning["Optimization"]
  node_optimization["Schedule optimization<br/>[optimization.py]"]
  node_backend["Coordinator backend<br/>[backend.py]"]
  node_master["Coordinator solver<br/>[master.py]"]
  node_model["Site model<br/>[model.py]"]
  node_meter["Site metering<br/>[submeter.py]"]
  node_costs["Cost calculations<br/>[costs.py]"]
end

subgraph group_support["Learning and state"]
  node_calibration["Forecast calibration"]
  node_pvcalibration["PV bias calibration"]
  node_batteryid["Battery identification"]
  node_thermal["Thermal planning<br/>[thermal_dp.py]"]
  node_planstore[("Plan storage<br/>[plan_store.py]")]
  node_lastrun[("Last-run state<br/>[last_run.py]")]
end

node_operator(("Home operator"))
node_hass["Home Assistant"]

node_operator -->|"configures and runs"| node_web
node_operator -->|"uses"| node_ui
node_ui -.->|"sends requests"| node_web
node_web -->|"checks access"| node_auth
node_web -->|"dispatches runs"| node_cli
node_cli -->|"retrieves data"| node_retrieve
node_retrieve -->|"uses connection"| node_ws
node_hass -.->|"provides states"| node_retrieve
node_cli -->|"generates forecasts"| node_forecast
node_forecast -->|"reads history"| node_retrieve
node_forecast -->|"uses forecaster"| node_mlforecast
node_forecast -->|"uses regressor"| node_mlregressor
node_cli -->|"runs optimization"| node_optimization
node_optimization -->|"invokes coordinator"| node_backend
node_backend -->|"builds and solves"| node_master
node_backend -->|"builds site model"| node_model
node_master -->|"uses site model"| node_model
node_master -->|"prices plans"| node_costs
node_master -.->|"evaluates meter flows"| node_meter
node_cli -->|"uses calibration"| node_calibration
node_cli -->|"uses calibration"| node_pvcalibration
node_cli -->|"identifies batteries"| node_batteryid
node_cli -->|"persists plans"| node_planstore
node_web -->|"reads and writes plans"| node_planstore
node_web -->|"reads run state"| node_lastrun
node_planstore -->|"uses state helpers"| node_lastrun
node_cli -.->|"returns schedules"| node_hass
node_optimization -.->|"supports thermal planning"| node_thermal

click node_web "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/web_server.py"
click node_auth "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/api_auth.py"
click node_cli "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/command_line.py"
click node_ui "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/static/script.js"
click node_retrieve "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/retrieve_hass.py"
click node_ws "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/websocket_client.py"
click node_forecast "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/forecast.py"
click node_mlforecast "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/machine_learning_forecaster.py"
click node_mlregressor "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/machine_learning_regressor.py"
click node_optimization "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/optimization.py"
click node_backend "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/coordinator/backend.py"
click node_master "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/coordinator/master.py"
click node_model "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/coordinator/model.py"
click node_meter "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/coordinator/submeter.py"
click node_costs "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/coordinator/costs.py"
click node_calibration "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/forecast_calibration.py"
click node_pvcalibration "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/pv_bias_calibration.py"
click node_batteryid "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/battery_identification.py"
click node_thermal "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/thermal_dp.py"
click node_planstore "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/plan_store.py"
click node_lastrun "https://github.com/davidusb-geek/emhass/blob/master/src/emhass/last_run.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_web,node_auth,node_cli,node_ui toneBlue
class node_retrieve,node_ws,node_forecast,node_mlforecast,node_mlregressor toneAmber
class node_optimization,node_backend,node_master,node_model,node_meter,node_costs toneMint
class node_calibration,node_pvcalibration,node_batteryid,node_thermal,node_planstore,node_lastrun toneRose
class node_operator,node_hass toneIndigo
```

## Components

### Access and orchestration

- [Web server](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/web_server.py): `src/emhass/web_server.py`
- [API access control](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/api_auth.py): `src/emhass/api_auth.py`
- [Run orchestration](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/command_line.py): `src/emhass/command_line.py`
- [Web UI](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/static/script.js): `src/emhass/static/script.js`

### Data and forecasts

- [Home data retrieval](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/retrieve_hass.py): `src/emhass/retrieve_hass.py`
- [WebSocket client](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/websocket_client.py): `src/emhass/websocket_client.py`
- [Forecast generation](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/forecast.py): `src/emhass/forecast.py`
- [ML forecaster](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/machine_learning_forecaster.py): `src/emhass/machine_learning_forecaster.py`
- [ML regressor](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/machine_learning_regressor.py): `src/emhass/machine_learning_regressor.py`

### Optimization

- [Schedule optimization](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/optimization.py): `src/emhass/optimization.py`
- [Coordinator backend](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/coordinator/backend.py): `src/emhass/coordinator/backend.py`
- [Coordinator solver](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/coordinator/master.py): `src/emhass/coordinator/master.py`
- [Site model](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/coordinator/model.py): `src/emhass/coordinator/model.py`
- [Site metering](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/coordinator/submeter.py): `src/emhass/coordinator/submeter.py`
- [Cost calculations](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/coordinator/costs.py): `src/emhass/coordinator/costs.py`

### Learning and state

- [Forecast calibration](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/forecast_calibration.py): `src/emhass/forecast_calibration.py`
- [PV bias calibration](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/pv_bias_calibration.py): `src/emhass/pv_bias_calibration.py`
- [Battery identification](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/battery_identification.py): `src/emhass/battery_identification.py`
- [Thermal planning](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/thermal_dp.py): `src/emhass/thermal_dp.py`
- [Plan storage](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/plan_store.py): `src/emhass/plan_store.py`
- [Last-run state](https://github.com/davidusb-geek/emhass/blob/master/src/emhass/last_run.py): `src/emhass/last_run.py`

### Other components

- **Home operator**
- **Home Assistant**

## Connections

- Home operator → Web server: configures and runs
- Home operator → Web UI: uses
- Web UI → Web server: sends requests
- Web server → API access control: checks access (evidence: `src/emhass/web_server.py`)
- Web server → Run orchestration: dispatches runs (evidence: `src/emhass/web_server.py`)
- Run orchestration → Home data retrieval: retrieves data (evidence: `src/emhass/command_line.py`)
- Home data retrieval → WebSocket client: uses connection (evidence: `src/emhass/retrieve_hass.py`)
- Home Assistant → Home data retrieval: provides states
- Run orchestration → Forecast generation: generates forecasts (evidence: `src/emhass/command_line.py`)
- Forecast generation → Home data retrieval: reads history (evidence: `src/emhass/forecast.py`)
- Forecast generation → ML forecaster: uses forecaster (evidence: `src/emhass/forecast.py`)
- Forecast generation → ML regressor: uses regressor (evidence: `src/emhass/forecast.py`)
- Run orchestration → Schedule optimization: runs optimization (evidence: `src/emhass/command_line.py`)
- Schedule optimization → Coordinator backend: invokes coordinator (evidence: `src/emhass/coordinator/backend.py`)
- Coordinator backend → Coordinator solver: builds and solves (evidence: `src/emhass/coordinator/backend.py`)
- Coordinator backend → Site model: builds site model (evidence: `src/emhass/coordinator/backend.py`)
- Coordinator solver → Site model: uses site model (evidence: `src/emhass/coordinator/master.py`)
- Coordinator solver → Cost calculations: prices plans (evidence: `src/emhass/coordinator/master.py`)
- Coordinator solver → Site metering: evaluates meter flows (evidence: `src/emhass/coordinator/master.py`)
- Run orchestration → Forecast calibration: uses calibration (evidence: `src/emhass/command_line.py`)
- Run orchestration → PV bias calibration: uses calibration (evidence: `src/emhass/command_line.py`)
- Run orchestration → Battery identification: identifies batteries (evidence: `src/emhass/command_line.py`)
- Run orchestration → Plan storage: persists plans (evidence: `src/emhass/command_line.py`)
- Web server → Plan storage: reads and writes plans (evidence: `src/emhass/web_server.py`)
- Web server → Last-run state: reads run state (evidence: `src/emhass/web_server.py`)
- Plan storage → Last-run state: uses state helpers (evidence: `src/emhass/plan_store.py`)
- Run orchestration → Home Assistant: returns schedules
- Schedule optimization → Thermal planning: supports thermal planning
