Skip to main content

ADR 007: Embedded MQTT Broker Decision

Status​

Rejected

Context​

With MQTT commands implementation planned, we evaluated whether to bundle an embedded MQTT broker (Aedes) in the Electron app to simplify user setup.

Problem​

Users need an MQTT broker to:

  1. Receive status updates from Teams
  2. Send action commands to Teams

Without a broker, users must:

  • Install mosquitto: sudo apt-get install mosquitto
  • Configure and start the service
  • Understand MQTT concepts

Proposed Solution​

Bundle Aedes (JavaScript MQTT broker) in the Electron app:

  • Auto-starts when app launches
  • Listens on localhost:1883
  • Zero configuration needed
  • Bundle size: +230 KB
  • Implementation effort: 6-8 hours

Decision​

Do NOT bundle an embedded MQTT broker.

Rationale​

1. Doesn't Solve the Real Problem​

Users still need MQTT client tools to send commands:

# Even with embedded broker, users must install:
sudo apt-get install mosquitto-clients

# To run:
mosquitto_pub -h localhost -t teams/command -m '{"action":"toggle-mute"}'

Embedded broker eliminates:

  • Installing mosquitto broker

Embedded broker does NOT eliminate:

  • Installing mosquitto-clients (for mosquitto_pub)
  • Creating wrapper scripts
  • Understanding MQTT topics

Conclusion: Marginal benefit (removes 1 of 3 installation steps)

2. Wrong Architectural Pattern​

Teams should be a client, not a broker.

❌ Wrong: Each Teams instance runs its own broker
    Teams Instance 1 → Aedes broker :1883
    Teams Instance 2 → Aedes broker :1884 (port conflict!)
    Home Assistant → Mosquitto :1883
    → Fragmented ecosystem

✅ Right: Centralized broker, multiple clients
    Mosquitto :1883 (or Home Assistant MQTT add-on)
        ├─ Teams for Linux (client)
        ├─ Home Assistant (client)
        ├─ Node-RED (client)
        └─ IoT devices (clients)
    → Unified ecosystem

Users with home automation already have MQTT brokers. Creating another broker fragments their setup.

3. Implementation Complexity Without Value​

ComponentEmbedded BrokerExternal BrokerHTTP Server
Bundle size+230 KB0 KB0 KB
Implementation6-8 hours0 hours3-4 hours
User dependenciesmosquitto-clientsmosquitto + mosquitto-clientsNone (curl)
Port conflictsYes (need handling)NoRare
MaintenanceUpdate AedesUser managesNone

Cost/benefit: Not favorable

Consequences​

Positive​

  • ✅ Simpler architecture (Teams = client only)
  • ✅ No port conflict handling needed
  • ✅ No Aedes dependency to maintain
  • ✅ Users with existing MQTT get better integration
  • ✅ Saved 6-8 hours implementation effort

Negative​

  • ⚠️ Users without MQTT must install mosquitto
  • ⚠️ Slightly higher barrier to entry for MQTT features

Mitigations​

  • Document easy broker setup (apt-get one-liner for most distros)
  • Recommend Home Assistant MQTT add-on (one-click install)
  • Consider HTTP server as zero-dependency alternative (future)

Alternatives Considered​

Alternative 1: HTTP Command Server (Future)​

For users wanting to send commands without MQTT:

// Serve HTTP endpoint
http://localhost:48765/action/toggle-mute

// User script (no dependencies)
curl -X POST http://localhost:48765/action/toggle-mute

Advantages:

  • ✅ curl is pre-installed
  • ✅ Simpler than MQTT for basic use
  • ✅ Can add web UI later

Status: Consider for future implementation

Alternative 2: Keep MQTT, Document Broker Setup​

For users with home automation:

Document connecting to existing brokers:

  • Home Assistant MQTT add-on
  • Existing mosquitto installation
  • Cloud MQTT providers (for advanced users)

Status: Accepted (current plan)

User Segments​

Segment 1: Home Automation Users (30%)​

  • Already have MQTT broker
  • Want Teams integration with automations
  • Solution: Connect to existing broker (documented)

Segment 2: Command Integration Users (50%)​

  • Want to send commands from external systems
  • Don't have MQTT infrastructure
  • Solution: Install mosquitto (documented) OR HTTP server (future)

Segment 3: Advanced Users (20%)​

  • Can set up whatever they need
  • Solution: Any approach works

References​

Review​

This decision should be reviewed if:

  1. MQTT adoption is very low due to broker installation complexity
  2. Implementation effort for embedded broker drops significantly (new library, etc.)

For now: Proceed with MQTT client only + document broker setup.