wdmUI/decisions/0003-mqtt-como-espina-dorsal.md

ADR-0003 · MQTT as the spine of the system

Status: accepted Date: 2026-05

Context

The platform has many independent processes that need to communicate: cameras → Frigate → enrichers → forensic engine → console → hub. Options considered:

• REST APIs everywhere: tight coupling, polling overhead, hard to add subscribers.
• gRPC streams: better but still point-to-point, no topic-based filtering.
• Kafka: too heavy for edge devices, requires Zookeeper or KRaft, persistent disk-heavy.
• NATS: lightweight but newer, less ecosystem maturity.
• MQTT: mature, lightweight, broker available everywhere (Mosquitto), topic-based, retain messages, QoS levels, well-known TLS bridge mechanics.

Decision

MQTT is the spine of the system. Mosquitto runs on the router as the local broker. Bridges to the hub are configured selectively, with topic remapping. Components communicate via MQTT topics with a documented contract (see docs/01-architecture/mqtt-contract.md).

Key topics:

hai/<cam_id>/events/<type>      # detection events
hai/<cam_id>/state/<key>        # retained state (online, fps)
hai/<cam_id>/snapshots/<n>      # frame snapshots — NEVER bridged
hai/<cam_id>/telemetry/<key>    # raw telemetry — NEVER bridged
hai/_registry/announce          # service discovery
hai/_registry/heartbeat/<id>    # liveness
hai/healthd/health              # selftest reports
hai/_bridge/status              # bridge health (retained)
_cmd/<command>                  # commands incoming from hub

Sovereignty principle: snapshots and raw telemetry never bridge. Aggregated health does. Events do (with site prefix). The bridge.conf policy is in GitOps and visible in the UI.

Consequences

Good:

• Adding a new subscriber is free (no config changes upstream).
• Selective bridging gives operational sovereignty as a programmable property.
• mosquitto_sub is a superb debugging tool always available.
• Retained messages handle late-joining subscribers correctly.

Bad / trade-offs:

• MQTT 5 has features we want (response topics, message expiry) but Mosquitto's MQTT5 support is partial — we stay on MQTT 3.1.1 for compatibility.
• No native request-response semantics — we use req-id correlation in payloads where needed.
• Encryption at rest of the broker DB is not transparent — addressed via LUKS at the OS layer.

Alternatives considered

See above. Kafka was the strongest alternative; rejected primarily for edge-device cost and operational complexity.