# dotnet/mqttnet architecture

> Architecture diagram of the GitHub repository dotnet/mqttnet, 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/dotnet/mqttnet
- Repository: https://github.com/dotnet/mqttnet

## Overview

MQTTnet is a .NET MQTT client and broker library supporting MQTT through version 5. Its main workflow configures a client, connects over a supported channel, and exchanges publish/subscribe messages through the broker, which manages client sessions, subscriptions, delivery, and retained messages. The graph also shows protocol handling, packet inspection, RPC, SOCKS5, and ASP.NET Core hosting. Relationships are limited to README statements and the supplied source index or excerpts; unsampled implementation details are not assumed.

Main entry points: [`Source/MQTTnet/MqttClient.cs`](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/MqttClient.cs) (Client API), [`Source/MQTTnet.Server/Internal/MqttClientSessionsManager.cs`](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/Internal/MqttClientSessionsManager.cs) (Session manager), [`Source/MQTTnet/Adapter/MqttChannelAdapter.cs`](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Adapter/MqttChannelAdapter.cs) (Channels and adapters), [`Source/MQTTnet/Options/MqttClientOptionsBuilder.cs`](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Options/MqttClientOptionsBuilder.cs) (Client options)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["MQTT client"]
  node_client_api["Client API<br/>[MqttClient.cs]"]
  node_client_options["Client options"]
  node_message_api["Message model"]
end

subgraph group_protocol["Protocol runtime"]
  node_transport["Channels and adapters"]
  node_tcp_channel["TCP channel<br/>[MqttTcpChannel.cs]"]
  node_websocket_channel["WebSocket channel"]
  node_packet_dispatch["Packet dispatcher"]
  node_packet_codec["Packet formatting"]
  node_packet_inspection["Packet inspection"]
end

subgraph group_broker["Broker"]
  node_broker_api["Server API<br/>[MqttServer.cs]"]
  node_session_manager["Session manager"]
  node_session["Client session<br/>[MqttSession.cs]"]
  node_session_storage["Session storage"]
  node_retained[("Retained messages")]
  node_server_events["Broker events"]
end

subgraph group_hosting["Hosting and extensions"]
  node_aspnet_host["ASP.NET hosting"]
  node_rpc["RPC client<br/>[MqttRpcClient.cs]"]
  node_socks5["SOCKS5 transport"]
end

node_user(("Application"))
node_broker(("MQTT broker"))

node_user -->|"configures"| node_client_options
node_client_options -->|"configures"| node_client_api
node_user -->|"uses"| node_client_api
node_client_api -->|"creates adapters"| node_transport
node_transport -.->|"uses"| node_tcp_channel
node_transport -.->|"uses"| node_websocket_channel
node_client_api -->|"dispatches packets"| node_packet_dispatch
node_transport -->|"inspects packets"| node_packet_inspection
node_client_api -->|"exchanges messages"| node_message_api
node_client_api -->|"communicates with"| node_broker
node_user -->|"hosts broker"| node_broker_api
node_broker_api -.->|"manages clients"| node_session_manager
node_session_manager -->|"manages sessions"| node_session
node_session_manager -->|"updates storage"| node_session_storage
node_session_manager -->|"uses retained state"| node_retained
node_session_manager -->|"raises events"| node_server_events
node_retained -->|"loads and signals"| node_server_events
node_user -->|"hosts via"| node_aspnet_host
node_user -.->|"uses RPC"| node_rpc
node_rpc -->|"uses client"| node_client_api
node_user -.->|"configures proxy"| node_socks5
node_socks5 -->|"extends options"| node_client_options

