# tolwi/hassio-ecoflow-cloud architecture

> Architecture diagram of the GitHub repository tolwi/hassio-ecoflow-cloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tolwi/hassio-ecoflow-cloud
- Repository: https://github.com/tolwi/hassio-ecoflow-cloud

## Overview

##### Project Type and Purpose
- This is a Home Assistant custom integration (Python package under custom_components/ecoflow_cloud) that connects Home Assistant to the EcoFlow Cloud via MQTT and HTTP APIs.
- Purpose: monitor and control EcoFlow devices (Delta, River, Glacier, PowerStream, etc.) by subscribing to an MQTT broker and/or calling public/private REST APIs, then expose device attributes as HA entities (sensors, switches, numbers, selects, buttons).

##### File Structure
Top-level directories of interest:
- .devcontainer, .github – dev/test tooling, CI.
- custom_components/ecoflow_cloud – the core integration:
– api/ (ecoflow_mqtt.py, private_api.py, public_api.py, message.py)
– devices/internal (Protobuf definitions, device‐specific parsers)
– devices/public (device classes for public API responses)
– registry.py & data_holder.py – in-memory device/state registry
– config_flow.py – user-facing setup
– sensor.py, switch.py, number.py, select.py, button.py – HA platform entry points
– diagnostics.py, recorder.py – HA diagnostics & data persistence
– manifest.json, translations/ – metadata
- docs/ – human-readable documentation (integration.md, device docs)

##### README for Additional Insights
- Integration uses MQTT broker mqtt.ecoflow.com to receive device telemetry.
- Falls back (or parallely uses) REST-based private_api & public_api for control & state retrieval.
- Supports dozens of device models, each with its own sensor/switch definitions.

##### Main Components & Their Relationships

[ Home Assistant Core ]
↓ loads
[ ecoflow_cloud Integration ]
- config_flow.py
- manifest.json / translations
- startup orchestration
↓
┌────────────────────────────────────────────┐
│                API Layer                  │
│ ┌───────────────┐  ┌───────────────┐      │
│ │  MQTT Client  │◀─┤ecoflow_mqtt.py│      │
│ └───────────────┘  └───────────────┘      │
│        │             ▲                    │
│        │ subscribe   │ publish / subscribe│
│        ▼             │                    │
│ ┌───────────────────────────────────────┐ │
│ │     Private API (HTTP/REST)          │ │
│ │     public_api.py & private_api.py   │ │
│ └───────────────────────────────────────┘ │
│        │             │                    │
│        ▼             ▼                    │
│  [ EcoFlow Cloud Services ]              │
│  – mqtt.ecoflow.com (Broker)             │
│  – ecoflow.com REST endpoints            │
└────────────────────────────────────────────┘
↓  decode messages via Protobuf           │
[ Domain / Device Layer ]                   │
- data_holder.py (state aggregation)      │
- devices/internal/*.py (Protobuf parsers)│
- devices/public/*.py (API wrappers)      │
- registry.py (map device → HA entities)  │
↓
[ HA Platforms (entity factories) ]
- sensor.py → SensorEntity
- switch.py → SwitchEntity
- number.py → NumberEntity
- select.py → SelectEntity
- button.py → ButtonEntity
- recorder.py / diagnostics.py
↓
[ Home Assistant UI / State Machine ]

##### Architectural Patterns & Principles
- Layered architecture:
– API Layer (MQTT + HTTP)
– Domain / Model Layer (device classes, data holder, registry)
– Platform Layer (HA entity adapters)
- Observer/Event pattern: MQTT messages or API callbacks trigger state updates.
- Protobuf code generation (proto files → _pb2.py) to decode binary messages.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Home Assistant"
        HA["Home Assistant Core"]:::external
    end

    subgraph "Integration Entry" 
        IC["Integration Entry Point"]:::ui
        CF["Configuration Flow"]:::ui
        MF["Manifest"]:::ui
        TR["Translations"]:::ui
    end

    HA -->|"loads"| IC
    IC --> CF
    IC --> MF
    IC --> TR

    subgraph "API Layer"
        MC["MQTT Client"]:::api
        MD["Message Definitions"]:::api
        PR["Private REST API Client"]:::api
        PU["Public REST API Client"]:::api
    end

    CF -->|"init API"| MC
    CF -->|"init API"| PR
    CF -->|"init API"| PU

    subgraph "EcoFlow Cloud Services"
        EB["mqtt.ecoflow.com Broker"]:::external
        ER["EcoFlow REST Endpoints"]:::external
    end

    MC -->|"subscribe/publish"| EB
    PR -->|"HTTPS"| ER
    PU -->|"HTTPS"| ER
    EB --> MD
    MD --> MC

    subgraph "Domain / Model Layer"
        SH["In-Memory State Holder"]:::domain
        RG["Device Registry"]:::domain
        IP["Internal Device Parsers"]:::domain
        PD["Protobuf Definitions"]:::domain
        PW["Public Device Wrappers"]:::domain
        PL["Preload Protobuf Helper"]:::domain
        DH["Device-agnostic Helpers"]:::domain
    end

    EB -->|"MQTT msg"| IP
    IP -->|"decode"| SH
    PD --> IP
    PR -->|"data"| PW
    PU -->|"data"| PW
    PW --> SH
    SH --> RG
    PL --> PD
    DH --> RG

    subgraph "HA Platforms"
        SN["Sensor Platform"]:::platform
        SW["Switch Platform"]:::platform
        NB["Number Platform"]:::platform
        SL["Select Platform"]:::platform
        BT["Button Platform"]:::platform
        DG["Diagnostics Support"]:::platform
        RC["Recorder"]:::platform
    end

    RG --> SN
    RG --> SW
    RG --> NB
    RG --> SL
    RG --> BT
    RG --> DG
    RG --> RC

    SN -->|"actions"| PR
    SW -->|"actions"| PR
    NB -->|"actions"| PR
    SL -->|"actions"| PR
    BT -->|"actions"| PR

    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef api fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef domain fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef platform fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef ui fill:#e1bee7,stroke:#333,stroke-width:1px

    click IC "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/__init__.py"
    click CF "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/config_flow.py"
    click MF "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/manifest.json"
    click TR "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/translations/*.json"
    click MC "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/api/ecoflow_mqtt.py"
    click MD "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/api/message.py"
    click PR "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/api/private_api.py"
    click PU "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/api/public_api.py"
    click SH "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/devices/data_holder.py"
    click RG "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/devices/registry.py"
    click IP "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/devices/internal/*.py"
    click PD "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/devices/internal/proto/*.proto"
    click PW "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/devices/public/*.py"
    click SN "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/sensor.py"
    click SW "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/switch.py"
    click NB "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/number.py"
    click SL "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/select.py"
    click BT "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/button.py"
    click DG "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/diagnostics.py"
    click RC "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/recorder.py"
    click PL "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/_preload_proto.py"
    click DH "https://github.com/tolwi/hassio-ecoflow-cloud/blob/main/custom_components/ecoflow_cloud/device_data.py"
```
