Why TBMQ?

TBMQ is an MQTT broker built by the ThingsBoard team, drawing on years of operating IoT infrastructure at scale. Its design starts from a single observation: IoT traffic is not uniform. Devices publish continuously, backend applications subscribe to high-volume streams, and commands must reach specific targets reliably. Most brokers treat all three the same way. TBMQ gives each its own processing path — and the architecture to back it up.

Each figure below comes from a published test, with the hardware and load profile documented.

IoT deployments generate three fundamentally different kinds of traffic. TBMQ is designed around all three.

Fan-in: Thousands or millions of devices continuously publish telemetry, events, and sensor readings. A small set of backend applications must consume every message in order — even during spikes or partial outages. Dropping or reordering messages is not acceptable. TBMQ gives each of those applications its own Kafka topic, so a backlog accumulates in Kafka instead of in broker memory.

Fan-out: A single update or command must reach a large number of subscribed devices simultaneously. One incoming message produces many outgoing deliveries. Every subscriber must receive it, which makes the cost of topic matching the deciding factor.

Point-to-point: A publisher targets a specific subscriber through a uniquely defined topic. Command-response interactions, remote control flows, and device-to-device messaging all require low-latency, targeted delivery — including when the target is briefly offline and its messages have to wait for it.

TBMQ is built on Kafka for message durability and distribution, Netty for non-blocking network transport, an Actor system for per-client concurrency, and a Trie data structure for subscription matching in memory. These are not incidental technology choices — each directly determines how the broker behaves under load, during failures, and as the cluster grows.

TBMQ does not send a PUBACK or PUBREC to the publisher until Kafka has confirmed the message is stored. Once the publisher holds that acknowledgment, the message no longer depends on the node that received it: if that node crashes before delivery completes, another node picks up from Kafka and continues. Nothing is lost between acknowledgment and delivery.

That guarantee holds at full throughput. How far it extends past a TBMQ node is a matter of how you run Kafka — the shipped defaults keep a single copy of each message (acks=1, replication factor 1), so surviving the loss of a Kafka broker means running a replicated Kafka cluster with matching producer acknowledgments.

All active client subscriptions are loaded from Kafka and stored in a Trie data structure held in memory. When a PUBLISH arrives, TBMQ traverses the Trie to find matching subscribers. Lookup time is proportional to the length of the topic — not the number of subscriptions. Adding more subscribers does not slow down message routing. A broker with one million subscriptions matches topics in the same time as one with a thousand.

TBMQ classifies persistent clients into two categories based on observed IoT traffic patterns:

• DEVICE clients publish frequently and subscribe to few topics at low message rates. While such a client is offline, its messages wait in a per-client queue in Redis (or Valkey), which absorbs high write rates and hands the queue back quickly on reconnect. Kafka still holds the durable record.
• APPLICATION clients subscribe to high-volume topics and need messages buffered while offline. Each one gets a dedicated Kafka topic and its own consumer, so messages accumulate safely in Kafka and are delivered in order when the client returns — replayed from the client’s committed offset rather than re-queued one by one.

This separation means that a spike in device publishing does not delay delivery to application subscribers, and a slow application subscriber does not affect device-to-device or broker-to-device flows.

Every node in a TBMQ cluster is identical. There is no master process, no leader election, and no coordinator that becomes a bottleneck or a single point of failure. A load balancer distributes incoming MQTT connections across all available nodes.

All nodes share session and subscription state through Kafka. When a client reconnects after a node failure, any node in the cluster can resume its session from the latest state in Kafka — no session is tied to a specific node.

Start a new node and it joins the cluster automatically. Kafka consumer groups rebalance, distributing the load across the expanded cluster. No manual resharding, no downtime, no configuration changes.

For details, see the TBMQ architecture page.

TBMQ speaks every published version of the protocol, in both single-node and cluster deployments:

• MQTT 3.1
• MQTT 3.1.1
• MQTT 5.0

MQTT 5.0 support is not a subset: shared subscriptions, topic aliases, flow control, enhanced authentication, session and message expiry, will delay, user properties, subscription identifiers, and reason codes on every acknowledgement. For the per-feature behavior in TBMQ, see MQTT 5.0 features in TBMQ.