# espressif/esp-mqtt architecture

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

- Interactive diagram: https://gitdiagram.com/espressif/esp-mqtt
- Repository: https://github.com/espressif/esp-mqtt

## Overview

ESP-MQTT is an ESP-IDF MQTT client supporting MQTT 3.1.1 and 5.0 over TCP, TLS, WebSocket, and secure WebSocket. Applications configure and start one or more clients, then publish or subscribe; the client runtime handles transport connection, MQTT packet exchange, QoS acknowledgments, retransmission state, and event delivery. Packet codecs and the outbox are distinct internal layers. The README documents the protocol and transport capabilities; excerpts show transport selection and message reception, but not enough of the runtime call graph to assert most internal links.

Main entry points: [`mqtt_client.c`](https://github.com/espressif/esp-mqtt/blob/master/mqtt_client.c) (Client Runtime), [`mqtt5_client.c`](https://github.com/espressif/esp-mqtt/blob/master/mqtt5_client.c) (MQTT 5 Runtime), [`include/mqtt_client.h`](https://github.com/espressif/esp-mqtt/blob/master/include/mqtt_client.h) (Client API), [`include/mqtt5_client.h`](https://github.com/espressif/esp-mqtt/blob/master/include/mqtt5_client.h) (MQTT 5 API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client API"]
  node_client_api["Client API<br/>[mqtt_client.h]"]
  node_mqtt5_api["MQTT 5 API<br/>[mqtt5_client.h]"]
  node_common_types["Common Types<br/>[mqtt_common.h]"]
end

subgraph group_runtime["Client Runtime"]
  node_client_runtime["Client Runtime<br/>[mqtt_client.c]"]
  node_mqtt5_runtime["MQTT 5 Runtime<br/>[mqtt5_client.c]"]
  node_client_state["Client State<br/>[mqtt_client_priv.h]"]
  node_mqtt5_state["MQTT 5 State"]
  node_transport["Transport Adapters<br/>[mqtt_client.c]"]
  node_utilities["URI Utilities<br/>[mqtt_utils.c]"]
end

subgraph group_protocol["MQTT Protocol"]
  node_message_codec["MQTT Codec<br/>[mqtt_msg.c]"]
  node_message_format["MQTT Message Model<br/>[mqtt_msg.h]"]
  node_mqtt5_codec["MQTT 5 Codec<br/>[mqtt5_msg.c]"]
  node_mqtt5_format["MQTT 5 Message Model<br/>[mqtt5_msg.h]"]
end

subgraph group_state["Delivery State"]
  node_outbox[("QoS Outbox<br/>[mqtt_outbox.c]")]
  node_outbox_api["Outbox Interface<br/>[mqtt_outbox.h]"]
  node_platform["Platform Helpers<br/>[platform.c]"]
end

node_application(("Application"))
node_broker(("MQTT Broker"))

node_application -.->|"configures client"| node_client_api
node_client_api -.->|"starts runtime"| node_client_runtime
node_application -.->|"sets MQTT 5 options"| node_mqtt5_api
node_mqtt5_api -.->|"configures protocol"| node_mqtt5_runtime
node_client_runtime -->|"selects transport"| node_transport
node_client_runtime -.->|"exchanges packets"| node_broker
node_broker -.->|"returns packets"| node_client_runtime
node_client_runtime -.->|"decodes packets"| node_message_codec
node_message_codec -.->|"uses model"| node_message_format
node_mqtt5_runtime -.->|"encodes properties"| node_mqtt5_codec
node_mqtt5_codec -.->|"uses model"| node_mqtt5_format
node_mqtt5_runtime -.->|"extends runtime"| node_client_runtime
node_client_runtime -.->|"uses state"| node_client_state
node_mqtt5_runtime -.->|"uses state"| node_mqtt5_state
node_client_runtime -.->|"queues delivery"| node_outbox
node_outbox -.->|"implements interface"| node_outbox_api
node_client_runtime -.->|"parses URI"| node_utilities
node_client_runtime -.->|"uses helpers"| node_platform

click node_client_api "https://github.com/espressif/esp-mqtt/blob/master/include/mqtt_client.h"
click node_mqtt5_api "https://github.com/espressif/esp-mqtt/blob/master/include/mqtt5_client.h"
click node_common_types "https://github.com/espressif/esp-mqtt/blob/master/include/mqtt_common.h"
click node_client_runtime "https://github.com/espressif/esp-mqtt/blob/master/mqtt_client.c"
click node_mqtt5_runtime "https://github.com/espressif/esp-mqtt/blob/master/mqtt5_client.c"
click node_client_state "https://github.com/espressif/esp-mqtt/blob/master/lib/include/mqtt_client_priv.h"
click node_mqtt5_state "https://github.com/espressif/esp-mqtt/blob/master/lib/include/mqtt5_client_priv.h"
click node_transport "https://github.com/espressif/esp-mqtt/blob/master/mqtt_client.c"
click node_message_codec "https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_msg/mqtt_msg.c"
click node_message_format "https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_msg/include/mqtt_msg.h"
click node_mqtt5_codec "https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_msg/mqtt5_msg.c"
click node_mqtt5_format "https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_msg/include/mqtt5_msg.h"
click node_outbox "https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_outbox.c"
click node_outbox_api "https://github.com/espressif/esp-mqtt/blob/master/lib/include/mqtt_outbox.h"
click node_platform "https://github.com/espressif/esp-mqtt/blob/master/lib/platform.c"
click node_utilities "https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_utils/mqtt_utils.c"

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_mqtt5_api,node_common_types toneBlue
class node_client_runtime,node_mqtt5_runtime,node_client_state,node_mqtt5_state,node_transport,node_utilities toneAmber
class node_message_codec,node_message_format,node_mqtt5_codec,node_mqtt5_format toneMint
class node_outbox,node_outbox_api,node_platform toneRose
class node_application,node_broker toneIndigo
```

## Components

### Client API

- [Client API](https://github.com/espressif/esp-mqtt/blob/master/include/mqtt_client.h): `include/mqtt_client.h`
- [MQTT 5 API](https://github.com/espressif/esp-mqtt/blob/master/include/mqtt5_client.h): `include/mqtt5_client.h`
- [Common Types](https://github.com/espressif/esp-mqtt/blob/master/include/mqtt_common.h): `include/mqtt_common.h`

### Client Runtime

- [Client Runtime](https://github.com/espressif/esp-mqtt/blob/master/mqtt_client.c): `mqtt_client.c`
- [MQTT 5 Runtime](https://github.com/espressif/esp-mqtt/blob/master/mqtt5_client.c): `mqtt5_client.c`
- [Client State](https://github.com/espressif/esp-mqtt/blob/master/lib/include/mqtt_client_priv.h): `lib/include/mqtt_client_priv.h`
- [MQTT 5 State](https://github.com/espressif/esp-mqtt/blob/master/lib/include/mqtt5_client_priv.h): `lib/include/mqtt5_client_priv.h`
- [Transport Adapters](https://github.com/espressif/esp-mqtt/blob/master/mqtt_client.c): `mqtt_client.c`
- [URI Utilities](https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_utils/mqtt_utils.c): `lib/mqtt_utils/mqtt_utils.c`

### MQTT Protocol

- [MQTT Codec](https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_msg/mqtt_msg.c): `lib/mqtt_msg/mqtt_msg.c`
- [MQTT Message Model](https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_msg/include/mqtt_msg.h): `lib/mqtt_msg/include/mqtt_msg.h`
- [MQTT 5 Codec](https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_msg/mqtt5_msg.c): `lib/mqtt_msg/mqtt5_msg.c`
- [MQTT 5 Message Model](https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_msg/include/mqtt5_msg.h): `lib/mqtt_msg/include/mqtt5_msg.h`

### Delivery State

- [QoS Outbox](https://github.com/espressif/esp-mqtt/blob/master/lib/mqtt_outbox.c): `lib/mqtt_outbox.c`
- [Outbox Interface](https://github.com/espressif/esp-mqtt/blob/master/lib/include/mqtt_outbox.h): `lib/include/mqtt_outbox.h`
- [Platform Helpers](https://github.com/espressif/esp-mqtt/blob/master/lib/platform.c): `lib/platform.c`

### Other components

- **Application**
- **MQTT Broker**

## Connections

- Application → Client API: configures client
- Client API → Client Runtime: starts runtime (evidence: `mqtt_client.c`)
- Application → MQTT 5 API: sets MQTT 5 options
- MQTT 5 API → MQTT 5 Runtime: configures protocol (evidence: `mqtt5_client.c`)
- Client Runtime → Transport Adapters: selects transport (evidence: `mqtt_client.c`)
- Client Runtime → MQTT Broker: exchanges packets
- MQTT Broker → Client Runtime: returns packets
- Client Runtime → MQTT Codec: decodes packets
- MQTT Codec → MQTT Message Model: uses model (evidence: `lib/mqtt_msg/mqtt_msg.c`)
- MQTT 5 Runtime → MQTT 5 Codec: encodes properties
- MQTT 5 Codec → MQTT 5 Message Model: uses model (evidence: `lib/mqtt_msg/mqtt5_msg.c`)
- MQTT 5 Runtime → Client Runtime: extends runtime
- Client Runtime → Client State: uses state (evidence: `mqtt_client.c`)
- MQTT 5 Runtime → MQTT 5 State: uses state
- Client Runtime → QoS Outbox: queues delivery
- QoS Outbox → Outbox Interface: implements interface (evidence: `lib/mqtt_outbox.c`)
- Client Runtime → URI Utilities: parses URI
- Client Runtime → Platform Helpers: uses helpers