# liambindle/mqtt-c architecture

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

- Interactive diagram: https://gitdiagram.com/liambindle/mqtt-c
- Repository: https://github.com/liambindle/mqtt-c

## Overview

#### Purpose and Public Entry Points
MQTT-C is a portable ANSI C (C89-compatible) MQTT v3.1.1 client library for embedded and desktop systems. Consumers include `include/mqtt.h`, instantiate `struct mqtt_client`, then drive it through `mqtt_init`, `mqtt_connect`, publish/subscribe calls, and broker I/O processing. The public portability contract is `include/mqtt_pal.h`.

Paths: `include/mqtt.h`, `include/mqtt_pal.h`

#### Core Client Engine
The library’s primary state machine, MQTT packet construction/parsing, response handling, QoS flows, and outbound message queue management are centralized in the client implementation. A client translates API operations into MQTT wire packets and consumes incoming broker packets into response/callback state.

Paths: `src/mqtt.c`, `include/mqtt.h`

#### Platform Abstraction Boundary
The protocol engine is separated from host-specific facilities through the PAL. This boundary supplies required types and operations such as synchronization, time, and I/O-facing portability mechanisms, allowing the same MQTT engine to target single-threaded embedded platforms or threaded PC environments.

Paths: `src/mqtt_pal.c`, `include/mqtt_pal.h`, `src/mqtt.c`

#### Primary Runtime Flow
Application-owned transport setup precedes client initialization. The application initializes a `mqtt_client` with buffers and PAL/transport integration, sends CONNECT, then repeatedly services network input/output through the library while issuing publish, subscribe, unsubscribe, ping, and disconnect operations. Broker responses—CONNACK, PUBLISH, acknowledgements, and keepalive responses—are parsed by the engine and update queued-message/QoS state.

Paths: `include/mqtt.h`, `src/mqtt.c`, `include/mqtt_pal.h`

#### Transport and TLS Integration
MQTT-C does not impose a single socket or TLS runtime; examples provide integration templates for POSIX sockets and TLS stacks. This keeps TCP/TLS ownership at the application boundary while supporting OpenSSL, Mbed TLS, and BearSSL-backed clients. Example executables connect to external MQTT brokers, including Mosquitto’s public test service.

Paths: `examples/templates/posix_sockets.h`, `examples/templates/openssl_sockets.h`, `examples/templates/mbedtls_sockets.h`

#### Executable Usage Patterns
Examples are the practical entry points for basic publishing/subscribing, reconnect behavior, and secure transports. They demonstrate how application code binds a socket implementation to the library rather than introducing a separate server or web runtime.

Paths: `examples/simple_publisher.c`, `examples/simple_subscriber.c`, `examples/reconnect_subscriber.c`

#### Build and Verification
The library can be consumed directly by compiling its two implementation files, or built through CMake, Make, or Zig build definitions. Tests use cmocka and can contact a configurable MQTT broker; CI runs repository validation.

Paths: `CMakeLists.txt`, `makefile`, `build.zig`

