# jesse6548/mosquitto architecture

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

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

## Overview

##### Project Type and Purpose
- This is an open‐source MQTT broker (server) implementation named Eclipse Mosquitto.
- It includes:
- A broker executable (“mosquitto”) that accepts MQTT v3.1, v3.1.1, and v5.0 connections.
- A C library (libmosquitto) and C++ wrapper (mosquittopp) for client applications.
- Command-line utilities (mosquitto_pub, mosquitto_sub, mosquitto_ctrl, mosquitto_passwd).
- A plugin API for authentication, ACLs, dynamic security, payload manipulation, and more.
- Extensive test suites, examples, Docker images, and documentation.

##### Main Components (to include
a. MQTT Broker Core
- Network transport (listeners: TCP, TLS/SSL via OpenSSL, WebSockets).
- Protocol handling (CONNECT, PUBLISH, SUBSCRIBE, etc.).
- Session & state management (in‐memory, optional persistence).
- Topic routing and matching.
- Bridge module (connects this broker to others).
- Plugin loader & API hooks (auth, ACL, message processing).
- Persistence layer (flat files / spool directories).
- Configuration manager (parses mosquitto.conf).
- Logging subsystem.
b. Client Libraries
- libmosquitto (C) with threading support via pthreads.
- mosquittopp (C++ wrapper).
- Optional JSON support (via cJSON).
c. CLI Utilities
- mosquitto_pub, mosquitto_sub (publish/subscribe).
- mosquitto_ctrl (dynamic security & management).
- mosquitto_passwd (user/password file management).
d. Plugins
- Authentication & authorization plugins (built-in & external).
- Dynamic security plugin.
- Message timestamp, payload-modification, protocol version denial, IP-based auth.
e. External Services & Tools
- TLS CA / Let’s Encrypt for certificate issuance.
- DNS SRV (via c-ares).
- Docker images for containerized deployment.
- Documentation generation (DocBook, Sphinx).
- Test harnesses (Python/Pytest, C unit tests).

##### Relationships and Interactions
- Broker Core invokes Plugin hooks at defined extension points (on_connect, on_publish, on_subscribe, on_message).
- Broker Core persists session state and retained messages to disk via Persistence Layer.
- Bridge module acts as both client and server: outbound connections to other brokers.
- CLI tools link against Client Libraries, interact with Broker over MQTT protocol.
- Configuration Manager feeds runtime parameters into Broker Core (ports, persistence paths, plugin configuration).
- Logging subsystem writes to stdout, files, or external monitoring.

##### Architectural Patterns & Design Principles
- Layered architecture:
- Transport Layer → Protocol Layer → Broker Logic → Persistence & Plugins.
- Plugin-based extensibility:
- Well‐defined C API for third‐party modules.
- Separation of concerns:
- Core broker engine decoupled from transport (via abstracted mux.c), storage, and authentication logic.
- Modular codebase:
- Shared code under lib/, broker logic under src/, CLI under client/, apps/, tests in test/.
- Build & deploy via CMake/Make, containerized via Docker, cross‐platform support.

