# cjaliaga/home-assistant-aquarea architecture

> Architecture diagram of the GitHub repository cjaliaga/home-assistant-aquarea, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cjaliaga/home-assistant-aquarea
- Repository: https://github.com/cjaliaga/home-assistant-aquarea

## Overview

##### Project type and purpose
- This is a Home Assistant custom integration (“aquarea”) that plugs into Home Assistant Core.
- It provides an interface to Panasonic Aquarea Smart Cloud devices using the third-party Python library `aioaquarea`.
- The goal is to surface heat pump zones, sensors, switches, and climate controls as Home Assistant entities.

##### File structure
- Top-level folders:
- `.github` for CI/workflow definitions (HACS, hassfest, releases).
- `custom_components/aquarea` which contains the integration code.
- Within `custom_components/aquarea`:
- `manifest.json` and `config_flow.py` define metadata and the setup UI flow.
- `coordinator.py` implements Home Assistant’s DataUpdateCoordinator pattern.
- Multiple platform modules (`climate.py`, `sensor.py`, `switch.py`, `binary_sensor.py`, `button.py`, `select.py`, `water_heater.py`) each exposing one or more Entity classes.
- `const.py` for common constants, `strings.json` and `translations/*.json` for i18n.
- `hacs.json` indicates HACS compatibility.

##### README for additional insights
- Confirms the use of `aioaquarea` to perform HTTP-based cloud API calls.
- Describes supported entities: climate, water heater, sensors, energy, mode selectors, diagnostic sensors, etc.
- Explains the authentication flow and single-connection limitation of the Panasonic cloud.

##### Main components
a. Home Assistant Core
b. Aquarea Integration (custom_components/aquarea)
- Config Flow (user authentication setup)
- DataUpdateCoordinator (central polling/refresh mechanism)
- Entity platforms (climate, sensor, switch, etc.)
c. aioaquarea API client library
d. Panasonic Aquarea Smart Cloud (external service)
e. Home Assistant UI / State Machine (where entities appear)

##### Relationships and data flows
- User interacts with the Home Assistant UI to configure the integration (Config Flow → Home Assistant Core → Integration).
- Config Flow hands credentials to the API client and instantiates the DataUpdateCoordinator.
- The Coordinator schedules periodic fetches via `aioaquarea` to the Panasonic cloud.
- The API client makes HTTP(S) calls, returns JSON data.
- Coordinator parses the data, notifies all registered Entity instances.
- Each Entity (climate, sensor, etc.) updates its state in Home Assistant’s state machine and renders in the UI.
- When the user sends a command (e.g., set temperature), the Entity calls the Coordinator/API client, which issues a write call to the cloud.

##### Architectural patterns and design principles
- Layered architecture:
- Presentation/UI layer (Home Assistant frontend)
- Integration layer (Config Flow + Coordinator + Platforms)
- API client layer (`aioaquarea`)
- External system (Panasonic cloud)
- Observer pattern via DataUpdateCoordinator: Entities subscribe to data updates.
- Single source of truth: Coordinator centralizes polling and caching.
- Separation of concerns: each platform file only implements a specific entity type.

##### Technologies, frameworks, libraries
- Python 3.x, Home Assistant Integration API
- aioaquarea (async HTTP client for Panasonic cloud)
- Home Assistant DataUpdateCoordinator
- JSON for configuration and translations
- HACS for distribution

##### Final advice
- Every key part: Config Flow, Coordinator, Platforms, API client, cloud service.
- DataUpdateCoordinator pattern, since it’s central to how data moves.
- Use annotation or footnotes to note the single-connection limitation and retry logic.
- Review the manifest.json for any additional dependencies you might want to call out.

## Diagram (Mermaid)

```mermaid
flowchart TB
    UI["Home Assistant UI<br/>State Machine"]:::coreUI
    subgraph "Home Assistant Core"
        subgraph "Aquarea Integration"
            root["Aquarea Integration Root"]:::integration
            manifest["Manifest Metadata<br/>manifest.json"]:::integration
            const["Constants Module<br/>const.py"]:::integration
            strings["Translation Strings<br/>strings.json"]:::integration
            translations["Translations Directory<br/>translations/"]:::integration
            configFlow["Config Flow<br/>config_flow.py"]:::integration
            coordinator["DataUpdateCoordinator<br/>coordinator.py"]:::integration
            subgraph "Entity Platforms"
                climate["Climate Entity Platform<br/>climate.py"]:::integration
                sensor["Sensor Entity Platform<br/>sensor.py"]:::integration
                switch["Switch Entity Platform<br/>switch.py"]:::integration
                binary_sensor["Binary Sensor Entity Platform<br/>binary_sensor.py"]:::integration
                button["Button Entity Platform<br/>button.py"]:::integration
                select["Select Entity Platform<br/>select.py"]:::integration
                water_heater["Water Heater Entity Platform<br/>water_heater.py"]:::integration
            end
        end
    end
    API["aioaquarea API Client"]:::library
    Cloud["Panasonic Aquarea Smart Cloud"]:::external

    UI -->|"authenticate"| configFlow
    configFlow -->|"init coordinator"| coordinator
    coordinator -->|"HTTP GET /poll"| API
    API -->|"JSON data"| coordinator
    coordinator -->|"notify update"| climate
    coordinator -->|"notify update"| sensor
    coordinator -->|"notify update"| switch
    coordinator -->|"notify update"| binary_sensor
    coordinator -->|"notify update"| button
    coordinator -->|"notify update"| select
    coordinator -->|"notify update"| water_heater
    climate -->|"command"| coordinator
    sensor -->|"command"| coordinator
    switch -->|"command"| coordinator
    binary_sensor -->|"command"| coordinator
    button -->|"command"| coordinator
    select -->|"command"| coordinator
    water_heater -->|"command"| coordinator
    coordinator -->|"HTTP POST /set"| API
    API -->|"execute"| Cloud

    click root "https://github.com/cjaliaga/home-assistant-aquarea/tree/main/custom_components/aquarea/"
    click manifest "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/manifest.json"
    click const "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/const.py"
    click strings "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/strings.json"
    click translations "https://github.com/cjaliaga/home-assistant-aquarea/tree/main/custom_components/aquarea/translations/"
    click configFlow "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/config_flow.py"
    click coordinator "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/coordinator.py"
    click climate "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/climate.py"
    click sensor "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/sensor.py"
    click switch "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/switch.py"
    click binary_sensor "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/binary_sensor.py"
    click button "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/button.py"
    click select "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/select.py"
    click water_heater "https://github.com/cjaliaga/home-assistant-aquarea/blob/main/custom_components/aquarea/water_heater.py"

    classDef integration fill:#a8f0c6,stroke:#333,stroke-width:1px
    classDef library fill:#c6d9f1,stroke:#333,stroke-width:1px
    classDef external fill:#d0e6f6,stroke:#333,stroke-width:1px
    classDef coreUI fill:#e0e0e0,stroke:#333,stroke-width:1px
```
