# goldi5/raumklima-2 architecture

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

- Interactive diagram: https://gitdiagram.com/goldi5/raumklima-2
- Repository: https://github.com/goldi5/raumklima-2

## Overview

Raumklima is a Home Assistant heating and indoor-climate integration with a companion dashboard. Users configure rooms and a household hub, then room controllers regulate TRVs from room sensors and window state; ventilation assistance, presence, schedules and heating-season logic inform that operation. The integration also exposes notifications, health checks, decision logs and heating reports through Home Assistant entities and dashboard views. The README documents these capabilities; the sampled sources and SOURCE INDEX support several internal links, but do not expose every runtime dispatch or dashboard/API connection.

Main entry points: [`custom_components/raumklima/controller.py`](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/controller.py) (Room controller), [`custom_components/raumklima/hub.py`](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/hub.py) (Household hub), [`custom_components/raumklima/room_trv.py`](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/room_trv.py) (TRV control), [`custom_components/raumklima/reports.py`](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/reports.py) (Heating reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Integration setup"]
  node_config["Room configuration<br/>[config_flow.py]"]
  node_entities["HA entities<br/>[climate.py]"]
end

subgraph group_control["Room control"]
  node_controller["Room controller<br/>[controller.py]"]
  node_room_trv["TRV control<br/>[room_trv.py]"]
  node_room_windows["Window logic<br/>[room_windows.py]"]
  node_room_health["Room health<br/>[room_health.py]"]
  node_vent_manager["Ventilation assistant<br/>[vent_manager.py]"]
  node_ventilation["Ventilation rules<br/>[ventilation.py]"]
  node_logic["Control calculations<br/>[logic.py]"]
  node_planning["Schedules and protection<br/>[planning.py]"]
end

subgraph group_household["Household services"]
  node_hub["Household hub<br/>[hub.py]"]
  node_occupancy["Occupancy logic<br/>[occupancy.py]"]
  node_notify["HA notifications<br/>[hub_notify.py]"]
end

subgraph group_insight["Reports and diagnostics"]
  node_decision_log[("Decision log<br/>[decision_log.py]")]
  node_health["Health checks<br/>[health.py]"]
  node_reports["Heating reports<br/>[reports.py]"]
  node_report_data["Report data<br/>[report_data.py]"]
  node_stats["Heating statistics<br/>[stats.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_websocket["Dashboard API<br/>[websocket_api.py]"]
  node_frontend["Dashboard cards<br/>[index.js]"]
  node_frontend_shared["Card shared logic<br/>[shared.js]"]
  node_i18n["Card translations<br/>[i18n.js]"]
end

node_user(("Home Assistant user"))
node_ha["Home Assistant"]

node_user -->|"configures rooms"| node_config
node_config -.->|"sets up room"| node_controller
node_controller -->|"delegates control"| node_room_trv
node_controller -->|"delegates windows"| node_room_windows
node_controller -->|"delegates checks"| node_room_health
node_controller -->|"starts assistant"| node_vent_manager
node_vent_manager -->|"uses rules"| node_ventilation
node_room_trv -->|"uses calculations"| node_logic
node_room_trv -->|"uses plans"| node_planning
node_controller -->|"uses household state"| node_hub
node_controller -->|"records decisions"| node_decision_log
node_hub -->|"uses occupancy"| node_occupancy
node_hub -->|"starts reports"| node_reports
node_reports -->|"requests data"| node_report_data
node_reports -->|"uses statistics"| node_stats
node_report_data -->|"reads statistics"| node_stats
node_controller -->|"uses checks"| node_health
node_hub -->|"manages notifications"| node_notify
node_user -->|"views dashboard"| node_frontend
node_frontend -->|"uses shared logic"| node_frontend_shared
node_frontend_shared -->|"uses translations"| node_i18n
node_frontend -.->|"requests dashboard data"| node_websocket
node_ha -.->|"exposes controls"| node_entities

click node_config "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/config_flow.py"
click node_entities "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/climate.py"
click node_controller "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/controller.py"
click node_room_trv "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/room_trv.py"
click node_room_windows "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/room_windows.py"
click node_room_health "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/room_health.py"
click node_vent_manager "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/vent_manager.py"
click node_ventilation "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/ventilation.py"
click node_logic "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/logic.py"
click node_planning "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/planning.py"
click node_hub "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/hub.py"
click node_occupancy "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/occupancy.py"
click node_decision_log "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/decision_log.py"
click node_health "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/health.py"
click node_reports "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/reports.py"
click node_report_data "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/report_data.py"
click node_stats "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/stats.py"
click node_websocket "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/websocket_api.py"
click node_frontend "https://github.com/goldi5/raumklima-2/blob/main/frontend/src/index.js"
click node_frontend_shared "https://github.com/goldi5/raumklima-2/blob/main/frontend/src/shared.js"
click node_i18n "https://github.com/goldi5/raumklima-2/blob/main/frontend/src/i18n.js"
click node_notify "https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/hub_notify.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,node_entities,node_user toneBlue
class node_controller,node_room_trv,node_room_windows,node_room_health,node_vent_manager,node_ventilation,node_logic,node_planning toneAmber
class node_hub,node_occupancy,node_notify toneMint
class node_decision_log,node_health,node_reports,node_report_data,node_stats toneRose
class node_websocket,node_frontend,node_frontend_shared,node_i18n,node_ha toneIndigo
```

## Components

### Integration setup

- [Room configuration](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/config_flow.py): `custom_components/raumklima/config_flow.py`
- [HA entities](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/climate.py): `custom_components/raumklima/climate.py`

### Room control

- [Room controller](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/controller.py): `custom_components/raumklima/controller.py`
- [TRV control](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/room_trv.py): `custom_components/raumklima/room_trv.py`
- [Window logic](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/room_windows.py): `custom_components/raumklima/room_windows.py`
- [Room health](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/room_health.py): `custom_components/raumklima/room_health.py`
- [Ventilation assistant](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/vent_manager.py): `custom_components/raumklima/vent_manager.py`
- [Ventilation rules](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/ventilation.py): `custom_components/raumklima/ventilation.py`
- [Control calculations](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/logic.py): `custom_components/raumklima/logic.py`
- [Schedules and protection](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/planning.py): `custom_components/raumklima/planning.py`

### Household services

- [Household hub](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/hub.py): `custom_components/raumklima/hub.py`
- [Occupancy logic](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/occupancy.py): `custom_components/raumklima/occupancy.py`
- [HA notifications](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/hub_notify.py): `custom_components/raumklima/hub_notify.py`

### Reports and diagnostics

- [Decision log](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/decision_log.py): `custom_components/raumklima/decision_log.py`
- [Health checks](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/health.py): `custom_components/raumklima/health.py`
- [Heating reports](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/reports.py): `custom_components/raumklima/reports.py`
- [Report data](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/report_data.py): `custom_components/raumklima/report_data.py`
- [Heating statistics](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/stats.py): `custom_components/raumklima/stats.py`

### Dashboard

- [Dashboard API](https://github.com/goldi5/raumklima-2/blob/main/custom_components/raumklima/websocket_api.py): `custom_components/raumklima/websocket_api.py`
- [Dashboard cards](https://github.com/goldi5/raumklima-2/blob/main/frontend/src/index.js): `frontend/src/index.js`
- [Card shared logic](https://github.com/goldi5/raumklima-2/blob/main/frontend/src/shared.js): `frontend/src/shared.js`
- [Card translations](https://github.com/goldi5/raumklima-2/blob/main/frontend/src/i18n.js): `frontend/src/i18n.js`

### Other components

- **Home Assistant user**
- **Home Assistant**

## Connections

- Home Assistant user → Room configuration: configures rooms
- Room configuration → Room controller: sets up room
- Room controller → TRV control: delegates control (evidence: `custom_components/raumklima/controller.py`)
- Room controller → Window logic: delegates windows (evidence: `custom_components/raumklima/controller.py`)
- Room controller → Room health: delegates checks (evidence: `custom_components/raumklima/controller.py`)
- Room controller → Ventilation assistant: starts assistant (evidence: `custom_components/raumklima/controller.py`)
- Ventilation assistant → Ventilation rules: uses rules (evidence: `custom_components/raumklima/vent_manager.py`)
- TRV control → Control calculations: uses calculations (evidence: `custom_components/raumklima/room_trv.py`)
- TRV control → Schedules and protection: uses plans (evidence: `custom_components/raumklima/room_trv.py`)
- Room controller → Household hub: uses household state (evidence: `custom_components/raumklima/controller.py`)
- Room controller → Decision log: records decisions (evidence: `custom_components/raumklima/controller.py`)
- Household hub → Occupancy logic: uses occupancy (evidence: `custom_components/raumklima/hub.py`)
- Household hub → Heating reports: starts reports (evidence: `custom_components/raumklima/hub.py`)
- Heating reports → Report data: requests data (evidence: `custom_components/raumklima/reports.py`)
- Heating reports → Heating statistics: uses statistics (evidence: `custom_components/raumklima/reports.py`)
- Report data → Heating statistics: reads statistics (evidence: `custom_components/raumklima/report_data.py`)
- Room controller → Health checks: uses checks (evidence: `custom_components/raumklima/controller.py`)
- Household hub → HA notifications: manages notifications (evidence: `custom_components/raumklima/hub.py`)
- Home Assistant user → Dashboard cards: views dashboard
- Dashboard cards → Card shared logic: uses shared logic (evidence: `frontend/src/index.js`)
- Card shared logic → Card translations: uses translations (evidence: `frontend/src/shared.js`)
- Dashboard cards → Dashboard API: requests dashboard data
- Home Assistant → HA entities: exposes controls