Main entry points: [`src/mqtt.c`](https://github.com/liambindle/mqtt-c/blob/master/src/mqtt.c) (Client engine), [`include/mqtt.h`](https://github.com/liambindle/mqtt-c/blob/master/include/mqtt.h) (MQTT client API), [`examples/simple_publisher.c`](https://github.com/liambindle/mqtt-c/blob/master/examples/simple_publisher.c) (Publisher and subscriber), [`CMakeLists.txt`](https://github.com/liambindle/mqtt-c/blob/master/CMakeLists.txt) (Build definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_mqtt_api["MQTT client API<br/>public header<br/>[mqtt.h]"]
  node_pal_api["Portability API<br/>public header<br/>[mqtt_pal.h]"]
end

subgraph group_library["MQTT-C Library"]
  node_client_engine["Client engine<br/>C implementation<br/>[mqtt.c]"]
  node_qos_queue["QoS and outbound queue<br/>engine layer<br/>[mqtt.c]"]
  node_pal_impl["PAL implementation<br/>C implementation<br/>[mqtt_pal.c]"]
end

subgraph group_integration["Application Integration"]
  node_application["Consumer application<br/>application code"]
  node_posix_transport["POSIX socket template<br/>transport template<br/>[posix_sockets.h]"]
  node_tls_transports["TLS socket templates<br/>transport templates<br/>[openssl_sockets.h]"]
  node_simple_examples["Publisher and subscriber<br/>example applications<br/>[simple_publisher.c]"]
  node_reconnect_example["Reconnect subscriber<br/>example application"]
end

subgraph group_tooling["Build &amp; Verification"]
  node_build_systems["Build definitions<br/>build entry points<br/>[CMakeLists.txt]"]
end

node_mqtt_broker(("External MQTT broker<br/>external service"))

node_application -->|"uses"| node_mqtt_api
node_mqtt_api -->|"declares"| node_client_engine
node_client_engine -->|"manages"| node_qos_queue
node_client_engine -->|"depends on"| node_pal_api
node_pal_api -->|"implemented by"| node_pal_impl
node_application -->|"binds transport"| node_posix_transport
node_application -.->|"may bind TLS"| node_tls_transports
node_application -->|"services I/O"| node_client_engine
node_client_engine -->|"MQTT packets"| node_mqtt_broker
node_mqtt_broker -->|"responses and publishes"| node_client_engine
node_simple_examples -->|"demonstrate"| node_mqtt_api
node_simple_examples -->|"use"| node_posix_transport
node_reconnect_example -->|"demonstrates"| node_mqtt_api
node_build_systems -->|"builds"| node_client_engine
node_build_systems -->|"builds"| node_pal_impl

click node_mqtt_api "https://github.com/liambindle/mqtt-c/blob/master/include/mqtt.h"
click node_pal_api "https://github.com/liambindle/mqtt-c/blob/master/include/mqtt_pal.h"
click node_client_engine "https://github.com/liambindle/mqtt-c/blob/master/src/mqtt.c"
click node_qos_queue "https://github.com/liambindle/mqtt-c/blob/master/src/mqtt.c"
click node_pal_impl "https://github.com/liambindle/mqtt-c/blob/master/src/mqtt_pal.c"
click node_posix_transport "https://github.com/liambindle/mqtt-c/blob/master/examples/templates/posix_sockets.h"
click node_tls_transports "https://github.com/liambindle/mqtt-c/blob/master/examples/templates/openssl_sockets.h"
click node_simple_examples "https://github.com/liambindle/mqtt-c/blob/master/examples/simple_publisher.c"
click node_reconnect_example "https://github.com/liambindle/mqtt-c/blob/master/examples/reconnect_subscriber.c"
click node_build_systems "https://github.com/liambindle/mqtt-c/blob/master/CMakeLists.txt"

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_mqtt_api,node_pal_api toneBlue
class node_client_engine,node_qos_queue,node_pal_impl toneAmber
class node_application,node_posix_transport,node_tls_transports,node_simple_examples,node_reconnect_example toneMint
class node_build_systems toneRose
class node_mqtt_broker toneNeutral
```

## Components

### Public API

- [MQTT client API](https://github.com/liambindle/mqtt-c/blob/master/include/mqtt.h): public header · Client lifecycle, publish, subscribe, and broker I/O API. · `include/mqtt.h`
- [Portability API](https://github.com/liambindle/mqtt-c/blob/master/include/mqtt_pal.h): public header · Host abstraction contract for the protocol engine. · `include/mqtt_pal.h`

### MQTT-C Library

- [Client engine](https://github.com/liambindle/mqtt-c/blob/master/src/mqtt.c): C implementation · Drives MQTT state, packet encoding/parsing, and broker responses. · `src/mqtt.c`
- [QoS and outbound queue](https://github.com/liambindle/mqtt-c/blob/master/src/mqtt.c): engine layer · Tracks outbound messages and acknowledgement-driven QoS state. · `src/mqtt.c`
- [PAL implementation](https://github.com/liambindle/mqtt-c/blob/master/src/mqtt_pal.c): C implementation · Supplies portable synchronization, time, and platform facilities. · `src/mqtt_pal.c`

### Application Integration

- **Consumer application**: application code · Owns transport setup, buffers, and the mqtt_client instance.
- [POSIX socket template](https://github.com/liambindle/mqtt-c/blob/master/examples/templates/posix_sockets.h): transport template · `examples/templates/posix_sockets.h`
- [TLS socket templates](https://github.com/liambindle/mqtt-c/blob/master/examples/templates/openssl_sockets.h): transport templates · OpenSSL and Mbed TLS integration patterns. · `examples/templates/openssl_sockets.h`
- [Publisher and subscriber](https://github.com/liambindle/mqtt-c/blob/master/examples/simple_publisher.c): example applications · Basic application usage patterns. · `examples/simple_publisher.c`
- [Reconnect subscriber](https://github.com/liambindle/mqtt-c/blob/master/examples/reconnect_subscriber.c): example application · Reconnect-oriented client usage. · `examples/reconnect_subscriber.c`

### Build & Verification

- [Build definitions](https://github.com/liambindle/mqtt-c/blob/master/CMakeLists.txt): build entry points · Supports CMake, Make, and Zig builds. · `CMakeLists.txt`

### Other components

- **External MQTT broker**: external service · Receives MQTT traffic and returns protocol responses.

## Connections

- Consumer application → MQTT client API: uses
- MQTT client API → Client engine: declares
- Client engine → QoS and outbound queue: manages
- Client engine → Portability API: depends on
- Portability API → PAL implementation: implemented by
- Consumer application → POSIX socket template: binds transport
- Consumer application → TLS socket templates: may bind TLS
- Consumer application → Client engine: services I/O
- Client engine → External MQTT broker: MQTT packets
- External MQTT broker → Client engine: responses and publishes
- Publisher and subscriber → MQTT client API: demonstrate
- Publisher and subscriber → POSIX socket template: use
- Reconnect subscriber → MQTT client API: demonstrates
- Build definitions → Client engine: builds
- Build definitions → PAL implementation: builds