# box-box Refactor Brief ## Operator guide For day-to-day build, run, ingest, test, and Web route commands, use the top-level [README.md](../../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](01-data-sources.md): current and candidate data sources, source authority, limitations, and open questions. - [02 Backend Architecture](02-backend-architecture.md): proposed backend packages, local-first reads, ingestion policy, and live bridge boundaries. - [03 Database Design](03-database-design.md): target SQLite strategy, raw payload storage, normalized tables, provenance, and research questions. - [04 Web UI Product](04-web-ui-product.md): screen architecture, navigation, responsive behavior, and product priorities. - [05 Frontend Stack](05-frontend-stack.md): React stack choice and supporting libraries. - [06 Visual Design Direction](06-visual-design-direction.md): F1-native visual principles and anti-patterns to avoid. - [07 Research Agents Brief](07-research-agents-brief.md): research tracks for dedicated agents before ticket planning. - [08 V1 Scope and Phasing](08-v1-scope-and-phasing.md): first shippable milestone, non-goals, phase order, and early implementation sequence. - [09 Phase 1 Live Extraction](09-phase-1-live-extraction.md): first coding slice, package boundaries, tests, acceptance criteria, and non-goals. - [10 Phase 2 Store Foundation](10-phase-2-store-foundation.md): second coding slice for introducing the local SQLite domain store without changing product behavior. - [11 Phase 3 Ingestion Foundation](11-phase-3-ingestion-foundation.md): third coding slice for OpenF1-to-store ingestion orchestration. - [12 Phase 4 Local-First Web API](12-phase-4-local-first-web-api.md): fourth coding slice for store-backed Race Hub read models and Web API metadata. - [13 Phase 5 React Race Hub](13-phase-5-react-race-hub.md): first frontend implementation slice for the production Web UI. - [14 Phase 6 React Race Hub Analytics](14-phase-6-react-race-hub-analytics.md): next frontend slice for strategy, position, and richer Race Hub views. - [15 Phase 7 Analytics Data Foundation](15-phase-7-analytics-data-foundation.md): backend slice for laps, stints, pits, race control, weather, and positions. - [16 Phase 8 Analytics Visuals](16-phase-8-analytics-visuals.md): frontend slice for turning the newly available analytics datasets into useful Race Hub views. - [17 Phase 9 Navigation Data API](17-phase-9-navigation-data-api.md): backend slice for local-first season/weekend/session navigation so users do not need raw session keys. - [18 Phase 10 Navigation UI](18-phase-10-navigation-ui.md): frontend slice for adding local-first season/weekend navigation around Race Hub. - [19 Phase 11 Weekend Ingestion](19-phase-11-weekend-ingestion.md): backend slice for making one command ingest a whole race weekend into the local DB. - [20 Phase 12 Data Library UI](20-phase-12-data-library-ui.md): frontend slice for showing local ingestion coverage and next CLI actions. - [21 MVP Completion Checklist](21-mvp-completion-checklist.md): current implementation status, verification commands, and remaining post-MVP work. - [22 Phase 14 Visual Regression](22-phase-14-visual-regression.md): Playwright screenshot coverage for MVP routes and responsive viewports. - [23 Phase 15 Command Center](23-phase-15-command-center.md): default Web entry screen for local coverage, weekend focus, live status, and next actions. - [24 Phase 16 Live Timing Polish](24-phase-16-live-timing-polish.md): denser React live timing layout, status treatment, and race-control polish. - [25 Phase 18 Fan Command Center](25-phase-18-fan-command-center.md): reworks `/` around race-weekend identity and splits ingestion/admin concerns into the new `/admin` (Data Health) route. - [26 Phase 19 Weekend Workspace](26-phase-19-weekend-workspace.md): rebuilds `/race-hub` as a session-card-rail workspace with Overview / Race Story / Strategy / Lap Data / Conditions / Race Control / Data Status tabs, an inline weekend switcher, and GP-accent identity treatment. - [27 Phase 19B Paddock Briefing RSS](27-phase-19b-paddock-briefing-rss.md): backend spike for publisher-owned RSS/Atom feeds, local SQLite caching, and a future fan-facing briefing API. - [29 Phase 20 Paddock Briefing Ingestion](29-phase-20-paddock-briefing-ingestion.md): backend CLI slice for refreshing RSS/Atom feeds into the local news cache. ## 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.