IoT Architecture Diagram: Devices, MQTT, Stream Processing and Storage

Most IoT diagrams have three boxes: devices, a cloud icon and a dashboard. The questions that matter live between them. How does the broker know which device is talking? What happens when a site loses its connection for an hour? Which messages can be lost or delivered twice? How does a command reach one sensor among thousands?

An IoT architecture diagram should answer those questions on the page. This post builds one for a concrete case, temperature monitoring in cold storage warehouses, and walks through the decisions behind each hop: MQTT and its quality of service levels, topic design, device identity, offline sites and event time, and where the data ends up.

The layers of an IoT system

Not every system needs every layer. Devices with cellular or Wi-Fi modules often publish directly to the broker without a gateway. Draw the layers you actually run.

Why MQTT

MQTT is a publish/subscribe protocol where clients connect to a broker and exchange messages by topic. The MQTT 5.0 specification, an OASIS Standard since March 2019, describes it as lightweight, open and simple to implement. Port 1883 is registered with IANA for MQTT without TLS and 8883 for MQTT over TLS. Anything that leaves the site should use 8883.

Each message is published with a quality of service (QoS) level:

QoS applies to each hop, not end to end: a subscriber receives a message at the lower of the QoS it was published with and the QoS granted to its subscription. With QoS 1, the broker may deliver duplicates, so every consumer needs to handle the same reading twice. A device-generated message ID or a timestamp per sensor makes that easy.

MQTT 5 adds a few features worth putting on the diagram:

• Retained messages. The broker keeps the last message on a topic and sends it to new subscribers, which suits a device's current status.
• Will messages. The broker publishes a client's will message after its connection drops without a clean disconnect, so a gateway can announce that it went offline.
• Message expiry. If a message expires before delivery starts, the broker deletes it. Use it for commands that are only valid for a while.
• Shared subscriptions. Several consumers share one subscription and each message goes to only one of them, so the bridge to the stream platform can scale out.

Topic design

Topics are hierarchical, and subscribers use + for one level and # for the rest. A layout such as site/{site}/device/{id}/telemetry lets you subscribe to one site, one device or everything, and it lets the broker restrict each device to its own topics. Topics that begin with $ are reserved for the broker, and filters that start with a wildcard do not match them.

Keep topics for routing and permissions. Put the schema version and the measurement time in the payload, where they can change without breaking every subscription.

Device identity

Give every device or gateway its own X.509 certificate signed by your device CA, and have the broker require client certificates. The certificate subject becomes the client ID, and the broker grants topics based on it. A stolen device can then be revoked on its own, and no shared password sits in the firmware of thousands of units. Decide how certificates are issued, at manufacturing or at first boot, and how they are rotated before they expire, and draw the CA on the diagram.

Offline sites and event time

Sites lose their connection. A gateway that buffers readings locally will send an hour of data in a burst when the link comes back, so data arrives late and out of order. Stamp each reading with the time it was measured, keep gateway clocks synchronized, and process in event time with an allowance for lateness. An alert such as "freezer above -18 °C for ten minutes" has to be computed on when the readings were taken, not when they arrived. The same thinking applies to any event-driven architecture.

The example: cold storage monitoring

Each warehouse has about forty freezer sensors that report every 30 seconds and a dozen door sensors that report on change. A site gateway collects their readings over the local radio, buffers them when offline and publishes them to the MQTT broker with QoS 1 over mutual TLS. The broker checks each client certificate against the device CA. A bridge with a shared subscription copies telemetry into Kafka. One consumer archives the raw messages to object storage; a stream processor computes one-minute aggregates in event time, writes them to a time-series store for dashboards and raises temperature alerts. Device management sends commands and configuration back through the broker.

How to read it:

• Left, the site. Sensors talk only to the site gateway; the gateway is the one client the broker sees from this site.
• Middle, the broker. Telemetry goes up with QoS 1. The dashed edges are commands down to the site and the certificate check against the device CA.
• Right, the data path. Kafka feeds the raw archive and the stream processor, which writes aggregates to the time-series store and raises alerts.
• The Markdown block holds the topic layout, the QoS per topic and the identity rule.

What to label

• Protocol, port and QoS on the link from the site to the broker.
• Message rates per device class. Forty sensors every 30 seconds is 80 messages a minute per site; multiply by the number of sites before sizing the broker.
• Identity: which certificate, which CA, and how certificates are rotated and revoked.
• Buffering: how long the gateway can hold data offline.
• Retention for each store, from hours in the stream to years in the archive.
• The command path, including message expiry and what a device does with an unknown command.

Common mistakes

• Shared credentials across devices. One leaked password then opens every device. Use one certificate per device.
• Port 1883 on the internet. Without TLS, readings and credentials travel in clear text.
• Assuming exactly once. QoS 1 can deliver duplicates; make consumers idempotent instead of reaching for QoS 2 everywhere.
• Processing in arrival time. Buffered data then triggers false alerts, or hides real ones.
• Devices writing straight to the database. You lose the broker's authentication, buffering and fan-out.
• No update path. Firmware updates and configuration changes are part of the architecture; draw them.
• Wildcard permissions for devices. A device allowed to subscribe to # can read every other device's data.

The network topology diagram covers the site's own network, which an IoT diagram usually leaves out.

Build it in Archboard

1. Sign in with Google or GitHub and create a diagram.
2. Add a Core Frame for the site. Inside it, from the Network pack, add a Device for each sensor group with the kind set to IoT / smart home, and another Device set to Modem / gateway for the site gateway.
3. From the C4 Model pack, add Container nodes for the MQTT broker, device management and the stream processor, and a Database for the time-series store.
4. From the Security pack, add a Certificate for the device CA.
5. From the Data pack, add Kafka and an Object Store for the raw archive. From the DevOps pack, add Metrics for the dashboards and an Alert node.
6. Connect them left to right, label the uplink with its QoS, make commands and the certificate check dashed, and add a Core Markdown block with the topic design.

The example uses 14 diagram nodes, within the Free plan. The network diagram page shows the rest of the Network pack.

FAQ

Should IoT devices use MQTT or HTTP? MQTT keeps one connection open, so the cloud can push commands, and its overhead per message is small. HTTP is simpler for devices that report rarely and never receive commands.

Which QoS level should I use? QoS 1 for most telemetry and commands, with consumers that tolerate duplicates. QoS 0 for high-frequency readings you can afford to lose. QoS 2 only where duplicates cannot be handled downstream.

Do I need Kafka if I already have an MQTT broker? Not always. The broker routes messages to connected subscribers; it is not a long-term log you can replay. Add a stream platform when several consumers need the same data, or when you need to reprocess history.

How do devices get their certificates? At manufacturing or at first boot through a provisioning service, each with its own key pair. Keep the private key in secure hardware where the device has it.

Should rules run at the edge or in the cloud? Rules that must work during an outage, such as a local alarm for a door left open, run on the gateway. Rules that need data from many sites run in the cloud.

Start free — one seat, no credit card.