# obabec/rust-mqtt architecture

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

- Interactive diagram: https://gitdiagram.com/obabec/rust-mqtt
- Repository: https://github.com/obabec/rust-mqtt

## Overview

rust-mqtt is a no_std-oriented asynchronous MQTT 5 client library. Its user-controlled workflow is to configure and connect a Client over an async transport, then publish or subscribe, poll for protocol events and acknowledgements, and explicitly disconnect or recover a session after failure. The map separates client orchestration, protocol/session behavior, and transport and data primitives. README and source-index references support the shown links; unsampled packet and session internals are represented at their existing paths without asserting undocumented call chains.

Main entry points: [`src/client/mod.rs`](https://github.com/obabec/rust-mqtt/blob/main/src/client/mod.rs) (MQTT Client), [`src/client/raw/mod.rs`](https://github.com/obabec/rust-mqtt/blob/main/src/client/raw/mod.rs) (Raw Connection), [`src/session/mod.rs`](https://github.com/obabec/rust-mqtt/blob/main/src/session/mod.rs) (Session Tracking), [`src/v5/packet`](https://github.com/obabec/rust-mqtt/tree/main/src/v5/packet) (MQTT v5 Packets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client API"]
  node_client["MQTT Client<br/>[mod.rs]"]
  node_options["Action Options<br/>[mod.rs]"]
  node_events["Client Events<br/>[event.rs]"]
  node_auth["Enhanced Auth<br/>[auth.rs]"]
  node_config["Client / Server Config<br/>[mod.rs]"]
end

subgraph group_protocol["Protocol and Session"]
  node_session["Session Tracking<br/>[mod.rs]"]
  node_session_handle["Session Handle<br/>[handle.rs]"]
  node_mqtt_packets["MQTT v5 Packets"]
  node_packet_framing["Packet Framing<br/>[rx.rs]"]
  node_header["Fixed Header<br/>[header.rs]"]
  node_types["MQTT Types<br/>[mod.rs]"]
  node_topics["Topic Types<br/>[topic.rs]"]
end

subgraph group_foundation["Runtime Foundations"]
  node_io["Async I/O<br/>[mod.rs]"]
  node_raw["Raw Connection<br/>[mod.rs]"]
  node_buffer["Buffer Provider<br/>[buffer.rs]"]
  node_bytes["Byte Storage<br/>[bytes.rs]"]
end

node_user(("Application"))
node_broker(("MQTT Broker"))

node_user -->|"uses"| node_client
node_user -->|"configures"| node_options
node_client -->|"accepts"| node_options
node_client -->|"enforces"| node_config
node_client -->|"delegates I/O"| node_raw
node_raw -->|"uses transport"| node_io
node_raw -->|"provisions"| node_buffer
node_buffer -->|"provides storage"| node_bytes
node_client -.->|"tracks protocol state"| node_session
node_session -->|"uses"| node_session_handle
node_client -->|"returns events"| node_events
node_client -->|"supports exchanges"| node_auth
node_client -.->|"encodes protocol"| node_mqtt_packets
node_raw -->|"receives packets"| node_packet_framing
node_packet_framing -->|"uses header"| node_header
node_mqtt_packets -.->|"uses values"| node_types
node_topics -->|"exports through"| node_types
node_client -->|"exchanges MQTT"| node_broker

click node_client "https://github.com/obabec/rust-mqtt/blob/main/src/client/mod.rs"
click node_options "https://github.com/obabec/rust-mqtt/blob/main/src/client/options/mod.rs"
click node_events "https://github.com/obabec/rust-mqtt/blob/main/src/client/event.rs"
click node_auth "https://github.com/obabec/rust-mqtt/blob/main/src/auth.rs"
click node_config "https://github.com/obabec/rust-mqtt/blob/main/src/config/mod.rs"
click node_session "https://github.com/obabec/rust-mqtt/blob/main/src/session/mod.rs"
click node_session_handle "https://github.com/obabec/rust-mqtt/blob/main/src/session/handle.rs"
click node_mqtt_packets "https://github.com/obabec/rust-mqtt/tree/main/src/v5/packet"
click node_packet_framing "https://github.com/obabec/rust-mqtt/blob/main/src/packet/rx.rs"
click node_header "https://github.com/obabec/rust-mqtt/blob/main/src/header.rs"
click node_types "https://github.com/obabec/rust-mqtt/blob/main/src/types/mod.rs"
click node_topics "https://github.com/obabec/rust-mqtt/blob/main/src/types/topic.rs"
click node_io "https://github.com/obabec/rust-mqtt/blob/main/src/io/mod.rs"
click node_raw "https://github.com/obabec/rust-mqtt/blob/main/src/client/raw/mod.rs"
click node_buffer "https://github.com/obabec/rust-mqtt/blob/main/src/buffer.rs"
click node_bytes "https://github.com/obabec/rust-mqtt/blob/main/src/bytes.rs"

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,node_options,node_events,node_auth,node_config toneBlue
class node_session,node_session_handle,node_mqtt_packets,node_packet_framing,node_header,node_types,node_topics toneAmber
class node_io,node_raw,node_buffer,node_bytes toneMint
class node_user,node_broker toneIndigo
```

## Components

### Client API

- [MQTT Client](https://github.com/obabec/rust-mqtt/blob/main/src/client/mod.rs): `src/client/mod.rs`
- [Action Options](https://github.com/obabec/rust-mqtt/blob/main/src/client/options/mod.rs): `src/client/options/mod.rs`
- [Client Events](https://github.com/obabec/rust-mqtt/blob/main/src/client/event.rs): `src/client/event.rs`
- [Enhanced Auth](https://github.com/obabec/rust-mqtt/blob/main/src/auth.rs): `src/auth.rs`
- [Client / Server Config](https://github.com/obabec/rust-mqtt/blob/main/src/config/mod.rs): `src/config/mod.rs`

### Protocol and Session

- [Session Tracking](https://github.com/obabec/rust-mqtt/blob/main/src/session/mod.rs): `src/session/mod.rs`
- [Session Handle](https://github.com/obabec/rust-mqtt/blob/main/src/session/handle.rs): `src/session/handle.rs`
- [MQTT v5 Packets](https://github.com/obabec/rust-mqtt/tree/main/src/v5/packet): `src/v5/packet`
- [Packet Framing](https://github.com/obabec/rust-mqtt/blob/main/src/packet/rx.rs): `src/packet/rx.rs`
- [Fixed Header](https://github.com/obabec/rust-mqtt/blob/main/src/header.rs): `src/header.rs`
- [MQTT Types](https://github.com/obabec/rust-mqtt/blob/main/src/types/mod.rs): `src/types/mod.rs`
- [Topic Types](https://github.com/obabec/rust-mqtt/blob/main/src/types/topic.rs): `src/types/topic.rs`

### Runtime Foundations

- [Async I/O](https://github.com/obabec/rust-mqtt/blob/main/src/io/mod.rs): `src/io/mod.rs`
- [Raw Connection](https://github.com/obabec/rust-mqtt/blob/main/src/client/raw/mod.rs): `src/client/raw/mod.rs`
- [Buffer Provider](https://github.com/obabec/rust-mqtt/blob/main/src/buffer.rs): `src/buffer.rs`
- [Byte Storage](https://github.com/obabec/rust-mqtt/blob/main/src/bytes.rs): `src/bytes.rs`

### Other components

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

## Connections

- Application → MQTT Client: uses (evidence: `README.md`)
- Application → Action Options: configures (evidence: `README.md`)
- MQTT Client → Action Options: accepts (evidence: `src/client/mod.rs`)
- MQTT Client → Client / Server Config: enforces (evidence: `src/client/mod.rs`)
- MQTT Client → Raw Connection: delegates I/O (evidence: `src/client/mod.rs`)
- Raw Connection → Async I/O: uses transport
- Raw Connection → Buffer Provider: provisions (evidence: `src/client/raw/mod.rs`)
- Buffer Provider → Byte Storage: provides storage (evidence: `src/buffer.rs`)
- MQTT Client → Session Tracking: tracks protocol state
- Session Tracking → Session Handle: uses (evidence: `src/session/mod.rs`)
- MQTT Client → Client Events: returns events (evidence: `src/client/mod.rs`)
- MQTT Client → Enhanced Auth: supports exchanges (evidence: `src/auth.rs`)
- MQTT Client → MQTT v5 Packets: encodes protocol
- Raw Connection → Packet Framing: receives packets (evidence: `src/client/raw/mod.rs`)
- Packet Framing → Fixed Header: uses header (evidence: `src/packet/rx.rs`)
- MQTT v5 Packets → MQTT Types: uses values
- Topic Types → MQTT Types: exports through (evidence: `src/types/mod.rs`)
- MQTT Client → MQTT Broker: exchanges MQTT (evidence: `README.md`)