box-box/documentations/refactor/README.md

box-box Refactor Brief

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.
• Cursor Phase 7 Prompt: current handoff prompt for the next Cursor backend phase.

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.