Add local-first race hub API

documentations/refactor/13-phase-5-react-race-hub.md

@@ -0,0 +1,103 @@
+# Phase 5 React Race Hub
+
+## Purpose
+
+Phase 5 begins the production Web UI. The backend now has the foundation needed
+for a local-first Race Hub: live timing is shared, a domain store exists,
+ingestion can populate it, and `/api/v1/race-hub` can read from local data with
+dataset metadata.
+
+This is the point to switch from Cursor to Claude for frontend/UI work.
+
+## Manager Decision
+
+Start with a focused React Race Hub slice, not a full app rewrite. The goal is
+to prove the chosen frontend stack, visual language, responsive layout, and API
+contract against the new local-first backend.
+
+Keep the old Web UI available until the React route is credible.
+
+## Scope
+
+Add a Vite + React + TypeScript frontend foundation and build a first Race Hub
+route around:
+
+- meeting/session header;
+- dataset/source status strip;
+- classification table;
+- starting grid table;
+- driver/team color treatment;
+- missing dataset states;
+- compact Race Hub navigation shell;
+- responsive desktop, tablet, and phone layouts.
+
+Use `/api/v1/race-hub?session_key=...` as the primary API.
+
+## Stack Defaults
+
+- Vite
+- React
+- TypeScript
+- TanStack Query
+- TanStack Router, unless integration cost argues for React Router
+- D3 only for bespoke charts later; do not use it for basic layout tables
+- Vitest for component/unit tests
+- Playwright for at least one smoke path if practical
+
+## Visual Direction
+
+Follow the existing mockups in `documentations/refactor/screens/`, but treat
+them as direction, not rigid specs.
+
+The UI should feel like an F1 operations room:
+
+- dense but readable;
+- technical, not generic SaaS;
+- restrained use of panels;
+- no card sludge;
+- no decorative gradient blobs;
+- strong timing-table ergonomics;
+- team colors used as data, not wallpaper;
+- mobile views designed directly, not merely squeezed desktop.
+
+## Integration Policy
+
+Do not rip out the existing static Web UI on day one. Add the React app in a way
+that can coexist while the route is built and tested.
+
+Acceptable approaches:
+
+- add a Vite app under a dedicated frontend directory and document the dev flow;
+- serve built assets from Go only after the React slice is stable;
+- expose a `/react` or equivalent route temporarily if needed.
+
+The implementation should avoid large backend changes except for tiny API
+contract fixes discovered while integrating.
+
+## Non-Goals
+
+Do not include these in Phase 5:
+
+- full replacement of every existing Web screen;
+- live timing React rewrite;
+- ingest UI;
+- settings UI;
+- full season/calendar rebuild;
+- new backend ingestion features;
+- persistence of live SignalR events.
+
+## Acceptance Criteria
+
+Phase 5 is complete when:
+
+- the React app can run locally;
+- a Race Hub screen loads from `/api/v1/race-hub`;
+- available and missing datasets are visibly distinct;
+- the layout is usable on desktop and phone widths;
+- tests or smoke checks cover the Race Hub happy path;
+- the old Web UI still works.
+
+## Next Phase After This
+
+Phase 6 should expand the React app around the Race Hub: strategy chart,
+position evolution, lap comparison, and richer Data Library/status workflows.