CubeCraft-Creations/remote-rig
11
0
Fork 0
generated from CubeCraft-Creations/Tracehound
Code Issues 9 Pull Requests 1 Actions Packages Projects Releases 1 Wiki Activity

docs: update CONTEXT.md with closed-network architecture and current state
Build (Dev) / build (push) Failing after 1s
Details
CI/CD / lint-and-typecheck (push) Failing after 0s
Details
CI/CD / test (push) Has been skipped
Details
CI/CD / build (push) Has been skipped
Details
CI/CD / deploy (push) Has been skipped
Details

Browse Source 
- Replaced architecture diagram with travel router LAN design
- Added MQTT contract reference
- Updated issue status table with agent assignments
- Revised known limitations to reflect actual gaps
- Added network config section (subnet, static IP)
- Removed CUB-182 (canceled duplicate)

Post-sync: 13 done, 15 backlog, 1 in review, 1 canceled.
This commit is contained in:
Hermes
2026-05-21 21:11:33 +00:00
parent df212796d2
commit ce188086cb
1 changed files with 99 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CONTEXT.md
+99 -57
View File
@@ -1,10 +1,11 @@
# RemoteRig — Project Context
> **Last updated:** 2026-05-21
> **Last updated:** 2026-05-21 (evening — post-planning sync)
> **Repo:** `CubeCraft-Creations/remote-rig` | **Host:** `code.cubecraftcreations.com`
> **Local clone:** `/mnt/ai-storage/projects/remote-rig` | **Default branch:** `dev`
> **Discord:** `DISCORD_DEV_REMOTERIG_CHANNEL_ID`
> **Linear Epic:** [CUB-198](https://linear.app/cubecraft-creations/issue/CUB-198)
> **MQTT Contract:** [docs/MQTT_CONTRACT.md](./docs/MQTT_CONTRACT.md)
---
@@ -33,35 +34,49 @@ RemoteRig is a **multi-camera remote monitoring system**. It provides a camera g
## Architecture
```
ESP32 Node (per camera)
│
├── HTTP POST /api/v1/cameras/:id/status (status push)
│
└── MQTT ──→ Mosquitto Broker ──→ MQTT Subscriber (Go hub)
│
▼
┌──────────────────────────────┐
│ Go Central Hub (Pi Zero 2 W)│
│ ┌────────────────────┐ │
│ │ SQLite Database │ │
│ └────────────────────┘ │
│ ┌────────────────────┐ │
│ │ SSE Hub │ │
│ └────────────────────┘ │
└──────────────────────────────┘
│
SSE /api/v1/events/stream
│
▼
React Dashboard (Browser)
┌──────────────────────────────────────────┐
│ Travel Router (self-contained LAN) │
│ Subnet: 192.168.4.0/24 │
│ DHCP pool: .100-.200 │
└──────┬──────────┬──────────┬──────────────┘
│ │ │
┌───────────────┘ │ └───────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ ESP32 #1 │ │ ESP32 #N │ │ Pi Zero 2 W │
│ DHCP addr │ │ DHCP addr │ │ 192.168.4.10 │
│ │ │ │ │ (static IP) │
│ STA→GoPro AP │ │ STA→GoPro AP │ │ │
│ STA→Router │ │ STA→Router │ │ Mosquitto :1883 │
│ │ │ │ │ Go API :8080 │
│ MQTT→:1883 │ │ MQTT→:1883 │ │ React UI │
└──────┬───────┘ └──────┬───────┘ │ SQLite DB │
│ │ └──────────────────┘
▼ ▼ │
┌──────────────┐ ┌──────────────┐ │
│ GoPro Hero 3 │ │ GoPro Hero 3 │ SSE /api/v1/events/stream
│ AP: 10.5.5.1 │ │ AP: 10.5.5.1 │ │
│ Wi-Fi only │ │ Wi-Fi only │ ▼
└──────────────┘ └──────────────┘ ┌──────────────────┐
│ User Device │
│ (laptop/kiosk) │
│ http://.4.10 │
└──────────────────┘
```
### Key Architecture Decisions
- **SQLite over PostgreSQL:** Single-node deployment on Pi Zero 2 W — no need for separate DB server
- **SSE over WebSocket:** Simpler server-side; unidirectional updates from hub → browser are sufficient
- **MQTT for ESP32 → Hub communication:** Lightweight, designed for IoT/embedded use
- **API key auth:** Simple bearer token middleware; configurable key in `config.yaml`
- **Idempotent migrations:** DB checks if tables exist before running migrations
**Network is fully self-contained — no internet dependency.** The travel router creates the LAN. All devices connect to it. The Pi runs all services (Mosquitto, Go API, React UI, SQLite). ESP32s bridge the GoPro's AP to the LAN via MQTT.
### Key Architecture Decisions (revised)
- **Closed travel router network** — No venue Wi-Fi dependency. User brings their own router. All devices on `192.168.4.0/24`.
- **ESP32 dual-STA** — One STA to GoPro AP (10.5.5.1), one STA to travel router. No channel-hopping concerns on closed network.
- **ESP32 → GoPro over Wi-Fi** — Bacpac I²C route rejected (30-pin Herobus connector too complex). HTTP to GoPro AP is proven and reliable.
- **MQTT for ESP32 → Hub** — Lightweight, designed for IoT. Mosquitto on Pi. QoS 1 for status, QoS 2 for commands. Full contract: [docs/MQTT_CONTRACT.md](./docs/MQTT_CONTRACT.md)
- **SQLite over PostgreSQL** — Single-node Pi Zero 2 W deployment. WAL mode for concurrent read/write.
- **SSE over WebSocket** — Unidirectional hub → browser updates. Simpler, sufficient for status dashboard.
- **Chi router** — Lightweight Go HTTP router with middleware support.
- **Zustand over Redux** — Minimal boilerplate for camera status store.
- **API key auth** — Simple bearer token; closed LAN, not internet-facing.
- **Camera auto-discovery** — ESP32 publishes `announce` message on first MQTT connect. Hub auto-registers by MAC, assigns sequential `cam-NNN` ID.
## Directory Layout
@@ -194,11 +209,14 @@ read_timeout: 5s
write_timeout: 10s
idle_timeout: 120s
mqtt:
broker: "localhost:1883"
broker: "localhost:1883" # Mosquitto on Pi Zero 2 W
client_id: "remoterig-hub"
platform:
type: "pi-zero-2w"
max_cameras: 16
network:
subnet: "192.168.4.0/24" # Travel router subnet
hub_ip: "192.168.4.10" # Pi Zero 2 W static IP
```
## Frontend Component Tree
@@ -233,29 +251,50 @@ Custom theme in `tailwind.config.js`:
## Linear Issue Map
| CUB | Title | Status |
|-----|-------|--------|
| 198 | **Epic: Multi-camera remote monitoring system** | Backlog |
| 178 | UX/UI design: camera monitoring dashboard mockups | Backlog |
| 179 | Logging & persistence strategy | In Review |
| 180 | Risk mitigation checklist | Done |
| 181 | Scaffold Go module, directory layout, config, main.go | Done |
| 182 | Scaffold Go module (dup of 181) | Backlog |
| 183 | SQLite schema migration + DB init | Backlog |
| 184 | API key auth middleware | Backlog |
| 185 | Camera/StatusLog/RecordingEvent Go models | Backlog |
| 186 | GET /api/v1/cameras (list with live status) | Backlog |
| 187 | POST /api/v1/cameras/:id/start + MQTT publish | Done |
| 188 | POST /api/v1/cameras/:id/stop recording | Backlog |
| 189 | POST /api/v1/cameras (register new camera) | Backlog |
| 190 | GET /api/v1/cameras/:id (detail + history) | Backlog |
| 191 | POST /api/v1/cameras/:id/push-status (HTTP ingestion) | Backlog |
| 192 | MQTT subscriber for status ingestion + fan-out | Backlog |
| 193 | SSE /api/v1/events/stream endpoint | Backlog |
| 194 | Scaffold Vite + React + TypeScript + Tailwind project | Done |
| 195 | React SSE hook (useSSE.ts) | In Review |
| 196 | React CameraCard component with status display | Backlog |
| 197 | UX wireframe — main dashboard camera grid | In Review |
**Last synced:** 2026-05-21 (evening)
| CUB | Title | Status | Agent |
|-----|-------|--------|-------|
| 198 | **Epic: Multi-camera remote monitoring system** | Backlog | — |
| 238 | Define MQTT message format contract | ✅ Done | Dex |
| 228 | Add battery_calibration_offset to cameras table | Backlog | Hex |
| 230 | ESP32 offline status buffering and replay | Backlog | Pip |
| 232 | Implement MQTT subscriber in Go hub | Backlog | Dex |
| 229 | Design camera auto-discovery and registration flow | Backlog | Dex |
| 231 | Mosquitto MQTT broker setup on Pi Zero 2 W | Backlog | Dex |
| 233 | Verify and harden SSE endpoint | Backlog | Dex |
| 234 | Verify and harden all camera API endpoints | Backlog | Dex |
| 235 | Implement GET /api/v1/cameras/:id with 24h history | Backlog | Dex |
| 236 | Implement POST /api/v1/cameras registration | Backlog | Dex |
| 237 | Update CONTEXT.md to actual state | Backlog | Otto |
| — | — | — | — |
| 173 | Confirm GoPro Hero 3 Wi‑Fi control API | ✅ Done | Otto |
| 174 | ESP32 firmware baseline | ✅ Done | Pip |
| 175 | Central hub backend (Go service) | ✅ Done | Dex |
| 177 | Database schema (cameras, events, status_logs) | ✅ Done | Hex |
| 180 | Risk mitigation checklist | ✅ Done | — |
| 181 | Scaffold Go module, directory layout, config | ✅ Done | — |
| 187 | POST start recording + MQTT publish | ✅ Done | Dex |
| 194 | Scaffold Vite + React + TypeScript + Tailwind | ✅ Done | — |
| 195 | React SSE hook (useSSE.ts) + Zustand store | ✅ Done | Rex |
| 196 | CameraCard component + 16 unit tests | ✅ Done | Rex |
| 179 | Logging & persistence strategy | ✅ Done | — |
| 208 | Add README with project overview | ✅ Done | Hermes |
| 182 | ~~Duplicate of CUB-181~~ | ❌ Canceled | — |
| — | — | — | — |
| 183 | SQLite schema migration + DB init | Backlog | Hex |
| 184 | API key auth middleware | Backlog | Dex |
| 185 | Camera/StatusLog/RecordingEvent Go models | Backlog | Hex |
| 186 | GET /api/v1/cameras (list with live status) | Backlog | Dex |
| 188 | POST stop recording | Backlog | Dex |
| 189 | POST register new camera | Backlog | Dex |
| 190 | GET camera detail + history | Backlog | Dex |
| 191 | POST push-status (HTTP ingestion) | Backlog | Dex |
| 192 | MQTT subscriber | Backlog | Dex |
| 193 | SSE /api/v1/events/stream endpoint | Backlog | Dex |
| 178 | UX/UI design mockups | Backlog | Sketch |
| 197 | Dashboard camera grid wireframe | In Review | Sketch |
| 176 | Frontend umbrella (React + Tailwind) | Backlog | Rex |
## CI/CD Pipeline
@@ -287,11 +326,14 @@ Triggered by `workflow_dispatch`:
## Known Limitations
- MQTT subscriber implementation is still in Backlog (CUB-192). Currently, only HTTP status push is wired up.
- SSE endpoint implementation is in Backlog (CUB-193) — frontend SSE hook exists but backend SSE hub is placeholder.
- CameraCard component plan exists (`docs/plans/2026-05-21-cub-196-cameracard.md`) but implementation is pending.
- CUB-182 is essentially a duplicate of CUB-181 (both scaffold Go module).
- `remoterig.db` (SQLite DB file) is currently committed to the repo — should be in `.gitignore` for a production config.
- **MQTT subscriber not yet implemented** (CUB-232) — ESP32→hub communication backbone is designed (see [MQTT_CONTRACT.md](./docs/MQTT_CONTRACT.md)) but not built. Currently only HTTP status push is wired up.
- **SSE endpoint needs verification** (CUB-233) — Frontend SSE hook exists (merged PR #2), backend SSE hub code exists (140 lines) but needs heartbeat, reconnection, and integration testing.
- **No camera auto-discovery** (CUB-229) — Cameras must be manually registered. ESP32 announce protocol designed in MQTT contract but not implemented.
- **No battery calibration** (CUB-228) — GoPro Hero 3 reports raw byte; per-camera calibration offset column not yet added to schema.
- **No offline buffering on ESP32** (CUB-230) — If travel router Wi-Fi drops, status data is lost. SPIFFS buffer designed but not implemented.
- **CameraCard wireframe pending** (CUB-197) — Dashboard UI has live code but needs UX review/wireframe sign-off.
- **remoterig.db committed to repo** — Should be in `.gitignore` for production. Low priority (convenient for dev).
- **Time sync TBD** — ESP32s need accurate timestamps without internet. Options: Pi as NTP server, GPS module, or HTTP time endpoint. See MQTT contract open questions.
## Getting Started