# elradix/daikin_cycle_ml architecture

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

- Interactive diagram: https://gitdiagram.com/elradix/daikin_cycle_ml
- Repository: https://github.com/elradix/daikin_cycle_ml

## Overview

Daikin Cycle ML is a local Home Assistant integration for monitoring Daikin Altherma heat-pump cycling. A configured heat-pump entity supplies telemetry; the coordinator polls it, detects and scores cycles, and evaluates them with per-mode learning and anomaly analysis. Advice and alerts surface through Home Assistant entities and notifications. SQLite preserves cycle and model history, while scheduled jobs maintain retention and retrain clusters. Edges reflect the README and sampled coordinator/service excerpts; unsampled subsystem wiring is included only where documented, and otherwise left out.

Main entry points: [`coordinator.py`](https://github.com/elradix/daikin_cycle_ml/blob/main/coordinator.py) (Polling coordinator), [`storage/store.py`](https://github.com/elradix/daikin_cycle_ml/blob/main/storage/store.py) (Cycle store), [`services.py`](https://github.com/elradix/daikin_cycle_ml/blob/main/services.py) (User services), [`storage/db.py`](https://github.com/elradix/daikin_cycle_ml/blob/main/storage/db.py) (SQLite history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and polling"]
  node_config["Integration setup<br/>[config_flow.py]"]
  node_lifecycle["Integration lifecycle<br/>[__init__.py]"]
  node_coordinator["Polling coordinator<br/>[coordinator.py]"]
end

subgraph group_analysis["Cycle analysis"]
  node_attributes["Attribute reader"]
  node_cycles["Cycle detector<br/>[cycle_detector.py]"]
  node_quality["Quality scorer<br/>[quality_scorer.py]"]
  node_advice["Actionable advice<br/>[action_engine.py]"]
end

subgraph group_learning["Self-learning"]
  node_features["Feature extraction<br/>[features.py]"]
  node_thresholds["Adaptive thresholds"]
  node_baseline["Per-mode baseline<br/>[baseline.py]"]
  node_anomaly["Anomaly evaluation<br/>[anomaly_engine.py]"]
  node_clustering["Cycle clustering<br/>[clustering.py]"]
end

subgraph group_persistence["State and services"]
  node_store[("Cycle store<br/>[store.py]")]
  node_sqlite[("SQLite history<br/>[db.py]")]
  node_services["User services<br/>[services.py]"]
end

subgraph group_presentation["Home Assistant output"]
  node_notifications["Alert generation"]
  node_entities["Sensors and binaries<br/>[sensor.py]"]
  node_binary_entities["Binary sensors<br/>[binary_sensor.py]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
end

node_user(("Home Assistant user"))
node_heatpump(("Heat-pump entities"))
node_ha_notifications["HA notifications"]

node_user -->|"configures"| node_config
node_config -->|"provides setup"| node_lifecycle
node_lifecycle -->|"starts polling"| node_coordinator
node_heatpump -->|"provides state"| node_coordinator
node_coordinator -->|"reads attributes"| node_attributes
node_coordinator -->|"detects cycles"| node_cycles
node_coordinator -->|"scores cycles"| node_quality
node_coordinator -->|"extracts features"| node_features
node_coordinator -->|"observes cycles"| node_thresholds
node_coordinator -->|"updates baseline"| node_baseline
node_coordinator -->|"evaluates vector"| node_anomaly
node_coordinator -->|"generates advice"| node_advice
node_coordinator -->|"reclusters history"| node_clustering
node_coordinator -->|"evaluates alerts"| node_notifications
node_coordinator -->|"updates records"| node_store
node_coordinator -->|"persists state"| node_sqlite
node_entities -->|"reads snapshot"| node_coordinator
node_entities -->|"reads cycles"| node_store
node_binary_entities -->|"reads status"| node_coordinator
node_binary_entities -->|"reads cycles"| node_store
node_coordinator -->|"creates alerts"| node_ha_notifications
node_services -->|"resolves entry"| node_coordinator
node_services -->|"exports cycles"| node_store
node_services -->|"reads and writes"| node_sqlite
node_diagnostics -->|"reads diagnostics"| node_coordinator
node_diagnostics -->|"reads history"| node_sqlite

click node_config "https://github.com/elradix/daikin_cycle_ml/blob/main/config_flow.py"
click node_lifecycle "https://github.com/elradix/daikin_cycle_ml/blob/main/__init__.py"
click node_coordinator "https://github.com/elradix/daikin_cycle_ml/blob/main/coordinator.py"
click node_attributes "https://github.com/elradix/daikin_cycle_ml/blob/main/engine/attribute_reader.py"
click node_cycles "https://github.com/elradix/daikin_cycle_ml/blob/main/engine/cycle_detector.py"
click node_quality "https://github.com/elradix/daikin_cycle_ml/blob/main/engine/quality_scorer.py"
click node_features "https://github.com/elradix/daikin_cycle_ml/blob/main/ml/features.py"
click node_thresholds "https://github.com/elradix/daikin_cycle_ml/blob/main/ml/adaptive_thresholds.py"
click node_baseline "https://github.com/elradix/daikin_cycle_ml/blob/main/ml/baseline.py"
click node_anomaly "https://github.com/elradix/daikin_cycle_ml/blob/main/engine/anomaly_engine.py"
click node_clustering "https://github.com/elradix/daikin_cycle_ml/blob/main/ml/clustering.py"
click node_advice "https://github.com/elradix/daikin_cycle_ml/blob/main/engine/action_engine.py"
click node_notifications "https://github.com/elradix/daikin_cycle_ml/blob/main/engine/notification_engine.py"
click node_entities "https://github.com/elradix/daikin_cycle_ml/blob/main/sensor.py"
click node_binary_entities "https://github.com/elradix/daikin_cycle_ml/blob/main/binary_sensor.py"
click node_store "https://github.com/elradix/daikin_cycle_ml/blob/main/storage/store.py"
click node_sqlite "https://github.com/elradix/daikin_cycle_ml/blob/main/storage/db.py"
click node_services "https://github.com/elradix/daikin_cycle_ml/blob/main/services.py"
click node_diagnostics "https://github.com/elradix/daikin_cycle_ml/blob/main/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,node_lifecycle,node_coordinator,node_user toneBlue
class node_attributes,node_cycles,node_quality,node_advice toneAmber
class node_features,node_thresholds,node_baseline,node_anomaly,node_clustering toneMint
class node_store,node_sqlite,node_services toneRose
class node_notifications,node_entities,node_binary_entities,node_diagnostics,node_heatpump,node_ha_notifications toneIndigo
```

## Components

### Setup and polling

- [Integration setup](https://github.com/elradix/daikin_cycle_ml/blob/main/config_flow.py): `config_flow.py`
- [Integration lifecycle](https://github.com/elradix/daikin_cycle_ml/blob/main/__init__.py): `__init__.py`
- [Polling coordinator](https://github.com/elradix/daikin_cycle_ml/blob/main/coordinator.py): `coordinator.py`

### Cycle analysis

- [Attribute reader](https://github.com/elradix/daikin_cycle_ml/blob/main/engine/attribute_reader.py): `engine/attribute_reader.py`
- [Cycle detector](https://github.com/elradix/daikin_cycle_ml/blob/main/engine/cycle_detector.py): `engine/cycle_detector.py`
- [Quality scorer](https://github.com/elradix/daikin_cycle_ml/blob/main/engine/quality_scorer.py): `engine/quality_scorer.py`
- [Actionable advice](https://github.com/elradix/daikin_cycle_ml/blob/main/engine/action_engine.py): `engine/action_engine.py`

### Self-learning

- [Feature extraction](https://github.com/elradix/daikin_cycle_ml/blob/main/ml/features.py): `ml/features.py`
- [Adaptive thresholds](https://github.com/elradix/daikin_cycle_ml/blob/main/ml/adaptive_thresholds.py): `ml/adaptive_thresholds.py`
- [Per-mode baseline](https://github.com/elradix/daikin_cycle_ml/blob/main/ml/baseline.py): `ml/baseline.py`
- [Anomaly evaluation](https://github.com/elradix/daikin_cycle_ml/blob/main/engine/anomaly_engine.py): `engine/anomaly_engine.py`
- [Cycle clustering](https://github.com/elradix/daikin_cycle_ml/blob/main/ml/clustering.py): `ml/clustering.py`

### State and services

- [Cycle store](https://github.com/elradix/daikin_cycle_ml/blob/main/storage/store.py): `storage/store.py`
- [SQLite history](https://github.com/elradix/daikin_cycle_ml/blob/main/storage/db.py): `storage/db.py`
- [User services](https://github.com/elradix/daikin_cycle_ml/blob/main/services.py): `services.py`

### Home Assistant output

- [Alert generation](https://github.com/elradix/daikin_cycle_ml/blob/main/engine/notification_engine.py): `engine/notification_engine.py`
- [Sensors and binaries](https://github.com/elradix/daikin_cycle_ml/blob/main/sensor.py): `sensor.py`
- [Binary sensors](https://github.com/elradix/daikin_cycle_ml/blob/main/binary_sensor.py): `binary_sensor.py`
- [Diagnostics](https://github.com/elradix/daikin_cycle_ml/blob/main/diagnostics.py): `diagnostics.py`

### Other components

- **Home Assistant user**
- **Heat-pump entities**
- **HA notifications**

## Connections

- Home Assistant user → Integration setup: configures
- Integration setup → Integration lifecycle: provides setup
- Integration lifecycle → Polling coordinator: starts polling
- Heat-pump entities → Polling coordinator: provides state
- Polling coordinator → Attribute reader: reads attributes
- Polling coordinator → Cycle detector: detects cycles
- Polling coordinator → Quality scorer: scores cycles
- Polling coordinator → Feature extraction: extracts features
- Polling coordinator → Adaptive thresholds: observes cycles
- Polling coordinator → Per-mode baseline: updates baseline
- Polling coordinator → Anomaly evaluation: evaluates vector
- Polling coordinator → Actionable advice: generates advice
- Polling coordinator → Cycle clustering: reclusters history
- Polling coordinator → Alert generation: evaluates alerts
- Polling coordinator → Cycle store: updates records
- Polling coordinator → SQLite history: persists state
- Sensors and binaries → Polling coordinator: reads snapshot
- Sensors and binaries → Cycle store: reads cycles
- Binary sensors → Polling coordinator: reads status
- Binary sensors → Cycle store: reads cycles
- Polling coordinator → HA notifications: creates alerts
- User services → Polling coordinator: resolves entry
- User services → Cycle store: exports cycles
- User services → SQLite history: reads and writes
- Diagnostics → Polling coordinator: reads diagnostics
- Diagnostics → SQLite history: reads history