# eclipse-mosquitto/mosquitto architecture

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

- Interactive diagram: https://gitdiagram.com/eclipse-mosquitto/mosquitto
- Repository: https://github.com/eclipse-mosquitto/mosquitto

## Overview

Eclipse Mosquitto is an MQTT 5.0/3.1.1/3.1 broker, client libraries, and command-line tools. In the principal workflow, clients publish and subscribe through the broker; the broker routes MQTT traffic and can retain state through persistence. The C client library provides the common runtime beneath client applications. Other documented capabilities include request/response messaging, broker administration, dynamic security, and password management. Evidence is strongest for the product boundaries and documented workflow; several implementation links are therefore omitted or marked unverified rather than inferred from directory names.

Main entry points: [`src/mosquitto.c`](https://github.com/eclipse-mosquitto/mosquitto/blob/master/src/mosquitto.c) (MQTT Broker), [`lib/libmosquitto.c`](https://github.com/eclipse-mosquitto/mosquitto/blob/master/lib/libmosquitto.c) (C Client Library), [`client/pub_client.c`](https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/pub_client.c) (Publisher), [`src/handle_publish.c`](https://github.com/eclipse-mosquitto/mosquitto/blob/master/src/handle_publish.c) (Broker Protocol Handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_broker["MQTT Broker"]
  node_broker["MQTT Broker<br/>[mosquitto.c]"]
  node_broker_config["Broker Configuration<br/>[conf.c]"]
  node_broker_database[("Broker Message State<br/>[database.c]")]
  node_broker_handlers["Broker Protocol Handling<br/>[handle_publish.c]"]
end

subgraph group_clients["Client Runtime"]
  node_publisher["Publisher<br/>[pub_client.c]"]
  node_subscriber["Subscriber<br/>[sub_client.c]"]
  node_request_client["Request Client<br/>[rr_client.c]"]
  node_shared_client["Shared Client Options<br/>[client_shared.c]"]
  node_client_library["C Client Library<br/>[libmosquitto.c]"]
  node_client_protocol["Client Protocol<br/>[send_mosq.h]"]
  node_client_internals["Client Internals"]
  node_publisher_tool["Publish Tool<br/>[pub_client.c]"]
  node_subscriber_tool["Subscribe Tool<br/>[sub_client.c]"]
  node_request_tool["Request Tool<br/>[rr_client.c]"]
end

subgraph group_admin["Administration"]
  node_ctrl["Broker Control<br/>[mosquitto_ctrl.c]"]
  node_dynsec_control["Security Commands<br/>[dynsec_client.c]"]
  node_password_tool["Password Utility<br/>[mosquitto_passwd.c]"]
  node_db_dump["Database Dump<br/>[db_dump.c]"]
  node_signal_tool["Signal Utility<br/>[mosquitto_signal.c]"]
end

subgraph group_extensions["Broker Extensions"]
  node_broker_persistence[("SQLite Persistence<br/>[plugin.c]")]
  node_dynamic_security["Dynamic Security<br/>[plugin.c]"]
  node_acl_plugin["ACL File Plugin<br/>[plugin.c]"]
end

node_mqtt_clients(("MQTT Clients"))

node_mqtt_clients -->|"connect to"| node_broker
node_publisher_tool -->|"publishes to"| node_broker
node_subscriber_tool -->|"subscribes to"| node_broker
node_request_tool -->|"uses"| node_broker
node_publisher -->|"uses options"| node_shared_client
node_publisher -->|"uses"| node_client_library
node_subscriber -.->|"uses"| node_client_library
node_request_client -.->|"uses"| node_client_library
node_broker -.->|"loads configuration"| node_broker_config
node_broker -.->|"handles MQTT"| node_broker_handlers
node_broker_handlers -.->|"updates state"| node_broker_database
node_broker -.->|"supports persistence"| node_broker_persistence
node_broker -.->|"supports security"| node_dynamic_security
node_broker -.->|"loads plugin"| node_acl_plugin
node_ctrl -.->|"administers"| node_broker
node_dynsec_control -.->|"configures"| node_dynamic_security
node_password_tool -.->|"manages credentials"| node_broker
node_db_dump -.->|"reads state"| node_broker_database
node_signal_tool -.->|"signals"| node_broker

click node_publisher "https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/pub_client.c"
click node_subscriber "https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/sub_client.c"
click node_request_client "https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/rr_client.c"
click node_shared_client "https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/client_shared.c"
click node_client_library "https://github.com/eclipse-mosquitto/mosquitto/blob/master/lib/libmosquitto.c"
click node_client_protocol "https://github.com/eclipse-mosquitto/mosquitto/blob/master/lib/send_mosq.h"
click node_client_internals "https://github.com/eclipse-mosquitto/mosquitto/blob/master/lib/mosquitto_internal.h"
click node_broker "https://github.com/eclipse-mosquitto/mosquitto/blob/master/src/mosquitto.c"
click node_broker_config "https://github.com/eclipse-mosquitto/mosquitto/blob/master/src/conf.c"
click node_broker_database "https://github.com/eclipse-mosquitto/mosquitto/blob/master/src/database.c"
click node_broker_handlers "https://github.com/eclipse-mosquitto/mosquitto/blob/master/src/handle_publish.c"
click node_broker_persistence "https://github.com/eclipse-mosquitto/mosquitto/blob/master/plugins/persist-sqlite/plugin.c"
click node_dynamic_security "https://github.com/eclipse-mosquitto/mosquitto/blob/master/plugins/dynamic-security/plugin.c"
click node_acl_plugin "https://github.com/eclipse-mosquitto/mosquitto/blob/master/plugins/acl-file/plugin.c"
click node_publisher_tool "https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/pub_client.c"
click node_subscriber_tool "https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/sub_client.c"
click node_request_tool "https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/rr_client.c"
click node_ctrl "https://github.com/eclipse-mosquitto/mosquitto/blob/master/apps/mosquitto_ctrl/mosquitto_ctrl.c"
click node_dynsec_control "https://github.com/eclipse-mosquitto/mosquitto/blob/master/apps/mosquitto_ctrl/dynsec_client.c"
click node_password_tool "https://github.com/eclipse-mosquitto/mosquitto/blob/master/apps/mosquitto_passwd/mosquitto_passwd.c"
click node_db_dump "https://github.com/eclipse-mosquitto/mosquitto/blob/master/apps/db_dump/db_dump.c"
click node_signal_tool "https://github.com/eclipse-mosquitto/mosquitto/blob/master/apps/mosquitto_signal/mosquitto_signal.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_broker,node_broker_config,node_broker_database,node_broker_handlers,node_mqtt_clients toneBlue
class node_publisher,node_subscriber,node_request_client,node_shared_client,node_client_library,node_client_protocol,node_client_internals,node_publisher_tool,node_subscriber_tool,node_request_tool toneAmber
class node_ctrl,node_dynsec_control,node_password_tool,node_db_dump,node_signal_tool toneMint
class node_broker_persistence,node_dynamic_security,node_acl_plugin toneRose
```

## Components

### MQTT Broker

- [MQTT Broker](https://github.com/eclipse-mosquitto/mosquitto/blob/master/src/mosquitto.c): `src/mosquitto.c`
- [Broker Configuration](https://github.com/eclipse-mosquitto/mosquitto/blob/master/src/conf.c): `src/conf.c`
- [Broker Message State](https://github.com/eclipse-mosquitto/mosquitto/blob/master/src/database.c): `src/database.c`
- [Broker Protocol Handling](https://github.com/eclipse-mosquitto/mosquitto/blob/master/src/handle_publish.c): `src/handle_publish.c`

### Client Runtime

- [Publisher](https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/pub_client.c): `client/pub_client.c`
- [Subscriber](https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/sub_client.c): `client/sub_client.c`
- [Request Client](https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/rr_client.c): `client/rr_client.c`
- [Shared Client Options](https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/client_shared.c): `client/client_shared.c`
- [C Client Library](https://github.com/eclipse-mosquitto/mosquitto/blob/master/lib/libmosquitto.c): `lib/libmosquitto.c`
- [Client Protocol](https://github.com/eclipse-mosquitto/mosquitto/blob/master/lib/send_mosq.h): `lib/send_mosq.h`
- [Client Internals](https://github.com/eclipse-mosquitto/mosquitto/blob/master/lib/mosquitto_internal.h): `lib/mosquitto_internal.h`
- [Publish Tool](https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/pub_client.c): `client/pub_client.c`
- [Subscribe Tool](https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/sub_client.c): `client/sub_client.c`
- [Request Tool](https://github.com/eclipse-mosquitto/mosquitto/blob/master/client/rr_client.c): `client/rr_client.c`

### Administration

- [Broker Control](https://github.com/eclipse-mosquitto/mosquitto/blob/master/apps/mosquitto_ctrl/mosquitto_ctrl.c): `apps/mosquitto_ctrl/mosquitto_ctrl.c`
- [Security Commands](https://github.com/eclipse-mosquitto/mosquitto/blob/master/apps/mosquitto_ctrl/dynsec_client.c): `apps/mosquitto_ctrl/dynsec_client.c`
- [Password Utility](https://github.com/eclipse-mosquitto/mosquitto/blob/master/apps/mosquitto_passwd/mosquitto_passwd.c): `apps/mosquitto_passwd/mosquitto_passwd.c`
- [Database Dump](https://github.com/eclipse-mosquitto/mosquitto/blob/master/apps/db_dump/db_dump.c): `apps/db_dump/db_dump.c`
- [Signal Utility](https://github.com/eclipse-mosquitto/mosquitto/blob/master/apps/mosquitto_signal/mosquitto_signal.c): `apps/mosquitto_signal/mosquitto_signal.c`

### Broker Extensions

- [SQLite Persistence](https://github.com/eclipse-mosquitto/mosquitto/blob/master/plugins/persist-sqlite/plugin.c): `plugins/persist-sqlite/plugin.c`
- [Dynamic Security](https://github.com/eclipse-mosquitto/mosquitto/blob/master/plugins/dynamic-security/plugin.c): `plugins/dynamic-security/plugin.c`
- [ACL File Plugin](https://github.com/eclipse-mosquitto/mosquitto/blob/master/plugins/acl-file/plugin.c): `plugins/acl-file/plugin.c`

### Other components

- **MQTT Clients**

## Connections

- MQTT Clients → MQTT Broker: connect to
- Publish Tool → MQTT Broker: publishes to
- Subscribe Tool → MQTT Broker: subscribes to
- Request Tool → MQTT Broker: uses
- Publisher → Shared Client Options: uses options (evidence: `client/pub_client.c`)
- Publisher → C Client Library: uses (evidence: `client/pub_client.c`)
- Subscriber → C Client Library: uses
- Request Client → C Client Library: uses
- MQTT Broker → Broker Configuration: loads configuration
- MQTT Broker → Broker Protocol Handling: handles MQTT
- Broker Protocol Handling → Broker Message State: updates state
- MQTT Broker → SQLite Persistence: supports persistence
- MQTT Broker → Dynamic Security: supports security
- MQTT Broker → ACL File Plugin: loads plugin
- Broker Control → MQTT Broker: administers
- Security Commands → Dynamic Security: configures
- Password Utility → MQTT Broker: manages credentials
- Database Dump → Broker Message State: reads state
- Signal Utility → MQTT Broker: signals
