# robustmq/robustmq architecture

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

- Interactive diagram: https://gitdiagram.com/robustmq/robustmq
- Repository: https://github.com/robustmq/robustmq

## Overview

RobustMQ is a unified, multi-protocol messaging broker: clients publish or send messages through MQTT, Kafka, NATS, AMQP, or mq9, and protocol consumers can read shared message storage. The README also describes mq9 agent discovery and persistent mailboxes, tenant isolation, connectors, multiple storage modes, and Raft-backed clustering. The tree and excerpts support the major subsystems, but not all protocol-handler internals; edges therefore rely on the documented shared-storage and capability relationships rather than inferred calls between unsampled modules.

Main entry points: [`src/storage-engine/src/core/cache.rs`](https://github.com/robustmq/robustmq/blob/main/src/storage-engine/src/core/cache.rs) (Storage engine), [`src/common/security/src/manager.rs`](https://github.com/robustmq/robustmq/blob/main/src/common/security/src/manager.rs) (Tenant and permissions), [`src/mqtt-broker`](https://github.com/robustmq/robustmq/tree/main/src/mqtt-broker) (MQTT broker), [`src/kafka-broker`](https://github.com/robustmq/robustmq/tree/main/src/kafka-broker) (Kafka broker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocols["Messaging protocols"]
  node_mqtt["MQTT broker"]
  node_kafka["Kafka broker"]
  node_nats["NATS broker"]
  node_amqp["AMQP broker"]
  node_mq9["mq9 agent messaging"]
end

subgraph group_storage["Shared data plane"]
  node_engine["Storage engine<br/>[cache.rs]"]
  node_memory[("Memory storage<br/>[engine.rs]")]
  node_rocksdb[("RocksDB storage<br/>[engine.rs]")]
  node_offsets["Shard offsets<br/>[offset.rs]"]
end

subgraph group_cluster["Cluster management"]
  node_metadata["Metadata service<br/>[cache.rs]"]
  node_raft["Raft coordination<br/>[manager.rs]"]
  node_cluster_api["Metadata gRPC<br/>[service_engine.rs]"]
end

subgraph group_integrations["Extensions and management"]
  node_connectors["Data connectors<br/>[core.rs]"]
  node_admin["Admin and MCP<br/>[server.rs]"]
  node_tenant["Tenant and permissions<br/>[manager.rs]"]
end

node_clients(("Clients and agents"))

node_clients -->|"publishes and subscribes"| node_mqtt
node_clients -->|"produces and consumes"| node_kafka
node_clients -->|"publishes and subscribes"| node_nats
node_clients -->|"publishes and consumes"| node_amqp
node_clients -->|"discovers and messages"| node_mq9
node_mqtt -->|"shares message storage"| node_engine
node_kafka -->|"shares message storage"| node_engine
node_nats -->|"shares message storage"| node_engine
node_amqp -->|"shares message storage"| node_engine
node_mq9 -->|"shares message storage"| node_engine
node_engine -->|"uses storage mode"| node_memory
node_engine -->|"uses storage mode"| node_rocksdb
node_engine -->|"tracks shard offsets"| node_offsets
node_metadata -.->|"coordinates cluster state"| node_raft
node_cluster_api -->|"serves metadata operations"| node_metadata
node_connectors -.->|"exports messages"| node_engine
node_admin -.->|"manages cluster"| node_metadata
node_tenant -.->|"isolates tenant access"| node_mqtt
node_tenant -.->|"isolates tenant access"| node_kafka
node_tenant -.->|"isolates tenant access"| node_nats
node_tenant -.->|"isolates tenant access"| node_amqp
node_tenant -.->|"isolates tenant access"| node_mq9

click node_mqtt "https://github.com/robustmq/robustmq/tree/main/src/mqtt-broker"
click node_kafka "https://github.com/robustmq/robustmq/tree/main/src/kafka-broker"
click node_nats "https://github.com/robustmq/robustmq/tree/main/src/nats-broker"
click node_amqp "https://github.com/robustmq/robustmq/tree/main/src/amqp-broker"
click node_mq9 "https://github.com/robustmq/robustmq/tree/main/src/mq9-core"
click node_engine "https://github.com/robustmq/robustmq/blob/main/src/storage-engine/src/core/cache.rs"
click node_memory "https://github.com/robustmq/robustmq/blob/main/src/storage-engine/src/commitlog/memory/engine.rs"
click node_rocksdb "https://github.com/robustmq/robustmq/blob/main/src/storage-engine/src/commitlog/rocksdb/engine.rs"
click node_offsets "https://github.com/robustmq/robustmq/blob/main/src/storage-engine/src/core/offset.rs"
click node_metadata "https://github.com/robustmq/robustmq/blob/main/src/meta-service/src/core/cache.rs"
click node_raft "https://github.com/robustmq/robustmq/blob/main/src/meta-service/src/raft/manager.rs"
click node_cluster_api "https://github.com/robustmq/robustmq/blob/main/src/meta-service/src/server/service_engine.rs"
click node_connectors "https://github.com/robustmq/robustmq/blob/main/src/connector/src/core.rs"
click node_admin "https://github.com/robustmq/robustmq/blob/main/src/admin-server/src/server.rs"
click node_tenant "https://github.com/robustmq/robustmq/blob/main/src/common/security/src/manager.rs"

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_mqtt,node_kafka,node_nats,node_amqp,node_mq9,node_clients toneBlue
class node_engine,node_memory,node_rocksdb,node_offsets toneAmber
class node_metadata,node_raft,node_cluster_api toneMint
class node_connectors,node_admin,node_tenant toneRose
```

## Components

### Messaging protocols

- [MQTT broker](https://github.com/robustmq/robustmq/tree/main/src/mqtt-broker): `src/mqtt-broker`
- [Kafka broker](https://github.com/robustmq/robustmq/tree/main/src/kafka-broker): `src/kafka-broker`
- [NATS broker](https://github.com/robustmq/robustmq/tree/main/src/nats-broker): `src/nats-broker`
- [AMQP broker](https://github.com/robustmq/robustmq/tree/main/src/amqp-broker): `src/amqp-broker`
- [mq9 agent messaging](https://github.com/robustmq/robustmq/tree/main/src/mq9-core): `src/mq9-core`

### Shared data plane

- [Storage engine](https://github.com/robustmq/robustmq/blob/main/src/storage-engine/src/core/cache.rs): `src/storage-engine/src/core/cache.rs`
- [Memory storage](https://github.com/robustmq/robustmq/blob/main/src/storage-engine/src/commitlog/memory/engine.rs): `src/storage-engine/src/commitlog/memory/engine.rs`
- [RocksDB storage](https://github.com/robustmq/robustmq/blob/main/src/storage-engine/src/commitlog/rocksdb/engine.rs): `src/storage-engine/src/commitlog/rocksdb/engine.rs`
- [Shard offsets](https://github.com/robustmq/robustmq/blob/main/src/storage-engine/src/core/offset.rs): `src/storage-engine/src/core/offset.rs`

### Cluster management

- [Metadata service](https://github.com/robustmq/robustmq/blob/main/src/meta-service/src/core/cache.rs): `src/meta-service/src/core/cache.rs`
- [Raft coordination](https://github.com/robustmq/robustmq/blob/main/src/meta-service/src/raft/manager.rs): `src/meta-service/src/raft/manager.rs`
- [Metadata gRPC](https://github.com/robustmq/robustmq/blob/main/src/meta-service/src/server/service_engine.rs): `src/meta-service/src/server/service_engine.rs`

### Extensions and management

- [Data connectors](https://github.com/robustmq/robustmq/blob/main/src/connector/src/core.rs): `src/connector/src/core.rs`
- [Admin and MCP](https://github.com/robustmq/robustmq/blob/main/src/admin-server/src/server.rs): `src/admin-server/src/server.rs`
- [Tenant and permissions](https://github.com/robustmq/robustmq/blob/main/src/common/security/src/manager.rs): `src/common/security/src/manager.rs`

### Other components

- **Clients and agents**

## Connections

- Clients and agents → MQTT broker: publishes and subscribes
- Clients and agents → Kafka broker: produces and consumes
- Clients and agents → NATS broker: publishes and subscribes
- Clients and agents → AMQP broker: publishes and consumes
- Clients and agents → mq9 agent messaging: discovers and messages
- MQTT broker → Storage engine: shares message storage
- Kafka broker → Storage engine: shares message storage
- NATS broker → Storage engine: shares message storage
- AMQP broker → Storage engine: shares message storage
- mq9 agent messaging → Storage engine: shares message storage
- Storage engine → Memory storage: uses storage mode (evidence: `src/storage-engine/src/commitlog/memory/engine.rs`)
- Storage engine → RocksDB storage: uses storage mode (evidence: `src/storage-engine/src/commitlog/rocksdb/engine.rs`)
- Storage engine → Shard offsets: tracks shard offsets (evidence: `src/storage-engine/src/commitlog/memory/engine.rs`)
- Metadata service → Raft coordination: coordinates cluster state
- Metadata gRPC → Metadata service: serves metadata operations (evidence: `src/meta-service/src/server/service_engine.rs`)
- Data connectors → Storage engine: exports messages
- Admin and MCP → Metadata service: manages cluster
- Tenant and permissions → MQTT broker: isolates tenant access
- Tenant and permissions → Kafka broker: isolates tenant access
- Tenant and permissions → NATS broker: isolates tenant access
- Tenant and permissions → AMQP broker: isolates tenant access
- Tenant and permissions → mq9 agent messaging: isolates tenant access
