# pszypowicz/ampio-mqtt architecture

> Architecture diagram of the GitHub repository pszypowicz/ampio-mqtt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pszypowicz/ampio-mqtt
- Repository: https://github.com/pszypowicz/ampio-mqtt

## Overview

ampio-mqtt is a Home Assistant-agnostic async client for the Ampio M-SERV local MQTT protocol. The main workflow is LAN discovery (optional), client connection and catalogue loading, protocol decoding into typed state, then event delivery and object commands. The graph also preserves classification, room/scene data, admin-only module and raw-channel features, and diagnostics. Source excerpts show the client, transport, protocol, and store boundaries; less-visible capabilities are included where documented in the README, without asserting their internal wiring.

Main entry points: [`src/ampio_mqtt/client.py`](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/client.py) (Ampio client), [`src/ampio_mqtt/_store.py`](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/_store.py) (State store), [`src/ampio_mqtt/_connection.py`](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/_connection.py) (MQTT connection), [`src/ampio_mqtt/_protocol.py`](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/_protocol.py) (Wire protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client API"]
  node_client_api["Ampio client<br/>[client.py]"]
  node_command_surface["Commands and admin<br/>[client.py]"]
end

subgraph group_runtime["MQTT Runtime"]
  node_connection["MQTT connection<br/>[_connection.py]"]
  node_protocol["Wire protocol<br/>[_protocol.py]"]
end

subgraph group_domain["Domain State"]
  node_store["State store<br/>[_store.py]"]
  node_models["Typed models<br/>[models.py]"]
  node_classification["Object classification<br/>[classification.py]"]
  node_device_types["Device type metadata<br/>[device_types.py]"]
  node_events["Typed event stream<br/>[events.py]"]
  node_errors["Errors<br/>[errors.py]"]
end

subgraph group_discovery["LAN Discovery"]
  node_discovery_api["LAN discovery<br/>[discovery.py]"]
end

node_consumer(("Library consumer"))
node_lan(("Ampio LAN"))
node_broker(("MQTT broker"))
node_ampio_server(("Ampio M-SERV"))

node_consumer -->|"discovers"| node_discovery_api
node_discovery_api -->|"queries mDNS"| node_lan
node_consumer -->|"creates client"| node_client_api
node_client_api -->|"opens session"| node_connection
node_connection -->|"connects and publishes"| node_broker
node_broker -->|"delivers messages"| node_connection
node_connection -->|"forwards messages"| node_client_api
node_client_api -->|"routes wire data"| node_protocol
node_protocol -->|"decodes replies"| node_store
node_client_api -->|"applies updates"| node_store
node_store -->|"classifies objects"| node_classification
node_store -->|"builds state"| node_models
node_models -->|"uses kind definitions"| node_classification
node_models -->|"uses metadata"| node_device_types
node_client_api -->|"dispatches updates"| node_events
node_store -->|"produces store events"| node_events
node_client_api -->|"exposes commands"| node_command_surface
node_command_surface -->|"builds wire requests"| node_protocol
node_protocol -->|"speaks MQTT protocol"| node_ampio_server
node_client_api -->|"raises client errors"| node_errors

click node_client_api "https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/client.py"
click node_command_surface "https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/client.py"
click node_discovery_api "https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/discovery.py"
click node_connection "https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/_connection.py"
click node_protocol "https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/_protocol.py"
click node_store "https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/_store.py"
click node_models "https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/models.py"
click node_classification "https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/classification.py"
click node_device_types "https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/device_types.py"
click node_events "https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/events.py"
click node_errors "https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/errors.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_client_api,node_command_surface toneBlue
class node_connection,node_protocol toneAmber
class node_store,node_models,node_classification,node_device_types,node_events,node_errors toneMint
class node_discovery_api toneRose
class node_consumer,node_lan,node_broker,node_ampio_server toneIndigo
```

## Components

### Client API

- [Ampio client](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/client.py): `src/ampio_mqtt/client.py`
- [Commands and admin](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/client.py): `src/ampio_mqtt/client.py`

### MQTT Runtime

- [MQTT connection](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/_connection.py): `src/ampio_mqtt/_connection.py`
- [Wire protocol](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/_protocol.py): `src/ampio_mqtt/_protocol.py`

### Domain State

- [State store](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/_store.py): `src/ampio_mqtt/_store.py`
- [Typed models](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/models.py): `src/ampio_mqtt/models.py`
- [Object classification](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/classification.py): `src/ampio_mqtt/classification.py`
- [Device type metadata](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/device_types.py): `src/ampio_mqtt/device_types.py`
- [Typed event stream](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/events.py): `src/ampio_mqtt/events.py`
- [Errors](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/errors.py): `src/ampio_mqtt/errors.py`

### LAN Discovery

- [LAN discovery](https://github.com/pszypowicz/ampio-mqtt/blob/main/src/ampio_mqtt/discovery.py): `src/ampio_mqtt/discovery.py`

### Other components

- **Library consumer**
- **Ampio LAN**
- **MQTT broker**
- **Ampio M-SERV**

## Connections

- Library consumer → LAN discovery: discovers (evidence: `README.md`)
- LAN discovery → Ampio LAN: queries mDNS (evidence: `src/ampio_mqtt/discovery.py`)
- Library consumer → Ampio client: creates client (evidence: `README.md`)
- Ampio client → MQTT connection: opens session (evidence: `src/ampio_mqtt/client.py`)
- MQTT connection → MQTT broker: connects and publishes (evidence: `README.md`)
- MQTT broker → MQTT connection: delivers messages (evidence: `src/ampio_mqtt/_connection.py`)
- MQTT connection → Ampio client: forwards messages (evidence: `src/ampio_mqtt/_connection.py`)
- Ampio client → Wire protocol: routes wire data (evidence: `src/ampio_mqtt/client.py`)
- Wire protocol → State store: decodes replies (evidence: `src/ampio_mqtt/_store.py`)
- Ampio client → State store: applies updates (evidence: `src/ampio_mqtt/client.py`)
- State store → Object classification: classifies objects (evidence: `src/ampio_mqtt/_store.py`)
- State store → Typed models: builds state (evidence: `src/ampio_mqtt/_store.py`)
- Typed models → Object classification: uses kind definitions (evidence: `src/ampio_mqtt/models.py`)
- Typed models → Device type metadata: uses metadata (evidence: `src/ampio_mqtt/models.py`)
- Ampio client → Typed event stream: dispatches updates (evidence: `src/ampio_mqtt/client.py`)
- State store → Typed event stream: produces store events (evidence: `src/ampio_mqtt/_store.py`)
- Ampio client → Commands and admin: exposes commands (evidence: `README.md`)
- Commands and admin → Wire protocol: builds wire requests (evidence: `src/ampio_mqtt/client.py`)
- Wire protocol → Ampio M-SERV: speaks MQTT protocol (evidence: `README.md`)
- Ampio client → Errors: raises client errors (evidence: `src/ampio_mqtt/client.py`)