docs: align hardware and MQTT architecture notes

docs/MQTT_CONTRACT.md

@@ -15,22 +15,26 @@
           ▼                          ▼                          ▼
    ┌──────────────┐         ┌──────────────┐         ┌──────────────┐
    │   ESP32 #1   │         │   ESP32 #2   │         │  Pi Zero 2 W │
-   │  10.60.1.101│       │  10.60.1.102│       │ 10.60.1.56  │
-   │              │         │              │         │              │
-   │ STA→GoPro AP │         │ STA→GoPro AP │         │ Mosquitto    │
-   │ STA→Router   │         │ STA→Router   │         │ Go backend   │
-   └──────┬───────┘         └──────┬───────┘         │ React UI     │
-          │                        │                  └──────────────┘
-          ▼                        ▼
-   ┌──────────────┐         ┌──────────────┐
-   │ GoPro Hero 3 │         │ GoPro Hero 3 │
-   │ AP: 10.5.5.1 │         │ AP: 10.5.5.1 │
-   └──────────────┘         └──────────────┘
+   │  10.60.1.101 │        │  10.60.1.102 │        │ 10.60.1.56  │
+   │ STA→Router   │        │ STA→Router   │        │ Mosquitto    │
+   │ MQTT relay   │        │ MQTT relay   │        │ Go backend   │
+   └──────┬───────┘        └──────┬───────┘        │ React UI     │
+          │ UART                  │ UART             └──────────────┘
+          ▼                       ▼
+   ┌──────────────┐        ┌──────────────┐
+   │ ESP8266 #1   │        │ ESP8266 #2   │
+   │ STA→GoPro AP │        │ STA→GoPro AP │
+   │ HTTP→10.5.5.1│        │ HTTP→10.5.5.1│
+   └──────┬───────┘        └──────┬───────┘
+          ▼                       ▼
+   ┌──────────────┐        ┌──────────────┐
+   │ GoPro Hero 3 │        │ GoPro Hero 3 │
+   └──────────────┘        └──────────────┘
 ```
 
 - **Travel router:** Self-contained, no internet. Gateway `10.60.1.1`. DHCP pool: `10.60.1.100-200`
 - **Pi Zero 2 W:** Static IP `10.60.1.56`. Runs Mosquitto (port 1883), Go backend (port 8080), serves React UI
-- **ESP32s:** DHCP from router. Each has dual STA: one to GoPro AP, one to router
+- **ESP32s:** DHCP from router. Each stays on the travel-router LAN, relays MQTT to/from its paired ESP8266 over UART
 - **User device:** Connects to router, opens `http://10.60.1.56:8080` for dashboard
 
 ## MQTT Broker
@@ -61,7 +65,7 @@ remoterig/
 **Direction:** ESP32 → Hub  
 **QoS:** 1 | **Retain:** true | **Interval:** 30 seconds
 
-Published by the ESP32 every 30s with the latest GoPro status.
+Published by the ESP32 every 30s using the latest GoPro status received from the paired ESP8266 over UART.
 
 ```json
 {
@@ -143,8 +147,9 @@ Commands sent from the dashboard to individual cameras.
 | `stop_recording` | Stop GoPro recording | status (updated on next poll) |
 | `reboot` | Reboot the ESP32 | — (ESP32 reconnects after boot) |
 
-**ESP32 behavior:**
-- On receipt, execute command against GoPro
+**ESP32 / ESP8266 behavior:**
+- ESP32 receives the MQTT command and forwards it over UART to the paired ESP8266
+- ESP8266 executes the corresponding HTTP command against the GoPro AP
 - Next status publish will reflect the new state
 - If command fails (GoPro unreachable), publish status with `online: false`
 
@@ -221,16 +226,17 @@ ESP32 boots
   ├── Publishes announce (retained) on cameras/<id>/announce
   │
   ▼
-  ┌─────────────────────────────────────────┐
-  │  Main loop (every 30s):                 │
-  │  1. HTTP GET GoPro status (10.5.5.1)    │
-  │  2. Parse 60-byte status blob            │
-  │  3. Publish status (retained)            │
-  │  4. Every 60s: publish heartbeat         │
-  └─────────────────────────────────────────┘
+  ┌───────────────────────────────────────────────┐
+  │  Main loop (every 30s):                       │
+  │  1. ESP32 requests/receives status via UART   │
+  │  2. ESP8266 polls GoPro HTTP (10.5.5.1)       │
+  │  3. ESP8266 returns parsed status over UART   │
+  │  4. ESP32 publishes MQTT status (retained)    │
+  │  5. Every 60s: ESP32 publishes heartbeat      │
+  └───────────────────────────────────────────────┘
   │
   ├── On MQTT disconnect → reconnect with 1s/2s/4s/8s/16s/30s backoff
-  ├── On GoPro unreachable → publish status with online: false
+  ├── On ESP8266/GoPro unreachable → publish status with online: false
   ├── On Wi-Fi loss → buffer status locally, replay on reconnect (CUB-230)
   │
   ▼
@@ -243,11 +249,12 @@ ESP32 shutdown / watchdog reboot
 1. User clicks "Start" on dashboard
 2. Browser → HTTP POST /api/v1/cameras/cam-001/start → Go backend
 3. Go backend → MQTT publish remoterig/cameras/cam-001/command {command: "start_recording"}
-4. ESP32 receives command, sends HTTP GET to 10.5.5.1/bacpac/SH?t=<password>&p=%01
-5. GoPro starts recording
-6. Next 30s poll: ESP32 publishes status with recording: true
-7. Go backend receives status, updates SQLite, fans out via SSE
-8. Dashboard updates with pulsing REC indicator
+4. ESP32 receives command and forwards it to ESP8266 over UART
+5. ESP8266 sends HTTP GET to 10.5.5.1/bacpac/SH?t=<password>&p=%01
+6. GoPro starts recording
+7. Next 30s poll: ESP8266 reports status over UART; ESP32 publishes status with recording: true
+8. Go backend receives status, updates SQLite, fans out via SSE
+9. Dashboard updates with pulsing REC indicator
 ```
 
 ## Offline Buffering (future — CUB-230)