# snodec/mqttsuite architecture

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

- Interactive diagram: https://gitdiagram.com/snodec/mqttsuite
- Repository: https://github.com/snodec/mqttsuite

## Overview

MQTTSuite is a collection of MQTT 3.1.1 applications. A typical message workflow uses mqttcli to publish or subscribe through mqttbroker; optional branches translate mapped topics, bridge brokers, or persist messages to MariaDB. The integrator UI edits mapping configurations, while broker-side administration exposes mapping configuration and draft operations. The README documents product capabilities; unsampled implementation links are omitted or marked unverified rather than inferred from names.

Main entry points: [`mqttbroker/lib/Mqtt.cpp`](https://github.com/snodec/mqttsuite/blob/master/mqttbroker/lib/Mqtt.cpp) (MQTT broker), [`lib/MappingAdminRouter.cpp`](https://github.com/snodec/mqttsuite/blob/master/lib/MappingAdminRouter.cpp) (Mapping admin API), [`mqttintegrator/ui/src/app/shared/services/mapping.service.ts`](https://github.com/snodec/mqttsuite/blob/master/mqttintegrator/ui/src/app/shared/services/mapping.service.ts) (Mapping state service), [`mqttbridge/mqttbridge.cpp`](https://github.com/snodec/mqttsuite/blob/master/mqttbridge/mqttbridge.cpp) (Bridge application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared mapping runtime"]
  node_config_app["Application config"]
  node_mapping_reader["Mapping reader"]
  node_mapping_runtime["Topic mapper<br/>[MqttMapper.h]"]
  node_mapping_admin["Mapping admin API"]
  node_template_plugin["Template storage plugin<br/>[Storage.cpp]"]
  node_template_engine["Template engine<br/>[inja.hpp]"]
  node_logger["Logging<br/>[Log.h]"]
end

subgraph group_brokercli["Broker and CLI"]
  node_cli["MQTT command client<br/>[Mqtt.cpp]"]
  node_broker["MQTT broker<br/>[Mqtt.cpp]"]
  node_broker_model["Broker routing<br/>[MqttModel.cpp]"]
end

subgraph group_integrator["Mapping integrator"]
  node_mapping_ui["Mapping editor UI<br/>[edit-topic.ts]"]
  node_mapping_service["Mapping state service<br/>[mapping.service.ts]"]
  node_mapping_adapter["Mapping format adapter<br/>[mapping-adapter.ts]"]
  node_mapping_api["Mapping API client<br/>[api.service.ts]"]
  node_integrator_mqtt["Integrator MQTT runtime<br/>[Mqtt.cpp]"]
end

subgraph group_bridge["Broker bridging"]
  node_bridge_ui["Bridge configuration UI<br/>[BridgeForm.tsx]"]
  node_bridge_app["Bridge application<br/>[mqttbridge.cpp]"]
  node_bridge_store["Bridge configuration store<br/>[BridgeStore.cpp]"]
  node_bridge_runtime["Bridge message handling<br/>[Bridge.cpp]"]
  node_sse["Bridge status events<br/>[SSEDistributor.cpp]"]
end

subgraph group_storage["Message storage"]
  node_storage_plan["Storage projections<br/>[StoragePlan.cpp]"]
  node_store_mqtt["Storage MQTT handler<br/>[Mqtt.cpp]"]
  node_mariadb_storage["MariaDB writer<br/>[MariaDbStorage.cpp]"]
  node_mariadb[("MariaDB")]
end

node_user(("Operator or device"))

node_user -->|"publish or subscribe"| node_cli
node_cli -->|"exchange messages"| node_broker
node_broker -.->|"route messages"| node_broker_model
node_broker -->|"translate topics"| node_mapping_runtime
node_mapping_admin -->|"reads active mapping"| node_config_app
node_mapping_admin -->|"creates drafts"| node_mapping_reader
node_mapping_admin -->|"reads active mapping"| node_mapping_runtime
node_mapping_runtime -.->|"uses plugin"| node_template_plugin
node_template_plugin -.->|"evaluates templates"| node_template_engine
node_user -.->|"edit mappings"| node_mapping_ui
node_mapping_ui -.->|"updates mapping state"| node_mapping_service
node_mapping_service -->|"converts mapping"| node_mapping_adapter
node_mapping_service -->|"deploys configuration"| node_mapping_api
node_mapping_api -.->|"HTTP API"| node_mapping_admin
node_user -.->|"configure bridges"| node_bridge_ui
node_bridge_ui -.->|"manage configuration"| node_bridge_app
node_bridge_app -.->|"loads configuration"| node_bridge_store
node_bridge_app -.->|"runs bridge"| node_bridge_runtime
node_bridge_runtime -.->|"reports status"| node_sse
node_broker -->|"delivers messages"| node_store_mqtt
node_store_mqtt -.->|"matches projections"| node_storage_plan
node_store_mqtt -.->|"stores messages"| node_mariadb_storage
node_mariadb_storage -->|"writes records"| node_mariadb
node_user -.->|"configure integration"| node_integrator_mqtt

click node_cli "https://github.com/snodec/mqttsuite/blob/master/mqttcli/lib/Mqtt.cpp"
click node_broker "https://github.com/snodec/mqttsuite/blob/master/mqttbroker/lib/Mqtt.cpp"
click node_broker_model "https://github.com/snodec/mqttsuite/blob/master/mqttbroker/lib/MqttModel.cpp"
click node_config_app "https://github.com/snodec/mqttsuite/blob/master/lib/ConfigApplication.h"
click node_mapping_reader "https://github.com/snodec/mqttsuite/blob/master/lib/JsonMappingReader.h"
click node_mapping_runtime "https://github.com/snodec/mqttsuite/blob/master/lib/MqttMapper.h"
click node_mapping_admin "https://github.com/snodec/mqttsuite/blob/master/lib/MappingAdminRouter.cpp"
click node_template_plugin "https://github.com/snodec/mqttsuite/blob/master/lib/plugins/storage/Storage.cpp"
click node_template_engine "https://github.com/snodec/mqttsuite/blob/master/lib/inja.hpp"
click node_mapping_ui "https://github.com/snodec/mqttsuite/blob/master/mqttintegrator/ui/src/app/components/edit-topic/edit-topic.ts"
click node_mapping_service "https://github.com/snodec/mqttsuite/blob/master/mqttintegrator/ui/src/app/shared/services/mapping.service.ts"
click node_mapping_adapter "https://github.com/snodec/mqttsuite/blob/master/mqttintegrator/ui/src/app/shared/adapter/mapping-adapter.ts"
click node_mapping_api "https://github.com/snodec/mqttsuite/blob/master/mqttintegrator/ui/src/app/shared/services/api.service.ts"
click node_bridge_ui "https://github.com/snodec/mqttsuite/blob/master/mqttbridge/ui/src/components/BridgeForm.tsx"
click node_bridge_app "https://github.com/snodec/mqttsuite/blob/master/mqttbridge/mqttbridge.cpp"
click node_bridge_store "https://github.com/snodec/mqttsuite/blob/master/mqttbridge/lib/BridgeStore.cpp"
click node_bridge_runtime "https://github.com/snodec/mqttsuite/blob/master/mqttbridge/lib/Bridge.cpp"
click node_sse "https://github.com/snodec/mqttsuite/blob/master/mqttbridge/lib/SSEDistributor.cpp"
click node_storage_plan "https://github.com/snodec/mqttsuite/blob/master/mqttstore/lib/StoragePlan.cpp"
click node_store_mqtt "https://github.com/snodec/mqttsuite/blob/master/mqttstore/lib/Mqtt.cpp"
click node_mariadb_storage "https://github.com/snodec/mqttsuite/blob/master/mqttstore/lib/MariaDbStorage.cpp"
click node_logger "https://github.com/snodec/mqttsuite/blob/master/lib/Log.h"
click node_integrator_mqtt "https://github.com/snodec/mqttsuite/blob/master/mqttintegrator/lib/Mqtt.cpp"

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_config_app,node_mapping_reader,node_mapping_runtime,node_mapping_admin,node_template_plugin,node_template_engine,node_logger toneBlue
class node_cli,node_broker,node_broker_model toneAmber
class node_mapping_ui,node_mapping_service,node_mapping_adapter,node_mapping_api,node_integrator_mqtt toneMint
class node_bridge_ui,node_bridge_app,node_bridge_store,node_bridge_runtime,node_sse toneRose
class node_storage_plan,node_store_mqtt,node_mariadb_storage,node_mariadb,node_user toneIndigo
```

## Components

### Shared mapping runtime

- [Application config](https://github.com/snodec/mqttsuite/blob/master/lib/ConfigApplication.h): `lib/ConfigApplication.h`
- [Mapping reader](https://github.com/snodec/mqttsuite/blob/master/lib/JsonMappingReader.h): `lib/JsonMappingReader.h`
- [Topic mapper](https://github.com/snodec/mqttsuite/blob/master/lib/MqttMapper.h): `lib/MqttMapper.h`
- [Mapping admin API](https://github.com/snodec/mqttsuite/blob/master/lib/MappingAdminRouter.cpp): `lib/MappingAdminRouter.cpp`
- [Template storage plugin](https://github.com/snodec/mqttsuite/blob/master/lib/plugins/storage/Storage.cpp): `lib/plugins/storage/Storage.cpp`
- [Template engine](https://github.com/snodec/mqttsuite/blob/master/lib/inja.hpp): `lib/inja.hpp`
- [Logging](https://github.com/snodec/mqttsuite/blob/master/lib/Log.h): `lib/Log.h`

### Broker and CLI

- [MQTT command client](https://github.com/snodec/mqttsuite/blob/master/mqttcli/lib/Mqtt.cpp): `mqttcli/lib/Mqtt.cpp`
- [MQTT broker](https://github.com/snodec/mqttsuite/blob/master/mqttbroker/lib/Mqtt.cpp): `mqttbroker/lib/Mqtt.cpp`
- [Broker routing](https://github.com/snodec/mqttsuite/blob/master/mqttbroker/lib/MqttModel.cpp): `mqttbroker/lib/MqttModel.cpp`

### Mapping integrator

- [Mapping editor UI](https://github.com/snodec/mqttsuite/blob/master/mqttintegrator/ui/src/app/components/edit-topic/edit-topic.ts): `mqttintegrator/ui/src/app/components/edit-topic/edit-topic.ts`
- [Mapping state service](https://github.com/snodec/mqttsuite/blob/master/mqttintegrator/ui/src/app/shared/services/mapping.service.ts): `mqttintegrator/ui/src/app/shared/services/mapping.service.ts`
- [Mapping format adapter](https://github.com/snodec/mqttsuite/blob/master/mqttintegrator/ui/src/app/shared/adapter/mapping-adapter.ts): `mqttintegrator/ui/src/app/shared/adapter/mapping-adapter.ts`
- [Mapping API client](https://github.com/snodec/mqttsuite/blob/master/mqttintegrator/ui/src/app/shared/services/api.service.ts): `mqttintegrator/ui/src/app/shared/services/api.service.ts`
- [Integrator MQTT runtime](https://github.com/snodec/mqttsuite/blob/master/mqttintegrator/lib/Mqtt.cpp): `mqttintegrator/lib/Mqtt.cpp`

### Broker bridging

- [Bridge configuration UI](https://github.com/snodec/mqttsuite/blob/master/mqttbridge/ui/src/components/BridgeForm.tsx): `mqttbridge/ui/src/components/BridgeForm.tsx`
- [Bridge application](https://github.com/snodec/mqttsuite/blob/master/mqttbridge/mqttbridge.cpp): `mqttbridge/mqttbridge.cpp`
- [Bridge configuration store](https://github.com/snodec/mqttsuite/blob/master/mqttbridge/lib/BridgeStore.cpp): `mqttbridge/lib/BridgeStore.cpp`
- [Bridge message handling](https://github.com/snodec/mqttsuite/blob/master/mqttbridge/lib/Bridge.cpp): `mqttbridge/lib/Bridge.cpp`
- [Bridge status events](https://github.com/snodec/mqttsuite/blob/master/mqttbridge/lib/SSEDistributor.cpp): `mqttbridge/lib/SSEDistributor.cpp`

### Message storage

- [Storage projections](https://github.com/snodec/mqttsuite/blob/master/mqttstore/lib/StoragePlan.cpp): `mqttstore/lib/StoragePlan.cpp`
- [Storage MQTT handler](https://github.com/snodec/mqttsuite/blob/master/mqttstore/lib/Mqtt.cpp): `mqttstore/lib/Mqtt.cpp`
- [MariaDB writer](https://github.com/snodec/mqttsuite/blob/master/mqttstore/lib/MariaDbStorage.cpp): `mqttstore/lib/MariaDbStorage.cpp`
- **MariaDB**

### Other components

- **Operator or device**

## Connections

- Operator or device → MQTT command client: publish or subscribe (evidence: `README.md`)
- MQTT command client → MQTT broker: exchange messages (evidence: `README.md`)
- MQTT broker → Broker routing: route messages
- MQTT broker → Topic mapper: translate topics (evidence: `README.md`)
- Mapping admin API → Application config: reads active mapping (evidence: `lib/MappingAdminRouter.cpp`)
- Mapping admin API → Mapping reader: creates drafts (evidence: `lib/MappingAdminRouter.cpp`)
- Mapping admin API → Topic mapper: reads active mapping (evidence: `lib/MappingAdminRouter.cpp`)
- Topic mapper → Template storage plugin: uses plugin
- Template storage plugin → Template engine: evaluates templates
- Operator or device → Mapping editor UI: edit mappings
- Mapping editor UI → Mapping state service: updates mapping state
- Mapping state service → Mapping format adapter: converts mapping (evidence: `mqttintegrator/ui/src/app/shared/services/mapping.service.ts`)
- Mapping state service → Mapping API client: deploys configuration (evidence: `mqttintegrator/ui/src/app/shared/services/mapping.service.ts`)
- Mapping API client → Mapping admin API: HTTP API
- Operator or device → Bridge configuration UI: configure bridges
- Bridge configuration UI → Bridge application: manage configuration
- Bridge application → Bridge configuration store: loads configuration
- Bridge application → Bridge message handling: runs bridge
- Bridge message handling → Bridge status events: reports status
- MQTT broker → Storage MQTT handler: delivers messages (evidence: `README.md`)
- Storage MQTT handler → Storage projections: matches projections
- Storage MQTT handler → MariaDB writer: stores messages
- MariaDB writer → MariaDB: writes records (evidence: `mqttstore/lib/MariaDbStorage.cpp`)
- Operator or device → Integrator MQTT runtime: configure integration