# moquette-io/moquette architecture

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

- Interactive diagram: https://gitdiagram.com/moquette-io/moquette
- Repository: https://github.com/moquette-io/moquette

## Overview

Moquette is an embeddable MQTT 3/5 broker. MQTT clients connect to the broker’s Netty-based protocol handling; sessions and routing support delivery, subscriptions, retained messages, and QoS flows, with configurable persistence and optional metrics/interception. The README lists MQTT 5 capabilities including shared subscriptions, expiry, request/response, aliases, and flow control. Several core implementations were not excerpted, so their internal call relationships are not asserted; links to those features reflect documented product behavior rather than inspected method calls.

Main entry points: [`broker/src/main/java/io/moquette/broker/Server.java`](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/Server.java) (Broker server), [`broker/src/main/java/io/moquette/broker/PostOffice.java`](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/PostOffice.java) (Message routing), [`broker/src/main/java/io/moquette/metrics/MetricsProvider.java`](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/metrics/MetricsProvider.java) (Metrics provider), [`broker/src/main/java/io/moquette/broker/SessionRegistry.java`](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/SessionRegistry.java) (Session registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Broker runtime"]
  node_server["Broker server<br/>[Server.java]"]
  node_netty["Netty handlers"]
  node_connection["MQTT connection"]
end

subgraph group_messaging["Messaging state"]
  node_sessions["Session registry"]
  node_session["Client session<br/>[Session.java]"]
  node_routing["Message routing<br/>[PostOffice.java]"]
  node_subscriptions["Topic subscriptions"]
  node_topic["Topic matching<br/>[Topic.java]"]
  node_retained["Retained messages"]
  node_persistence[("Persistent storage")]
end

subgraph group_operations["Configuration and security"]
  node_configuration["Broker configuration<br/>[IConfig.java]"]
  node_security["Authentication and ACL"]
end

subgraph group_extensions["Broker extensions"]
  node_interception["Event interception"]
  node_metrics["Metrics provider"]
  node_prometheus["Prometheus exporter"]
end

node_clients(("MQTT clients"))

node_clients -->|"send MQTT"| node_netty
node_server -->|"uses config"| node_configuration
node_server -->|"configures stores"| node_persistence
node_server -->|"registers handlers"| node_interception
node_connection -.-> node_sessions
node_sessions -.-> node_session
node_session -.-> node_routing
node_routing -.-> node_subscriptions
node_subscriptions -.-> node_topic
node_routing -.-> node_retained
node_metrics -->|"initialized with"| node_configuration
node_metrics -.->|"loads provider"| node_prometheus

click node_server "https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/Server.java"
click node_netty "https://github.com/moquette-io/moquette/tree/main/broker/src/main/java/io/moquette/broker"
click node_connection "https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/MQTTConnection.java"
click node_sessions "https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/SessionRegistry.java"
click node_session "https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/Session.java"
click node_routing "https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/PostOffice.java"
click node_subscriptions "https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/subscriptions/CTrieSubscriptionDirectory.java"
click node_topic "https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/subscriptions/Topic.java"
click node_retained "https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/IRetainedRepository.java"
click node_persistence "https://github.com/moquette-io/moquette/tree/main/broker/src/main/java/io/moquette/persistence"
click node_configuration "https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/config/IConfig.java"
click node_security "https://github.com/moquette-io/moquette/tree/main/broker/src/main/java/io/moquette/broker/security"
click node_interception "https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/interception/InterceptHandler.java"
click node_metrics "https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/metrics/MetricsProvider.java"
click node_prometheus "https://github.com/moquette-io/moquette/blob/main/metrics_prometheus/src/main/java/io/moquette/metrics/prometheus/MetricsProviderPrometheus.java"

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_server,node_netty,node_connection,node_clients toneBlue
class node_sessions,node_session,node_routing,node_subscriptions,node_topic,node_retained,node_persistence toneAmber
class node_configuration,node_security toneMint
class node_interception,node_metrics,node_prometheus toneRose
```

## Components

### Broker runtime

- [Broker server](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/Server.java): `broker/src/main/java/io/moquette/broker/Server.java`
- [Netty handlers](https://github.com/moquette-io/moquette/tree/main/broker/src/main/java/io/moquette/broker): `broker/src/main/java/io/moquette/broker`
- [MQTT connection](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/MQTTConnection.java): `broker/src/main/java/io/moquette/broker/MQTTConnection.java`

### Messaging state

- [Session registry](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/SessionRegistry.java): `broker/src/main/java/io/moquette/broker/SessionRegistry.java`
- [Client session](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/Session.java): `broker/src/main/java/io/moquette/broker/Session.java`
- [Message routing](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/PostOffice.java): `broker/src/main/java/io/moquette/broker/PostOffice.java`
- [Topic subscriptions](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/subscriptions/CTrieSubscriptionDirectory.java): `broker/src/main/java/io/moquette/broker/subscriptions/CTrieSubscriptionDirectory.java`
- [Topic matching](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/subscriptions/Topic.java): `broker/src/main/java/io/moquette/broker/subscriptions/Topic.java`
- [Retained messages](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/IRetainedRepository.java): `broker/src/main/java/io/moquette/broker/IRetainedRepository.java`
- [Persistent storage](https://github.com/moquette-io/moquette/tree/main/broker/src/main/java/io/moquette/persistence): `broker/src/main/java/io/moquette/persistence`

### Configuration and security

- [Broker configuration](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/broker/config/IConfig.java): `broker/src/main/java/io/moquette/broker/config/IConfig.java`
- [Authentication and ACL](https://github.com/moquette-io/moquette/tree/main/broker/src/main/java/io/moquette/broker/security): `broker/src/main/java/io/moquette/broker/security`

### Broker extensions

- [Event interception](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/interception/InterceptHandler.java): `broker/src/main/java/io/moquette/interception/InterceptHandler.java`
- [Metrics provider](https://github.com/moquette-io/moquette/blob/main/broker/src/main/java/io/moquette/metrics/MetricsProvider.java): `broker/src/main/java/io/moquette/metrics/MetricsProvider.java`
- [Prometheus exporter](https://github.com/moquette-io/moquette/blob/main/metrics_prometheus/src/main/java/io/moquette/metrics/prometheus/MetricsProviderPrometheus.java): `metrics_prometheus/src/main/java/io/moquette/metrics/prometheus/MetricsProviderPrometheus.java`

### Other components

- **MQTT clients**

## Connections

- MQTT clients → Netty handlers: send MQTT
- Broker server → Broker configuration: uses config (evidence: `broker/src/main/java/io/moquette/broker/Server.java`)
- Broker server → Persistent storage: configures stores (evidence: `broker/src/main/java/io/moquette/broker/Server.java`)
- Broker server → Event interception: registers handlers (evidence: `broker/src/main/java/io/moquette/broker/Server.java`)
- MQTT connection → Session registry
- Session registry → Client session (evidence: `broker/src/main/java/io/moquette/broker/Session.java`)
- Client session → Message routing
- Message routing → Topic subscriptions
- Topic subscriptions → Topic matching
- Message routing → Retained messages
- Metrics provider → Broker configuration: initialized with (evidence: `broker/src/main/java/io/moquette/metrics/MetricsManager.java`)
- Metrics provider → Prometheus exporter: loads provider (evidence: `metrics_prometheus/src/main/java/io/moquette/metrics/prometheus/MetricsProviderPrometheus.java`)
