For day-to-day build, run, ingest, test, and Web route commands, use the top-level README.md. This directory is for architecture, phasing, and research — not the first stop for new contributors.

Purpose

This directory captures the planning baseline for the next major evolution of box-box. The current project has a strong live timing core, especially through the official F1 live feed, but the rest of the app still behaves like an on-demand OpenF1 client. That makes historical and session data unreliable, especially during live-session API lockouts.

The refactor direction is to make the Web UI the primary product surface, make historical data local-first, and preserve the TUI live mode that already works well. These documents are intentionally strategic and research-ready. They are not implementation tickets yet.

Strategic Defaults

Frontend: React + TypeScript, built with Vite.
Backend: Go remains the application and API server.
Storage: SQLite becomes a real local domain database, not only an HTTP cache.
Historical ingestion: OpenF1 REST is the first ingestion/backfill source.
Live timing: official F1 SignalR remains the live source.
Ingestion model: explicit CLI backfill plus opportunistic small web fetches.
TUI: preserve the current live mode; new historical/analytics work focuses on the Web UI first.
Product stance: race-weekend first, local-first, no rushed implementation.
Live persistence: persist live SignalR events/snapshots as a separate append-only stream once the live bridge is extracted; do not merge them into post-session OpenF1 records without a reconciliation design.
Migration: keep the current raw HTTP cache behavior intact while introducing the new domain database incrementally.

Documents

01 Data Sources: current and candidate data sources, source authority, limitations, and open questions.
02 Backend Architecture: proposed backend packages, local-first reads, ingestion policy, and live bridge boundaries.
03 Database Design: target SQLite strategy, raw payload storage, normalized tables, provenance, and research questions.
04 Web UI Product: screen architecture, navigation, responsive behavior, and product priorities.
05 Frontend Stack: React stack choice and supporting libraries.
06 Visual Design Direction: F1-native visual principles and anti-patterns to avoid.
07 Research Agents Brief: research tracks for dedicated agents before ticket planning.
08 V1 Scope and Phasing: first shippable milestone, non-goals, phase order, and early implementation sequence.
09 Phase 1 Live Extraction: first coding slice, package boundaries, tests, acceptance criteria, and non-goals.
10 Phase 2 Store Foundation: second coding slice for introducing the local SQLite domain store without changing product behavior.
11 Phase 3 Ingestion Foundation: third coding slice for OpenF1-to-store ingestion orchestration.
12 Phase 4 Local-First Web API: fourth coding slice for store-backed Race Hub read models and Web API metadata.
13 Phase 5 React Race Hub: first frontend implementation slice for the production Web UI.
14 Phase 6 React Race Hub Analytics: next frontend slice for strategy, position, and richer Race Hub views.
15 Phase 7 Analytics Data Foundation: backend slice for laps, stints, pits, race control, weather, and positions.
16 Phase 8 Analytics Visuals: frontend slice for turning the newly available analytics datasets into useful Race Hub views.
17 Phase 9 Navigation Data API: backend slice for local-first season/weekend/session navigation so users do not need raw session keys.
18 Phase 10 Navigation UI: frontend slice for adding local-first season/weekend navigation around Race Hub.
19 Phase 11 Weekend Ingestion: backend slice for making one command ingest a whole race weekend into the local DB.
20 Phase 12 Data Library UI: frontend slice for showing local ingestion coverage and next CLI actions.
21 MVP Completion Checklist: current implementation status, verification commands, and remaining post-MVP work.
22 Phase 14 Visual Regression: Playwright screenshot coverage for MVP routes and responsive viewports.
23 Phase 15 Command Center: default Web entry screen for local coverage, weekend focus, live status, and next actions.
24 Phase 16 Live Timing Polish: denser React live timing layout, status treatment, and race-control polish.
25 Phase 18 Fan Command Center: reworks / around race-weekend identity and splits ingestion/admin concerns into the new /admin (Data Health) route.
27 Phase 19B Paddock Briefing RSS: backend spike for publisher-owned RSS/Atom feeds, local SQLite caching, and a future fan-facing briefing API.

External References

OpenF1 documentation: https://openf1.org/docs/
Official F1 SignalR endpoint: https://livetiming.formula1.com/signalr
LiveF1 timing topic reference: https://livef1.goktugocal.com/livetimingf1/data_topics.html
OpenF1.Data package notes on F1 SignalR: https://www.nuget.org/packages/OpenF1.Data/1.0.87

Current Repo Context

The existing application already has:

A Go OpenF1 client in internal/api.
A SQLite-backed raw HTTP cache and track outline persistence.
A Bubble Tea TUI in internal/ui.
A Go-served Web UI in internal/web.
A live SignalR bridge extracted into internal/live and reused by both TUI and Web mode through server-sent events.

The refactor should build on that progress instead of replacing it blindly. The goal is to separate source fetching, domain persistence, query/read models, and frontend experience so each layer can be improved without destabilizing the others.