# waveguide/go-growatt architecture

> Architecture diagram of the GitHub repository waveguide/go-growatt, 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/waveguide/go-growatt
- Repository: https://github.com/waveguide/go-growatt

## Overview

Go-Growatt reads Growatt inverter telemetry over Modbus, publishes stats and state changes to MQTT, and accepts MQTT commands to limit active power. The principal workflow is configuration and startup, inverter polling and decoding, then MQTT publication; command messages travel back through the application to the inverter. The README also describes an optional serial-over-TCP bridge. Inverter internals are only partially sampled, so the graph shows documented register, time, and power-control behavior without inferring unshown call details.

Main entry points: [`inverter/inverter.go`](https://github.com/waveguide/go-growatt/blob/main/inverter/inverter.go) (Polling and reconnect), [`mqtt/mqtt.go`](https://github.com/waveguide/go-growatt/blob/main/mqtt/mqtt.go) (MQTT client), [`main.go`](https://github.com/waveguide/go-growatt/blob/main/main.go) (Application coordinator), [`ser2net.py`](https://github.com/waveguide/go-growatt/blob/main/ser2net.py) (Serial-TCP bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["Application coordinator<br/>[main.go]"]
  node_config_reader["Config loading<br/>[main.go]"]
  node_logger["Logging setup<br/>[logger.go]"]
  node_command_handler["Power command handling<br/>[main.go]"]
  node_stats_publisher["Stats and state publishing<br/>[main.go]"]
end

subgraph group_inverter["Inverter access"]
  node_inverter_runner["Polling and reconnect<br/>[inverter.go]"]
  node_modbus["Modbus register access<br/>[inverter.go]"]
  node_stats_decode["Stats decoding<br/>[inverter.go]"]
  node_time_sync["Inverter time sync<br/>[inverter.go]"]
  node_power_control["Active power control<br/>[inverter.go]"]
end

subgraph group_messaging["MQTT messaging"]
  node_mqtt_client["MQTT client<br/>[mqtt.go]"]
end

subgraph group_bridge["Serial bridge"]
  node_serial_bridge["Serial-TCP bridge<br/>[ser2net.py]"]
end

node_operator(("Operator"))
node_config["YAML config"]
node_broker(("MQTT broker"))
node_inverter_device(("Growatt inverter"))
node_serial_device(("Serial device"))
node_tcp_client(("Remote TCP client"))

node_operator -->|"supplies"| node_config
node_main -->|"loads config"| node_config_reader
node_config_reader -->|"reads"| node_config
node_main -->|"sets up"| node_logger
node_main -->|"initializes"| node_mqtt_client
node_mqtt_client -->|"connects"| node_broker
node_main -->|"subscribes"| node_mqtt_client
node_broker -->|"delivers commands"| node_mqtt_client
node_mqtt_client -->|"invokes callback"| node_command_handler
node_command_handler -->|"queues power rate"| node_inverter_runner
node_main -->|"starts polling"| node_inverter_runner
node_inverter_runner -->|"reads registers"| node_modbus
node_modbus -->|"reads and writes"| node_inverter_device
node_inverter_runner -->|"decodes readings"| node_stats_decode
node_inverter_runner -->|"checks and updates time"| node_time_sync
node_inverter_runner -->|"applies commands"| node_power_control
node_power_control -->|"writes registers"| node_modbus
node_inverter_runner -->|"sends stats"| node_stats_publisher
node_stats_publisher -->|"publishes data and state"| node_mqtt_client
node_mqtt_client -->|"publishes messages"| node_broker
node_serial_bridge -.->|"shuttles bytes"| node_serial_device
node_serial_bridge -.->|"shuttles bytes"| node_tcp_client
node_tcp_client -.->|"connects"| node_serial_bridge

click node_main "https://github.com/waveguide/go-growatt/blob/main/main.go"
click node_config_reader "https://github.com/waveguide/go-growatt/blob/main/main.go"
click node_logger "https://github.com/waveguide/go-growatt/blob/main/logger/logger.go"
click node_mqtt_client "https://github.com/waveguide/go-growatt/blob/main/mqtt/mqtt.go"
click node_command_handler "https://github.com/waveguide/go-growatt/blob/main/main.go"
click node_stats_publisher "https://github.com/waveguide/go-growatt/blob/main/main.go"
click node_inverter_runner "https://github.com/waveguide/go-growatt/blob/main/inverter/inverter.go"
click node_modbus "https://github.com/waveguide/go-growatt/blob/main/inverter/inverter.go"
click node_stats_decode "https://github.com/waveguide/go-growatt/blob/main/inverter/inverter.go"
click node_time_sync "https://github.com/waveguide/go-growatt/blob/main/inverter/inverter.go"
click node_power_control "https://github.com/waveguide/go-growatt/blob/main/inverter/inverter.go"
click node_serial_bridge "https://github.com/waveguide/go-growatt/blob/main/ser2net.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_main,node_config_reader,node_logger,node_command_handler,node_stats_publisher,node_tcp_client toneBlue
class node_inverter_runner,node_modbus,node_stats_decode,node_time_sync,node_power_control toneAmber
class node_mqtt_client toneMint
class node_serial_bridge toneRose
class node_operator,node_config,node_broker,node_inverter_device,node_serial_device toneIndigo
```

## Components

### Application

- [Application coordinator](https://github.com/waveguide/go-growatt/blob/main/main.go): `main.go`
- [Config loading](https://github.com/waveguide/go-growatt/blob/main/main.go): `main.go`
- [Logging setup](https://github.com/waveguide/go-growatt/blob/main/logger/logger.go): `logger/logger.go`
- [Power command handling](https://github.com/waveguide/go-growatt/blob/main/main.go): `main.go`
- [Stats and state publishing](https://github.com/waveguide/go-growatt/blob/main/main.go): `main.go`

### Inverter access

- [Polling and reconnect](https://github.com/waveguide/go-growatt/blob/main/inverter/inverter.go): `inverter/inverter.go`
- [Modbus register access](https://github.com/waveguide/go-growatt/blob/main/inverter/inverter.go): `inverter/inverter.go`
- [Stats decoding](https://github.com/waveguide/go-growatt/blob/main/inverter/inverter.go): `inverter/inverter.go`
- [Inverter time sync](https://github.com/waveguide/go-growatt/blob/main/inverter/inverter.go): `inverter/inverter.go`
- [Active power control](https://github.com/waveguide/go-growatt/blob/main/inverter/inverter.go): `inverter/inverter.go`

### MQTT messaging

- [MQTT client](https://github.com/waveguide/go-growatt/blob/main/mqtt/mqtt.go): `mqtt/mqtt.go`

### Serial bridge

- [Serial-TCP bridge](https://github.com/waveguide/go-growatt/blob/main/ser2net.py): `ser2net.py`

### Other components

- **Operator**
- **YAML config**
- **MQTT broker**
- **Growatt inverter**
- **Serial device**
- **Remote TCP client**

## Connections

- Operator → YAML config: supplies
- Application coordinator → Config loading: loads config
- Config loading → YAML config: reads
- Application coordinator → Logging setup: sets up
- Application coordinator → MQTT client: initializes
- MQTT client → MQTT broker: connects
- Application coordinator → MQTT client: subscribes
- MQTT broker → MQTT client: delivers commands
- MQTT client → Power command handling: invokes callback
- Power command handling → Polling and reconnect: queues power rate
- Application coordinator → Polling and reconnect: starts polling
- Polling and reconnect → Modbus register access: reads registers
- Modbus register access → Growatt inverter: reads and writes
- Polling and reconnect → Stats decoding: decodes readings
- Polling and reconnect → Inverter time sync: checks and updates time
- Polling and reconnect → Active power control: applies commands
- Active power control → Modbus register access: writes registers
- Polling and reconnect → Stats and state publishing: sends stats
- Stats and state publishing → MQTT client: publishes data and state
- MQTT client → MQTT broker: publishes messages
- Serial-TCP bridge → Serial device: shuttles bytes
- Serial-TCP bridge → Remote TCP client: shuttles bytes
- Remote TCP client → Serial-TCP bridge: connects