##### Detail Level
- Plugin categories rather than every single plugin.
- Build/deploy pipelines (CMake → binaries → Docker images → CI tests) as side components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Libraries & CLI"
        libC["libmosquitto (C)"]:::client
        libCPP["mosquittopp (C++)"]:::client
        pub["mosquitto_pub & mosquitto_sub"]:::client
        ctrl["mosquitto_ctrl"]:::client
        passwd["mosquitto_passwd"]:::client
    end

    subgraph "MQTT Broker Core"
        direction TB
        Transport["Network Transport Layer"]:::core
        Protocol["Protocol Handler"]:::core
        Session["Session & State Management"]:::core
        Routing["Topic Routing & Matching"]:::core
        Bridge["Bridge Module"]:::core
        PluginLoader["Plugin Loader & API Hooks"]:::core
        Persistence["Persistence Layer"]:::core
        Config["Configuration Manager"]:::core
        Logging["Logging Subsystem"]:::core
    end

    subgraph "Plugins"
        AuthPlugins["Authentication & Authorization Plugins"]:::plugin
        DynSec["Dynamic Security Plugin"]:::plugin
        Timestamp["Message Timestamp Plugin"]:::plugin
        PayloadMod["Payload Modification Plugin"]:::plugin
    end

    subgraph "External & Infrastructure"
        TLS["TLS CA / Let's Encrypt"]:::external
        DNS["DNS SRV (c-ares)"]:::external
        Docker["Docker Images"]:::external
        Docs["Documentation (DocBook/Sphinx)"]:::external
        Tests["Test Harnesses & Suites"]:::external
    end

    libC -->|MQTT| Transport
    libCPP -->|MQTT| Transport
    pub -->|uses| libC
    ctrl -->|uses| libC
    passwd -->|uses| libC

    Transport -->|"dispatch packets"| Protocol
    Protocol -->|manages sessions| Session
    Protocol -->|routes topics| Routing
    Protocol -->|handles bridge| Bridge
    Protocol -->|invokes hooks| PluginLoader

    Bridge -->|outbound/inbound| Transport
    Session -->|store state| Persistence
    Routing -->|retain messages| Persistence

    Config -->|settings| Transport
    Config -->|settings| Protocol
    Config -->|settings| Bridge
    Config -->|settings| PluginLoader

    Protocol -->|logs events| Logging
    PluginLoader -->|logs plugin events| Logging
    Persistence -->|logs errors| Logging

    PluginLoader --> AuthPlugins
    PluginLoader --> DynSec
    PluginLoader --> Timestamp
    PluginLoader --> PayloadMod

    TLS -->|secure transport| Transport
    DNS -->|service discovery| Transport
    Docker -->|containerizes| Transport
    Docker -->|containerizes| Protocol
    Docker -->|containerizes| Bridge
    Tests -->|validates| Transport
    Tests -->|validates| Protocol
    Tests -->|validates| Bridge

    click Transport "https://github.com/jesse6548/mosquitto/blob/master/src/net.c"
    click Protocol "https://github.com/jesse6548/mosquitto/blob/master/src/handle_connect.c"
    click Session "https://github.com/jesse6548/mosquitto/blob/master/src/context.c"
    click Routing "https://github.com/jesse6548/mosquitto/blob/master/src/topic_tok.c"
    click Bridge "https://github.com/jesse6548/mosquitto/blob/master/src/bridge.c"
    click PluginLoader "https://github.com/jesse6548/mosquitto/blob/master/src/plugin.c"
    click Persistence "https://github.com/jesse6548/mosquitto/blob/master/src/persist_read.c"
    click Config "https://github.com/jesse6548/mosquitto/blob/master/src/conf.c"
    click Logging "https://github.com/jesse6548/mosquitto/blob/master/src/logging.c"
    click libC "https://github.com/jesse6548/mosquitto/tree/master/lib/"
    click libCPP "https://github.com/jesse6548/mosquitto/blob/master/lib/cpp/mosquittopp.cpp"
    click pub "https://github.com/jesse6548/mosquitto/blob/master/client/pub_client.c"
    click ctrl "https://github.com/jesse6548/mosquitto/blob/master/apps/mosquitto_ctrl/mosquitto_ctrl.c"
    click passwd "https://github.com/jesse6548/mosquitto/blob/master/apps/mosquitto_passwd/mosquitto_passwd.c"
    click AuthPlugins "https://github.com/jesse6548/mosquitto/blob/master/plugins/auth-by-ip/mosquitto_auth_by_ip.c"
    click DynSec "https://github.com/jesse6548/mosquitto/blob/master/plugins/dynamic-security/plugin.c"
    click Timestamp "https://github.com/jesse6548/mosquitto/blob/master/plugins/message-timestamp/mosquitto_message_timestamp.c"
    click PayloadMod "https://github.com/jesse6548/mosquitto/blob/master/plugins/payload-modification/mosquitto_payload_modification.c"
    click Docker "https://github.com/jesse6548/mosquitto/tree/master/docker/"
    click Docs "https://github.com/jesse6548/mosquitto/tree/master/doc/"
    click Tests "https://github.com/jesse6548/mosquitto/tree/master/test/"

    classDef core fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef client fill:#E6FFED,stroke:#22863A,color:#22863A;
    classDef plugin fill:#FFEDD5,stroke:#D15704,color:#D15704;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
```
