# faststream-community/zmqtt architecture

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

- Interactive diagram: https://gitdiagram.com/faststream-community/zmqtt
- Repository: https://github.com/faststream-community/zmqtt

## Overview

zmqtt is a pure-asyncio MQTT 3.1.1/5.0 client. Applications create a client, connect to a broker, publish or subscribe, then consume messages through subscription-local queues; incoming messages are routed to a subscription or a correlated request. The graph preserves the packet codec, protocol/state machinery, routing and request/response branches, and transport layer. Source-index references and README statements support the links shown; unsampled implementation details are represented only at their documented subsystem level.

Main entry points: [`src/zmqtt/_internal/protocol.py`](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/protocol.py) (Protocol Engine), [`src/zmqtt/client.py`](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/client.py) (Async Client), [`src/zmqtt/_internal/inbound.py`](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/inbound.py) (Inbound Processing), [`src/zmqtt/_internal/packets/codec.py`](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/packets/codec.py) (Packet Codec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client API"]
  node_client["Async Client<br/>[client.py]"]
  node_public_api["Public API<br/>[__init__.py]"]
end

subgraph group_engine["Protocol Engine"]
  node_protocol["Protocol Engine<br/>[protocol.py]"]
  node_state["Session State<br/>[state.py]"]
  node_compat["Async Compatibility<br/>[_compat.py]"]
end

subgraph group_routing["Delivery and Routing"]
  node_inbound["Inbound Processing<br/>[inbound.py]"]
  node_router["Recipient Router<br/>[routing.py]"]
  node_subscription_index["Subscription Index"]
  node_topic_matching["Topic Matching<br/>[topic_matching.py]"]
  node_request_response["Request Response"]
  node_message["Message<br/>[message.py]"]
  node_types["QoS and Types"]
end

subgraph group_wire["MQTT Wire and Transport"]
  node_codec["Packet Codec<br/>[codec.py]"]
  node_packet_models["Packet Models"]
  node_properties["MQTT Properties<br/>[properties.py]"]
  node_reader["Packet Reader<br/>[reader.py]"]
  node_transport["Stream Transport<br/>[base.py]"]
  node_tcp_tls["TCP and TLS"]
end

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

node_application -->|"uses API"| node_public_api
node_public_api -->|"creates client"| node_client
node_client -->|"drives protocol"| node_protocol
node_client -->|"starts requests"| node_request_response
node_client -->|"manages session"| node_state
node_client -->|"uses transport"| node_transport
node_client -->|"manages subscriptions"| node_subscription_index
node_protocol -->|"dispatches packets"| node_inbound
node_protocol -->|"encodes and decodes"| node_codec
node_protocol -->|"reads packets"| node_reader
node_protocol -->|"updates session"| node_state
node_protocol -->|"reads and writes"| node_transport
node_protocol -->|"uses subscriptions"| node_subscription_index
node_protocol -->|"validates filters"| node_topic_matching
node_inbound -->|"decodes packets"| node_codec
node_inbound -->|"selects recipient"| node_router
node_inbound -->|"updates QoS state"| node_state
node_inbound -->|"selects subscription"| node_subscription_index
node_inbound -->|"builds message"| node_message
node_router -->|"selects subscription"| node_subscription_index
node_subscription_index -->|"matches filters"| node_topic_matching
node_subscription_index -->|"queues message"| node_message
node_request_response -->|"matches response"| node_message
node_codec -->|"encodes packets"| node_packet_models
node_codec -->|"encodes properties"| node_properties
node_codec -->|"uses QoS"| node_types
node_reader -->|"decodes frames"| node_codec
node_transport -->|"uses wait helper"| node_compat
node_tcp_tls -->|"implements transport"| node_transport
node_client -->|"selects connection"| node_tcp_tls
node_transport -->|"transfers bytes"| node_broker

click node_client "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/client.py"
click node_public_api "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/__init__.py"
click node_protocol "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/protocol.py"
click node_state "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/state.py"
click node_compat "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/_compat.py"
click node_inbound "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/inbound.py"
click node_router "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/routing.py"
click node_subscription_index "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/subscription_index.py"
click node_topic_matching "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/topic_matching.py"
click node_request_response "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/request_response.py"
click node_message "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/types/message.py"
click node_types "https://github.com/faststream-community/zmqtt/tree/master/src/zmqtt/_internal/types"
click node_codec "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/packets/codec.py"
click node_packet_models "https://github.com/faststream-community/zmqtt/tree/master/src/zmqtt/_internal/packets"
click node_properties "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/packets/properties.py"
click node_reader "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/packets/reader.py"
click node_transport "https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/transport/base.py"
click node_tcp_tls "https://github.com/faststream-community/zmqtt/tree/master/src/zmqtt/_internal/transport"

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_public_api toneBlue
class node_protocol,node_state,node_compat toneAmber
class node_inbound,node_router,node_subscription_index,node_topic_matching,node_request_response,node_message,node_types toneMint
class node_codec,node_packet_models,node_properties,node_reader,node_transport,node_tcp_tls toneRose
class node_application,node_broker toneIndigo
```

## Components

### Client API

- [Async Client](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/client.py): `src/zmqtt/client.py`
- [Public API](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/__init__.py): `src/zmqtt/__init__.py`

### Protocol Engine

- [Protocol Engine](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/protocol.py): `src/zmqtt/_internal/protocol.py`
- [Session State](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/state.py): `src/zmqtt/_internal/state.py`
- [Async Compatibility](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/_compat.py): `src/zmqtt/_internal/_compat.py`

### Delivery and Routing

- [Inbound Processing](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/inbound.py): `src/zmqtt/_internal/inbound.py`
- [Recipient Router](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/routing.py): `src/zmqtt/_internal/routing.py`
- [Subscription Index](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/subscription_index.py): `src/zmqtt/_internal/subscription_index.py`
- [Topic Matching](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/topic_matching.py): `src/zmqtt/_internal/topic_matching.py`
- [Request Response](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/request_response.py): `src/zmqtt/_internal/request_response.py`
- [Message](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/types/message.py): `src/zmqtt/_internal/types/message.py`
- [QoS and Types](https://github.com/faststream-community/zmqtt/tree/master/src/zmqtt/_internal/types): `src/zmqtt/_internal/types`

### MQTT Wire and Transport

- [Packet Codec](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/packets/codec.py): `src/zmqtt/_internal/packets/codec.py`
- [Packet Models](https://github.com/faststream-community/zmqtt/tree/master/src/zmqtt/_internal/packets): `src/zmqtt/_internal/packets`
- [MQTT Properties](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/packets/properties.py): `src/zmqtt/_internal/packets/properties.py`
- [Packet Reader](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/packets/reader.py): `src/zmqtt/_internal/packets/reader.py`
- [Stream Transport](https://github.com/faststream-community/zmqtt/blob/master/src/zmqtt/_internal/transport/base.py): `src/zmqtt/_internal/transport/base.py`
- [TCP and TLS](https://github.com/faststream-community/zmqtt/tree/master/src/zmqtt/_internal/transport): `src/zmqtt/_internal/transport`

### Other components

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

## Connections

- Application → Public API: uses API (evidence: `README.md`)
- Public API → Async Client: creates client (evidence: `src/zmqtt/__init__.py`)
- Async Client → Protocol Engine: drives protocol (evidence: `src/zmqtt/client.py`)
- Async Client → Request Response: starts requests (evidence: `src/zmqtt/client.py`)
- Async Client → Session State: manages session (evidence: `src/zmqtt/client.py`)
- Async Client → Stream Transport: uses transport (evidence: `src/zmqtt/client.py`)
- Async Client → Subscription Index: manages subscriptions (evidence: `src/zmqtt/client.py`)
- Protocol Engine → Inbound Processing: dispatches packets (evidence: `src/zmqtt/_internal/protocol.py`)
- Protocol Engine → Packet Codec: encodes and decodes (evidence: `src/zmqtt/_internal/protocol.py`)
- Protocol Engine → Packet Reader: reads packets (evidence: `src/zmqtt/_internal/protocol.py`)
- Protocol Engine → Session State: updates session (evidence: `src/zmqtt/_internal/protocol.py`)
- Protocol Engine → Stream Transport: reads and writes (evidence: `src/zmqtt/_internal/protocol.py`)
- Protocol Engine → Subscription Index: uses subscriptions (evidence: `src/zmqtt/_internal/protocol.py`)
- Protocol Engine → Topic Matching: validates filters (evidence: `src/zmqtt/_internal/protocol.py`)
- Inbound Processing → Packet Codec: decodes packets (evidence: `src/zmqtt/_internal/inbound.py`)
- Inbound Processing → Recipient Router: selects recipient (evidence: `src/zmqtt/_internal/inbound.py`)
- Inbound Processing → Session State: updates QoS state (evidence: `src/zmqtt/_internal/inbound.py`)
- Inbound Processing → Subscription Index: selects subscription (evidence: `src/zmqtt/_internal/inbound.py`)
- Inbound Processing → Message: builds message (evidence: `src/zmqtt/_internal/inbound.py`)
- Recipient Router → Subscription Index: selects subscription (evidence: `src/zmqtt/_internal/routing.py`)
- Subscription Index → Topic Matching: matches filters (evidence: `src/zmqtt/_internal/subscription_index.py`)
- Subscription Index → Message: queues message (evidence: `src/zmqtt/_internal/subscription_index.py`)
- Request Response → Message: matches response (evidence: `src/zmqtt/_internal/request_response.py`)
- Packet Codec → Packet Models: encodes packets (evidence: `src/zmqtt/_internal/packets/codec.py`)
- Packet Codec → MQTT Properties: encodes properties (evidence: `src/zmqtt/_internal/packets/codec.py`)
- Packet Codec → QoS and Types: uses QoS (evidence: `src/zmqtt/_internal/packets/codec.py`)
- Packet Reader → Packet Codec: decodes frames (evidence: `src/zmqtt/_internal/packets/reader.py`)
- Stream Transport → Async Compatibility: uses wait helper (evidence: `src/zmqtt/_internal/transport/base.py`)
- TCP and TLS → Stream Transport: implements transport (evidence: `src/zmqtt/_internal/transport/tcp.py`)
- Async Client → TCP and TLS: selects connection (evidence: `src/zmqtt/client.py`)
- Stream Transport → MQTT Broker: transfers bytes (evidence: `README.md`)
