Add local-first refactor foundation

documentations/refactor/07-research-agents-brief.md

@@ -0,0 +1,206 @@
+# Research Agents Brief
+
+## Summary
+
+Before implementation tickets are written, dedicated research agents should
+investigate the uncertain parts of the refactor. Their outputs should feed a
+product/architecture planning pass that turns findings into phased work.
+
+Each research track should separate confirmed facts, assumptions, risks, and
+recommendations.
+
+## 1. OpenF1 Contract Research
+
+Objective:
+
+- Document the exact OpenF1 endpoint contract needed by `box-box`.
+
+Inputs:
+
+- Existing `internal/api` client.
+- OpenF1 docs: https://openf1.org/docs/
+- Current app screens and planned Race Hub requirements.
+
+Outputs:
+
+- Endpoint inventory.
+- Field/schema notes.
+- Update cadence by endpoint.
+- Auth/free-tier behavior.
+- Rate-limit and lockout notes.
+- Essential vs optional datasets for v1.
+
+Key questions:
+
+- Which endpoints are immutable after session completion?
+- Which endpoints are high-volume enough to require explicit ingestion?
+- What errors are returned during live-session lockout?
+- Which endpoints can be filtered to reduce ingestion cost?
+
+## 2. Official F1 Live Timing Research
+
+Objective:
+
+- Document the SignalR live feed contract and parser risks.
+
+Inputs:
+
+- Current `internal/ui/official_live.go`.
+- SignalR endpoint: https://livetiming.formula1.com/signalr
+- OpenF1.Data package notes:
+  https://www.nuget.org/packages/OpenF1.Data/1.0.87
+
+Outputs:
+
+- Topic inventory.
+- Payload examples where available.
+- Parser fragility notes.
+- Recommended domain event/state model.
+- Testing strategy for non-live periods.
+
+Key questions:
+
+- Are current subscribed topics sufficient for the planned Web live mode?
+- Which topics should be parsed as events vs current state?
+- How should disconnections and reconnections be represented?
+- Should live snapshots/events be persisted?
+
+## 3. Static Archive Feasibility Research
+
+Objective:
+
+- Determine whether official F1 static archived timing files should become a
+  supported source.
+
+Inputs:
+
+- LiveF1 data topic reference:
+  https://livef1.goktugocal.com/livetimingf1/data_topics.html
+- Public static archive URL patterns.
+- OpenF1 meeting/session metadata.
+
+Outputs:
+
+- Feasibility assessment.
+- Session path mapping strategy.
+- Available years/session types.
+- Topic/file inventory.
+- Risks and legal/operational considerations.
+
+Key questions:
+
+- Can OpenF1 sessions be mapped reliably to static archive paths?
+- Are static archive files available consistently?
+- Which files provide replay-quality timing?
+- Is this source stable enough for v1 or later only?
+
+## 4. SQLite Schema And Indexing Design
+
+Objective:
+
+- Turn the domain database design into a concrete schema proposal.
+
+Inputs:
+
+- `03-database-design.md`.
+- Existing `internal/models/types.go`.
+- Race Hub and Live Replay query requirements.
+
+Outputs:
+
+- Table definitions.
+- Primary keys and foreign keys.
+- Index proposal.
+- Raw payload strategy.
+- Migration strategy.
+- High-volume data retention recommendations.
+
+Design questions:
+
+- Which tables need composite primary keys?
+- Which read paths need covering indexes?
+- Should telemetry/location be optional datasets?
+- Should derived read-model tables exist in v1?
+
+## 5. Backend API And Read-Model Design
+
+Objective:
+
+- Design the Web API shape that React will consume.
+
+Inputs:
+
+- Existing `internal/web/api.go`.
+- Planned Web screens.
+- Store/query requirements.
+
+Outputs:
+
+- Endpoint proposal.
+- Response envelope proposal.
+- Source/staleness metadata shape.
+- Error/partial-data behavior.
+- Migration strategy from existing endpoints.
+
+Design questions:
+
+- Should existing `/api/v1` routes be preserved and expanded?
+- What metadata should every response include?
+- How should partial data be represented?
+- Which read models should be backend-computed vs frontend-computed?
+
+## 6. F1-Native Visual System Research
+
+Objective:
+
+- Produce visual principles and examples for the React UI before components are
+  built.
+
+Inputs:
+
+- `06-visual-design-direction.md`.
+- F1 broadcast timing graphics.
+- FIA timing/result sheets.
+- Motorsport telemetry and timing tools.
+
+Outputs:
+
+- Moodboard or written reference guide.
+- Layout principles.
+- Typography and density guidance.
+- Color usage rules.
+- Anti-pattern list.
+
+Key questions:
+
+- How should the app look F1-native without copying official branding?
+- What visual hierarchy makes live timing fastest to scan?
+- How should phone/iPad layouts differ from desktop?
+- How can the UI avoid generic card-heavy dashboard design?
+
+## 7. Testing Strategy Research
+
+Objective:
+
+- Define a test strategy for backend, ingestion, frontend, and live behavior.
+
+Inputs:
+
+- Existing tests.
+- Planned store/ingestion architecture.
+- Live feed limitations outside active sessions.
+
+Outputs:
+
+- Backend unit/integration test plan.
+- Ingestion fixture strategy.
+- Frontend Vitest and Playwright strategy.
+- Mock SSE/live fixture plan.
+- Manual acceptance checklist.
+
+Key questions:
+
+- How should live SignalR behavior be tested without an active session?
+- What source payload fixtures are needed?
+- Which scenarios require real OpenF1 integration tests?
+- How should local DB migrations be tested?