/ record.md
record.md
1 # MAGIC DOC: Mission Control Dashboard 2 3 ## Project Intent 4 5 A **learning project** — not a product. The goal is visceral understanding of 6 real-time frontend patterns by building a live asset map that consumes three 7 data transport patterns: polling, WebSocket, and Server-Sent Events. 8 9 ## Tech Stack (confirmed 2026-04-01) 10 11 | Layer | Choice | Why | 12 |------------------|------------------------------|-------------------------------------------------------| 13 | Framework | TanStack Start | File-based routing, server functions, SSR-ready | 14 | State management | XState v5 | Explicit state machines for connection lifecycles | 15 | Mapping | Leaflet + react-leaflet | Mature, open-source, no API key required | 16 | WS server | Node.js + ws (on VPS) | Simulates mission assets, learner controls the server | 17 | SSE | EventSource (browser-native) | MBTA API provides SSE natively | 18 19 ## Decisions Made 20 21 - **TanStack Start over Vite** — server functions let us proxy OpenSky API 22 calls server-side (no CORS, credentials stay off the client). File-based 23 routing matches the single-page dashboard structure. 24 - **XState over useState/useEffect** — connection lifecycle (connecting, 25 connected, reconnecting, error) maps naturally to state machines. 26 `fromPromise` for one-shot polling fetches, `fromCallback` for long-lived 27 WebSocket/SSE subscriptions. No more `setInterval` + `useRef` cleanup bugs. 28 - **Org-mode for docs** — all documentation in `doc/` follows Diataxis 29 framework. Org-mode, not Markdown. 30 - **Radicle issue tracking** — project broken into 32 tracer-bullet issues 31 (see `plans/` directory). Each issue independently implementable in 20-60 min. 32 33 ## PRD and Roadmap 34 35 **PRD:** `plans/mission_control_dashboard.prd.org` 36 37 A formal product requirements document that: 38 - Breaks project into 32 functional requirements 39 - Defines acceptance criteria for each phase 40 - Lists technical stack and prerequisites 41 - Includes timeline (~2 hours total) 42 43 **Roadmap:** `plans/roadmap.org` (Org-mode) + `plans/radicle-issues/` (32 MD files) 44 45 A tracer-bullet breakdown: 46 - Setup (001-004): Project scaffolding 47 - Phase 1: Aircraft polling with OpenSky (005-011) 48 - Phase 2: Mission assets over WebSocket (012-018) 49 - Phase 3: Transit vehicles via SSE (019-024) 50 - Integration (025-027): Combine sources, unify UI, polish 51 - Future (028-032): Enhancements (clustering, filters, history, etc.) 52 53 ## Architecture 54 55 ## Architecture 56 57 ``` 58 ┌─────────────────────────────────────────────────────┐ 59 │ TanStack Start App │ 60 │ │ 61 │ src/routes/__root.tsx ← HTML shell │ 62 │ src/routes/index.tsx ← dashboard route │ 63 │ │ 64 │ src/server/opensky.ts ← createServerFn │ 65 │ (proxies OpenSky API, runs server-side) │ 66 │ │ 67 │ src/machines/ │ 68 │ aircraftPollingMachine.ts ← fromPromise + after │ 69 │ missionWebSocketMachine.ts ← fromCallback │ 70 │ transitSSEMachine.ts ← fromCallback │ 71 │ │ 72 │ src/components/ │ 73 │ Map.tsx ← useMachine × 3 │ 74 │ AircraftMarker.tsx │ 75 │ MissionMarker.tsx │ 76 │ TransitMarker.tsx │ 77 │ AlertsSidebar.tsx │ 78 │ │ 79 │ src/types/ │ 80 │ aircraft.ts │ 81 │ mission.ts │ 82 │ transit.ts │ 83 └─────────────────────────────────────────────────────┘ 84 85 Data flow: 86 OpenSky REST → server function → aircraftPollingMachine → Map 87 VPS WebSocket → missionWebSocketMachine → Map 88 MBTA SSE → transitSSEMachine → Map 89 ``` 90 91 ## Current State 92 93 | Area | Status | 94 |-----------------|------------------------------------------------------| 95 | Documentation | Complete — tutorial, explanation, how-tos, reference | 96 | PRD & Roadmap | ✅ Created — 32 tracer-bullet issues defined | 97 | Plan files | ✅ `plans/` directory with roadmap + Radicle issues | 98 | App scaffolding | Not started | 99 | Phase 1 (poll) | Not started | 100 | Phase 2 (WS) | Not started | 101 | Phase 3 (SSE) | Not started | 102 | WS server | Not started | 103 104 ## Progress Log 105 106 - **2026-04-01** — Created all documentation following Diataxis framework. 107 Updated docs from Vite + useState/useEffect to TanStack Start + XState. 108 Tutorial, 3 how-tos, 1 explanation, 1 reference, 1 index — all org-mode. 109 - **2026-04-02** — Created PRD (`plans/mission_control_dashboard.prd.org`) 110 with 32 requirements and roadmap (`plans/roadmap.org`) with tracer-bullet 111 issues. Breakdown in `plans/radicle-issues/` (32 MD files) for Radicle 112 issue tracking. Progress tracking in `doc/planning/phase_tracking.org`. 113 114 ## Open Questions 115 116 - OpenSky auth: use anonymous access first or set up OAuth from the start? 117 - WS server deployment: which VPS provider? TLS from day one or add later? 118 - MBTA API key: store in `.env` or hardcode for learning simplicity? 119 - **New:** Should PRD use relative or absolute file paths for documentation links?