# mtrossbach/noah-mqtt architecture

> Architecture diagram of the GitHub repository mtrossbach/noah-mqtt, 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/mtrossbach/noah-mqtt
- Repository: https://github.com/mtrossbach/noah-mqtt

## Overview

noah-mqtt polls Growatt NOAH batteries, publishes device status, battery details, and parameters over MQTT, and accepts MQTT parameter commands when App API control is enabled. The main entry point selects App, Web, or combined mode; Web mode retrieves data, while parameter changes require the App API. Device discovery also configures Home Assistant through MQTT auto-discovery. The graph follows the sampled entry point and service code; unsampled configuration and API internals are represented only at their supported paths.

Main entry points: [`internal/endpoint_mqtt/endpoint_mqtt.go`](https://github.com/mtrossbach/noah-mqtt/blob/main/internal/endpoint_mqtt/endpoint_mqtt.go) (MQTT endpoint), [`cmd/noah-mqtt/main.go`](https://github.com/mtrossbach/noah-mqtt/blob/main/cmd/noah-mqtt/main.go) (Application entry), [`internal/growatt_web/service.go`](https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_web/service.go) (Web API service), [`internal/growatt_app/service.go`](https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_app/service.go) (App API service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application setup"]
  node_main["Application entry<br/>[main.go]"]
  node_config["Runtime configuration"]
end

subgraph group_growatt["Growatt integration"]
  node_growatt_app["App API service<br/>[service.go]"]
  node_app_polling["App polling<br/>[service_polling.go]"]
  node_app_client["App API client<br/>[client.go]"]
  node_growatt_web["Web API service<br/>[service.go]"]
  node_web_client["Web API client<br/>[client.go]"]
end

subgraph group_mqtt["MQTT interface"]
  node_endpoint["MQTT endpoint<br/>[endpoint_mqtt.go]"]
  node_payloads["Payload models<br/>[payload.go]"]
end

subgraph group_ha["Home Assistant discovery"]
  node_ha_service["Discovery service<br/>[service.go]"]
end

node_user(("Operator"))
node_growatt_app_api(("Growatt App API"))
node_growatt_web_api(("Growatt Web API"))
node_mqtt_broker(("MQTT broker"))
node_home_assistant(("Home Assistant"))

node_user -->|"starts"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"creates endpoint"| node_endpoint
node_main -->|"selects App mode"| node_growatt_app
node_main -->|"selects Web mode"| node_growatt_web
node_main -->|"selects combined mode"| node_growatt_web
node_main -.->|"enables parameter control"| node_growatt_app
node_growatt_app -->|"fetches and sets"| node_app_client
node_growatt_web -->|"fetches data"| node_web_client
node_app_client -->|"requests API data"| node_growatt_app_api
node_web_client -->|"requests API data"| node_growatt_web_api
node_growatt_app -->|"starts polling"| node_app_polling
node_app_polling -->|"fetches status and details"| node_app_client
node_growatt_web -->|"enumerates and polls devices"| node_web_client
node_app_polling -->|"builds payloads"| node_payloads
node_growatt_web -->|"builds payloads"| node_payloads
node_growatt_app -->|"sets devices"| node_endpoint
node_growatt_web -->|"sets devices"| node_endpoint
node_app_polling -->|"publishes polled data"| node_endpoint
node_growatt_web -->|"publishes polled data"| node_endpoint
node_endpoint -->|"publishes state"| node_mqtt_broker
node_mqtt_broker -->|"delivers parameter commands"| node_endpoint
node_endpoint -.->|"applies parameter changes"| node_growatt_app
node_endpoint -->|"provides device details"| node_ha_service
node_ha_service -->|"publishes discovery"| node_mqtt_broker
node_home_assistant -->|"consumes discovery"| node_mqtt_broker

click node_main "https://github.com/mtrossbach/noah-mqtt/blob/main/cmd/noah-mqtt/main.go"
click node_config "https://github.com/mtrossbach/noah-mqtt/tree/main/internal/config"
click node_growatt_app "https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_app/service.go"
click node_app_polling "https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_app/service_polling.go"
click node_app_client "https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_app/client.go"
click node_growatt_web "https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_web/service.go"
click node_web_client "https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_web/client.go"
click node_endpoint "https://github.com/mtrossbach/noah-mqtt/blob/main/internal/endpoint_mqtt/endpoint_mqtt.go"
click node_payloads "https://github.com/mtrossbach/noah-mqtt/blob/main/pkg/models/payload.go"
click node_ha_service "https://github.com/mtrossbach/noah-mqtt/blob/main/internal/homeassistant/service.go"

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_main,node_config toneBlue
class node_growatt_app,node_app_polling,node_app_client,node_growatt_web,node_web_client toneAmber
class node_endpoint,node_payloads,node_growatt_app_api,node_growatt_web_api toneMint
class node_ha_service toneRose
class node_user,node_mqtt_broker,node_home_assistant toneIndigo
```

## Components

### Application setup

- [Application entry](https://github.com/mtrossbach/noah-mqtt/blob/main/cmd/noah-mqtt/main.go): `cmd/noah-mqtt/main.go`
- [Runtime configuration](https://github.com/mtrossbach/noah-mqtt/tree/main/internal/config): `internal/config`

### Growatt integration

- [App API service](https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_app/service.go): `internal/growatt_app/service.go`
- [App polling](https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_app/service_polling.go): `internal/growatt_app/service_polling.go`
- [App API client](https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_app/client.go): `internal/growatt_app/client.go`
- [Web API service](https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_web/service.go): `internal/growatt_web/service.go`
- [Web API client](https://github.com/mtrossbach/noah-mqtt/blob/main/internal/growatt_web/client.go): `internal/growatt_web/client.go`

### MQTT interface

- [MQTT endpoint](https://github.com/mtrossbach/noah-mqtt/blob/main/internal/endpoint_mqtt/endpoint_mqtt.go): `internal/endpoint_mqtt/endpoint_mqtt.go`
- [Payload models](https://github.com/mtrossbach/noah-mqtt/blob/main/pkg/models/payload.go): `pkg/models/payload.go`

### Home Assistant discovery

- [Discovery service](https://github.com/mtrossbach/noah-mqtt/blob/main/internal/homeassistant/service.go): `internal/homeassistant/service.go`

### Other components

- **Operator**
- **Growatt App API**
- **Growatt Web API**
- **MQTT broker**
- **Home Assistant**

## Connections

- Operator → Application entry: starts
- Application entry → Runtime configuration: loads settings
- Application entry → MQTT endpoint: creates endpoint
- Application entry → App API service: selects App mode
- Application entry → Web API service: selects Web mode
- Application entry → Web API service: selects combined mode
- Application entry → App API service: enables parameter control
- App API service → App API client: fetches and sets
- Web API service → Web API client: fetches data
- App API client → Growatt App API: requests API data
- Web API client → Growatt Web API: requests API data
- App API service → App polling: starts polling
- App polling → App API client: fetches status and details
- Web API service → Web API client: enumerates and polls devices
- App polling → Payload models: builds payloads
- Web API service → Payload models: builds payloads
- App API service → MQTT endpoint: sets devices
- Web API service → MQTT endpoint: sets devices
- App polling → MQTT endpoint: publishes polled data
- Web API service → MQTT endpoint: publishes polled data
- MQTT endpoint → MQTT broker: publishes state
- MQTT broker → MQTT endpoint: delivers parameter commands
- MQTT endpoint → App API service: applies parameter changes
- MQTT endpoint → Discovery service: provides device details
- Discovery service → MQTT broker: publishes discovery
- Home Assistant → MQTT broker: consumes discovery