# davidsmfreire/shinemonitor-api architecture

> Architecture diagram of the GitHub repository davidsmfreire/shinemonitor-api, 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/davidsmfreire/shinemonitor-api
- Repository: https://github.com/davidsmfreire/shinemonitor-api

## Overview

ShineMonitor API is a multi-language client suite for the vendor inverter-cloud API, with a Home Assistant integration as a user-facing consumer. The main workflow is authenticate, enumerate account devices, then fetch live or historical readings; the clients also expose broader plant, collector, device-management, and energy actions. Edges reflect the sampled Python, Rust, and Go call paths and documented repository layout; unsampled integration and client internals are represented only where supported by the tree or README.

Main entry points: [`python/shinemonitor_api/_client_async.py`](https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_client_async.py) (Python async client), [`python/shinemonitor_api/_actions.py`](https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_actions.py) (URLs and parsing), [`python/shinemonitor_api/_client_sync.py`](https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_client_sync.py) (Python sync client), [`rust/src/lib.rs`](https://github.com/davidsmfreire/shinemonitor-api/blob/main/rust/src/lib.rs) (Rust client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["API clients"]
  node_py_sync["Python sync client<br/>[_client_sync.py]"]
  node_py_async["Python async client<br/>[_client_async.py]"]
  node_py_methods["Generated actions<br/>[_methods.py]"]
  node_py_actions["URLs and parsing<br/>[_actions.py]"]
  node_protocol["Auth and protocol<br/>[_protocol.py]"]
  node_models["Response models<br/>[models.py]"]
  node_rust["Rust client<br/>[lib.rs]"]
  node_rust_actions["Rust actions<br/>[actions.rs]"]
  node_go["Go client<br/>[client.go]"]
  node_go_actions["Go actions<br/>[actions.go]"]
end

subgraph group_domain["API contract"]
  node_spec["Endpoint catalog<br/>[endpoints.yaml]"]
  node_schemas["Data schemas"]
end

subgraph group_homeassistant["Home Assistant"]
  node_ha_flow["Integration setup<br/>[config_flow.py]"]
  node_ha_setup["Integration lifecycle<br/>[__init__.py]"]
  node_coordinator["Polling coordinator<br/>[coordinator.py]"]
  node_sensors["Inverter sensors<br/>[sensor.py]"]
end

node_user(("API consumer"))
node_vendor["ShineMonitor API"]
node_ha_user(("Home Assistant user"))

node_user -->|"uses client"| node_py_sync
node_user -->|"uses client"| node_py_async
node_user -->|"uses client"| node_rust
node_user -->|"uses client"| node_go
node_py_sync -->|"builds auth requests"| node_protocol
node_py_async -->|"builds auth requests"| node_protocol
node_py_sync -->|"builds URLs; parses replies"| node_py_actions
node_py_async -->|"builds URLs; parses replies"| node_py_actions
node_py_sync -->|"inherits actions"| node_py_methods
node_py_async -->|"inherits actions"| node_py_methods
node_py_methods -->|"builds URLs; parses replies"| node_py_actions
node_py_actions -->|"maps response data"| node_models
node_py_sync -->|"sends HTTP requests"| node_vendor
node_py_async -->|"sends HTTP requests"| node_vendor
node_rust -->|"exposes actions"| node_rust_actions
node_rust_actions -->|"dispatches requests"| node_rust
node_rust -->|"sends HTTP requests"| node_vendor
node_go_actions -->|"dispatches requests"| node_go
node_go -->|"sends HTTP requests"| node_vendor
node_spec -->|"defines endpoints"| node_py_actions
node_spec -->|"defines endpoints"| node_rust_actions
node_spec -->|"defines endpoints"| node_go_actions
node_schemas -->|"describes daily data"| node_py_actions
node_ha_user -->|"configures integration"| node_ha_flow
node_ha_flow -->|"provides entry"| node_ha_setup
node_ha_setup -->|"starts polling"| node_coordinator
node_coordinator -->|"logs in; lists devices; fetches readings"| node_py_async
node_coordinator -->|"publishes snapshots"| node_sensors
node_sensors -->|"exposes measurements"| node_ha_user

click node_py_sync "https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_client_sync.py"
click node_py_async "https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_client_async.py"
click node_py_methods "https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_methods.py"
click node_py_actions "https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_actions.py"
click node_protocol "https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_protocol.py"
click node_models "https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/models.py"
click node_rust "https://github.com/davidsmfreire/shinemonitor-api/blob/main/rust/src/lib.rs"
click node_rust_actions "https://github.com/davidsmfreire/shinemonitor-api/blob/main/rust/src/actions.rs"
click node_go "https://github.com/davidsmfreire/shinemonitor-api/blob/main/go/client.go"
click node_go_actions "https://github.com/davidsmfreire/shinemonitor-api/blob/main/go/actions.go"
click node_spec "https://github.com/davidsmfreire/shinemonitor-api/blob/main/spec/endpoints.yaml"
click node_schemas "https://github.com/davidsmfreire/shinemonitor-api/blob/main/spec/daily_data_schema.json"
click node_ha_flow "https://github.com/davidsmfreire/shinemonitor-api/blob/main/custom_components/shinemonitor/config_flow.py"
click node_ha_setup "https://github.com/davidsmfreire/shinemonitor-api/blob/main/custom_components/shinemonitor/__init__.py"
click node_coordinator "https://github.com/davidsmfreire/shinemonitor-api/blob/main/custom_components/shinemonitor/coordinator.py"
click node_sensors "https://github.com/davidsmfreire/shinemonitor-api/blob/main/custom_components/shinemonitor/sensor.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_py_sync,node_py_async,node_py_methods,node_py_actions,node_protocol,node_models,node_rust,node_rust_actions,node_go,node_go_actions,node_ha_user toneBlue
class node_spec,node_schemas toneAmber
class node_ha_flow,node_ha_setup,node_coordinator,node_sensors,node_user,node_vendor toneMint
```

## Components

### API clients

- [Python sync client](https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_client_sync.py): `python/shinemonitor_api/_client_sync.py`
- [Python async client](https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_client_async.py): `python/shinemonitor_api/_client_async.py`
- [Generated actions](https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_methods.py): `python/shinemonitor_api/_methods.py`
- [URLs and parsing](https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_actions.py): `python/shinemonitor_api/_actions.py`
- [Auth and protocol](https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/_protocol.py): `python/shinemonitor_api/_protocol.py`
- [Response models](https://github.com/davidsmfreire/shinemonitor-api/blob/main/python/shinemonitor_api/models.py): `python/shinemonitor_api/models.py`
- [Rust client](https://github.com/davidsmfreire/shinemonitor-api/blob/main/rust/src/lib.rs): `rust/src/lib.rs`
- [Rust actions](https://github.com/davidsmfreire/shinemonitor-api/blob/main/rust/src/actions.rs): `rust/src/actions.rs`
- [Go client](https://github.com/davidsmfreire/shinemonitor-api/blob/main/go/client.go): `go/client.go`
- [Go actions](https://github.com/davidsmfreire/shinemonitor-api/blob/main/go/actions.go): `go/actions.go`

### API contract

- [Endpoint catalog](https://github.com/davidsmfreire/shinemonitor-api/blob/main/spec/endpoints.yaml): `spec/endpoints.yaml`
- [Data schemas](https://github.com/davidsmfreire/shinemonitor-api/blob/main/spec/daily_data_schema.json): `spec/daily_data_schema.json`

### Home Assistant

- [Integration setup](https://github.com/davidsmfreire/shinemonitor-api/blob/main/custom_components/shinemonitor/config_flow.py): `custom_components/shinemonitor/config_flow.py`
- [Integration lifecycle](https://github.com/davidsmfreire/shinemonitor-api/blob/main/custom_components/shinemonitor/__init__.py): `custom_components/shinemonitor/__init__.py`
- [Polling coordinator](https://github.com/davidsmfreire/shinemonitor-api/blob/main/custom_components/shinemonitor/coordinator.py): `custom_components/shinemonitor/coordinator.py`
- [Inverter sensors](https://github.com/davidsmfreire/shinemonitor-api/blob/main/custom_components/shinemonitor/sensor.py): `custom_components/shinemonitor/sensor.py`

### Other components

- **API consumer**
- **ShineMonitor API**
- **Home Assistant user**

## Connections

- API consumer → Python sync client: uses client
- API consumer → Python async client: uses client
- API consumer → Rust client: uses client
- API consumer → Go client: uses client
- Python sync client → Auth and protocol: builds auth requests
- Python async client → Auth and protocol: builds auth requests
- Python sync client → URLs and parsing: builds URLs; parses replies
- Python async client → URLs and parsing: builds URLs; parses replies
- Python sync client → Generated actions: inherits actions
- Python async client → Generated actions: inherits actions
- Generated actions → URLs and parsing: builds URLs; parses replies
- URLs and parsing → Response models: maps response data
- Python sync client → ShineMonitor API: sends HTTP requests
- Python async client → ShineMonitor API: sends HTTP requests
- Rust client → Rust actions: exposes actions
- Rust actions → Rust client: dispatches requests
- Rust client → ShineMonitor API: sends HTTP requests
- Go actions → Go client: dispatches requests
- Go client → ShineMonitor API: sends HTTP requests
- Endpoint catalog → URLs and parsing: defines endpoints
- Endpoint catalog → Rust actions: defines endpoints
- Endpoint catalog → Go actions: defines endpoints
- Data schemas → URLs and parsing: describes daily data
- Home Assistant user → Integration setup: configures integration
- Integration setup → Integration lifecycle: provides entry
- Integration lifecycle → Polling coordinator: starts polling
- Polling coordinator → Python async client: logs in; lists devices; fetches readings
- Polling coordinator → Inverter sensors: publishes snapshots
- Inverter sensors → Home Assistant user: exposes measurements