From 39c4ba41fd1862cce72d3b370db2cf1dfe8af276 Mon Sep 17 00:00:00 2001
From: Matthias Nott <mnott@mnsoft.org>
Date: Sun, 22 Mar 2026 16:50:48 +0100
Subject: [PATCH] docs: MQTT protocol migration plan as next major task

---
 TODO.md |   32 +++++++++++++++++++++++++++-----
 1 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/TODO.md b/TODO.md
index 305d0b0..e4da381 100644
--- a/TODO.md
+++ b/TODO.md
@@ -2,11 +2,33 @@
 
 ## High Priority
 
-### Message Send Queue (reliability)
-- Queue outgoing messages locally until WebSocket confirms delivery
-- Retry on reconnect — messages sent during disconnection/restart aren't lost
-- Visual indicator on messages: sending → sent (currently fire-and-forget)
-- Daemon restart drops in-flight messages — need client-side persistence
+### MQTT Protocol Migration — NEXT MAJOR TASK
+Replace ad-hoc WebSocket protocol with MQTT for reliable, ordered messaging.
+
+**Why:** Current protocol has no delivery guarantees, no message ordering, no offline queuing.
+Messages get lost on daemon restart, duplicated on catch_up, and arrive out of order.
+
+**Server (AIBroker):**
+- Embed MQTT broker (aedes) in daemon alongside existing WebSocket
+- Topics: `pailot/{sessionId}/out` (server→app), `pailot/{sessionId}/in` (app→server)
+- System topics: `pailot/sessions`, `pailot/status`, `pailot/typing/{sessionId}`
+- QoS 1 (at-least-once) for messages, QoS 0 for typing indicators
+- Retained messages for session list and last screenshot
+- Clean session=false so broker queues messages for offline clients
+- Bridge MQTT messages to/from existing AIBP routing
+
+**Flutter App:**
+- Replace WebSocket client with mqtt_client package
+- Subscribe to `pailot/+/out` for all session messages
+- Publish to `pailot/{sessionId}/in` for user messages
+- Message ID-based dedup (MQTT can deliver duplicates with QoS 1)
+- Ordered by broker — no client-side sorting needed
+- Offline messages delivered automatically on reconnect
+
+**Migration:**
+- Phase 1: Add MQTT alongside WebSocket, dual-publish
+- Phase 2: Flutter app switches to MQTT
+- Phase 3: Remove WebSocket from PAILot gateway
 
 ## Pending Features
 

--
Gitblit v1.3.1