click node_client_api "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/MqttClient.cs"
click node_client_options "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Options/MqttClientOptionsBuilder.cs"
click node_message_api "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/MqttApplicationMessage.cs"
click node_transport "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Adapter/MqttChannelAdapter.cs"
click node_tcp_channel "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Implementations/MqttTcpChannel.cs"
click node_websocket_channel "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Implementations/MqttWebSocketChannel.cs"
click node_packet_dispatch "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/PacketDispatcher/MqttPacketDispatcher.cs"
click node_packet_codec "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Formatter/MqttPacketFormatterAdapter.cs"
click node_packet_inspection "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Adapter/MqttPacketInspector.cs"
click node_broker_api "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/MqttServer.cs"
click node_session_manager "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/Internal/MqttClientSessionsManager.cs"
click node_session "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/Internal/MqttSession.cs"
click node_session_storage "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/Internal/MqttSessionsStorage.cs"
click node_retained "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/Internal/MqttRetainedMessagesManager.cs"
click node_server_events "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/Internal/MqttServerEventContainer.cs"
click node_aspnet_host "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.AspnetCore/MqttHostedServer.cs"
click node_rpc "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Extensions.Rpc/MqttRpcClient.cs"
click node_socks5 "https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Extensions.Socks5/Socks5StreamProvider.cs"

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_client_options,node_message_api toneBlue
class node_transport,node_tcp_channel,node_websocket_channel,node_packet_dispatch,node_packet_codec,node_packet_inspection toneAmber
class node_broker_api,node_session_manager,node_session,node_session_storage,node_retained,node_server_events toneMint
class node_aspnet_host,node_rpc,node_socks5 toneRose
class node_user,node_broker toneIndigo
```

## Components

### MQTT client

- [Client API](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/MqttClient.cs): `Source/MQTTnet/MqttClient.cs`
- [Client options](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Options/MqttClientOptionsBuilder.cs): `Source/MQTTnet/Options/MqttClientOptionsBuilder.cs`
- [Message model](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/MqttApplicationMessage.cs): `Source/MQTTnet/MqttApplicationMessage.cs`

### Protocol runtime

- [Channels and adapters](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Adapter/MqttChannelAdapter.cs): `Source/MQTTnet/Adapter/MqttChannelAdapter.cs`
- [TCP channel](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Implementations/MqttTcpChannel.cs): `Source/MQTTnet/Implementations/MqttTcpChannel.cs`
- [WebSocket channel](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Implementations/MqttWebSocketChannel.cs): `Source/MQTTnet/Implementations/MqttWebSocketChannel.cs`
- [Packet dispatcher](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/PacketDispatcher/MqttPacketDispatcher.cs): `Source/MQTTnet/PacketDispatcher/MqttPacketDispatcher.cs`
- [Packet formatting](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Formatter/MqttPacketFormatterAdapter.cs): `Source/MQTTnet/Formatter/MqttPacketFormatterAdapter.cs`
- [Packet inspection](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet/Adapter/MqttPacketInspector.cs): `Source/MQTTnet/Adapter/MqttPacketInspector.cs`

### Broker

- [Server API](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/MqttServer.cs): `Source/MQTTnet.Server/MqttServer.cs`
- [Session manager](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/Internal/MqttClientSessionsManager.cs): `Source/MQTTnet.Server/Internal/MqttClientSessionsManager.cs`
- [Client session](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/Internal/MqttSession.cs): `Source/MQTTnet.Server/Internal/MqttSession.cs`
- [Session storage](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/Internal/MqttSessionsStorage.cs): `Source/MQTTnet.Server/Internal/MqttSessionsStorage.cs`
- [Retained messages](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/Internal/MqttRetainedMessagesManager.cs): `Source/MQTTnet.Server/Internal/MqttRetainedMessagesManager.cs`
- [Broker events](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Server/Internal/MqttServerEventContainer.cs): `Source/MQTTnet.Server/Internal/MqttServerEventContainer.cs`

### Hosting and extensions

- [ASP.NET hosting](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.AspnetCore/MqttHostedServer.cs): `Source/MQTTnet.AspnetCore/MqttHostedServer.cs`
- [RPC client](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Extensions.Rpc/MqttRpcClient.cs): `Source/MQTTnet.Extensions.Rpc/MqttRpcClient.cs`
- [SOCKS5 transport](https://github.com/dotnet/mqttnet/blob/master/Source/MQTTnet.Extensions.Socks5/Socks5StreamProvider.cs): `Source/MQTTnet.Extensions.Socks5/Socks5StreamProvider.cs`

### Other components

- **Application**
- **MQTT broker**

## Connections

- Application → Client options: configures (evidence: `Source/MQTTnet/Options/MqttClientOptionsBuilder.cs`)
- Client options → Client API: configures (evidence: `Source/MQTTnet/Options/MqttClientOptionsBuilder.cs`)
- Application → Client API: uses
- Client API → Channels and adapters: creates adapters (evidence: `Source/MQTTnet/MqttClient.cs`)
- Channels and adapters → TCP channel: uses
- Channels and adapters → WebSocket channel: uses
- Client API → Packet dispatcher: dispatches packets (evidence: `Source/MQTTnet/MqttClient.cs`)
- Channels and adapters → Packet inspection: inspects packets
- Client API → Message model: exchanges messages (evidence: `Source/MQTTnet/MqttClient.cs`)
- Client API → MQTT broker: communicates with
- Application → Server API: hosts broker
- Server API → Session manager: manages clients
- Session manager → Client session: manages sessions (evidence: `Source/MQTTnet.Server/Internal/MqttClientSessionsManager.cs`)
- Session manager → Session storage: updates storage (evidence: `Source/MQTTnet.Server/Internal/MqttClientSessionsManager.cs`)
- Session manager → Retained messages: uses retained state (evidence: `Source/MQTTnet.Server/Internal/MqttClientSessionsManager.cs`)
- Session manager → Broker events: raises events (evidence: `Source/MQTTnet.Server/Internal/MqttClientSessionsManager.cs`)
- Retained messages → Broker events: loads and signals (evidence: `Source/MQTTnet.Server/Internal/MqttRetainedMessagesManager.cs`)
- Application → ASP.NET hosting: hosts via
- Application → RPC client: uses RPC
- RPC client → Client API: uses client (evidence: `Source/MQTTnet.Extensions.Rpc/MqttRpcClient.cs`)
- Application → SOCKS5 transport: configures proxy
- SOCKS5 transport → Client options: extends options (evidence: `Source/MQTTnet.Extensions.Socks5/MqttClientOptionsBuilderExtensions.cs`)
