mirror of
https://github.com/AmanTahiliani/box-box.git
synced 2026-08-07 19:56:18 -04:00
Add analytics data foundation
This commit is contained in:
65
documentations/refactor/16-phase-8-analytics-visuals.md
Normal file
65
documentations/refactor/16-phase-8-analytics-visuals.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# Phase 8 Analytics Visuals
|
||||
|
||||
## Purpose
|
||||
|
||||
Phase 7 added the backend data foundation for Race Hub analytics: stints, pit
|
||||
stops, positions, race control, weather, and laps now flow through the local
|
||||
SQLite store, ingestion, query layer, and `/api/v1/race-hub`.
|
||||
|
||||
Phase 8 returns to frontend work. The goal is to replace the Strategy and
|
||||
Position placeholder states with useful, production-minded views that consume
|
||||
the real local-first analytics arrays now present in the Race Hub payload.
|
||||
|
||||
## Scope
|
||||
|
||||
Build the first real analytics views for:
|
||||
|
||||
- race strategy from stints and pit stops;
|
||||
- position evolution from position samples;
|
||||
- lightweight supporting context from race control, weather, and laps where it
|
||||
improves the view without making the screen noisy.
|
||||
|
||||
The work should stay inside the React Race Hub surface. Do not redesign the
|
||||
whole application shell in this phase.
|
||||
|
||||
## Frontend Work
|
||||
|
||||
Expected changes:
|
||||
|
||||
- pass `stints`, `pit_stops`, `positions`, `race_control`, `weather`, and `laps`
|
||||
into the relevant Race Hub components;
|
||||
- replace "chart not yet implemented" placeholders with real visual treatment;
|
||||
- preserve honest missing-data states for sessions that only have core datasets;
|
||||
- keep the design dense, technical, and F1-native;
|
||||
- add focused component/unit tests for available and missing analytics data;
|
||||
- update Playwright coverage so seeded analytics views prove the real data path
|
||||
works.
|
||||
|
||||
## Visual Direction
|
||||
|
||||
Prefer timing-wall clarity over dashboard decoration:
|
||||
|
||||
- stint bars should be compact and scan-friendly;
|
||||
- team colors should identify drivers without overpowering compound colors;
|
||||
- compound colors should be disciplined and legible;
|
||||
- position evolution should make gain/loss and driver comparison obvious;
|
||||
- avoid decorative cards, giant empty panels, vague gradients, and generic SaaS
|
||||
chart chrome.
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Do not fetch OpenF1 directly from React.
|
||||
- Do not add a heavy charting library unless the local interaction genuinely
|
||||
needs it; SVG/CSS is enough for this first slice.
|
||||
- Do not hide missing datasets behind fake mock data in runtime views.
|
||||
- Keep mobile and iPad layouts usable, not just desktop-polished.
|
||||
- Keep backend changes out of scope unless a clear API bug is discovered.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Strategy tab renders real stint/pit information when analytics data exists.
|
||||
- Position tab renders real position information when position samples exist.
|
||||
- Missing-data sessions still show clear unavailable states.
|
||||
- Existing Race Hub views keep working.
|
||||
- Frontend tests and build pass.
|
||||
- Playwright Race Hub e2e passes against the seeded local database.
|
||||
@@ -63,8 +63,11 @@ not implementation tickets yet.
|
||||
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.
|
||||
- [Cursor Phase 7 Prompt](cursor-phase-7-analytics-data-foundation-prompt.md):
|
||||
current handoff prompt for the next Cursor backend phase.
|
||||
- [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.
|
||||
- [Claude Phase 8 Prompt](claude-phase-8-analytics-visuals-prompt.md): current
|
||||
handoff prompt for the next Claude frontend phase.
|
||||
|
||||
## External References
|
||||
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
# Prompt For Claude: Phase 8 Analytics Visuals
|
||||
|
||||
You are working in the `box-box` repository as the frontend/UI engineer for
|
||||
Phase 8. The backend data foundation is now in place. Your task is to turn the
|
||||
Race Hub Strategy and Position tabs from placeholders into real, useful
|
||||
frontend views powered by `/api/v1/race-hub`.
|
||||
|
||||
## Context
|
||||
|
||||
Read these docs first:
|
||||
|
||||
- `documentations/refactor/README.md`
|
||||
- `documentations/refactor/14-phase-6-react-race-hub-analytics.md`
|
||||
- `documentations/refactor/15-phase-7-analytics-data-foundation.md`
|
||||
- `documentations/refactor/16-phase-8-analytics-visuals.md`
|
||||
- `documentations/refactor/06-visual-design-direction.md`
|
||||
|
||||
The current React app lives in `frontend/`. The backend Race Hub payload now
|
||||
includes:
|
||||
|
||||
- `stints`
|
||||
- `pit_stops`
|
||||
- `positions`
|
||||
- `race_control`
|
||||
- `weather`
|
||||
- `laps`
|
||||
- dataset metadata under `datasets`
|
||||
|
||||
There is also a deterministic Playwright seed at
|
||||
`scripts/seed-e2e-db/main.go` and e2e coverage in `tests/race-hub.spec.ts`.
|
||||
|
||||
## Objective
|
||||
|
||||
Replace the "chart not yet implemented" states in:
|
||||
|
||||
- `frontend/src/components/StrategyView.tsx`
|
||||
- `frontend/src/components/PositionEvolutionView.tsx`
|
||||
|
||||
with real views that consume the analytics arrays from the Race Hub response.
|
||||
|
||||
## Product Expectations
|
||||
|
||||
Strategy should show, at minimum:
|
||||
|
||||
- per-driver stint bars;
|
||||
- compound labels/colors;
|
||||
- lap ranges;
|
||||
- pit stop markers or nearby pit stop context;
|
||||
- a compact fallback table if the viewport is narrow.
|
||||
|
||||
Position Evolution should show, at minimum:
|
||||
|
||||
- per-driver position progression from position samples;
|
||||
- grid-to-finish context when results and grid are present;
|
||||
- clear gain/loss language;
|
||||
- enough labeling that the view is understandable without a legend-heavy mess.
|
||||
|
||||
Use SVG/CSS for the first implementation unless you have a strong reason to add
|
||||
a charting library. This phase is about a high-quality first native view, not a
|
||||
large dependency decision.
|
||||
|
||||
## Design Direction
|
||||
|
||||
Keep it F1-native and operational:
|
||||
|
||||
- dense but readable;
|
||||
- restrained surfaces;
|
||||
- strong typographic hierarchy;
|
||||
- team color as identity, compound color as data;
|
||||
- no decorative gradient blobs;
|
||||
- no generic SaaS dashboard cards everywhere;
|
||||
- no fake runtime mock data.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- Update `RaceHubPage.tsx` to pass the new arrays into the components.
|
||||
- Use the existing `frontend/src/types.ts` contracts.
|
||||
- Preserve missing-data states for session `9000` in the e2e seed.
|
||||
- Update component tests or add new tests where the logic deserves coverage.
|
||||
- Update Playwright tests so they assert real analytics UI for seeded session
|
||||
`9472`, not placeholder text.
|
||||
- If you discover a backend contract issue, document it clearly instead of
|
||||
silently working around it in the UI.
|
||||
|
||||
## Verification
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
npm test -- --run
|
||||
npm run build
|
||||
cd .. && npm run test:e2e
|
||||
```
|
||||
|
||||
The e2e command starts a seeded local database and local web/API servers. It
|
||||
should not require OpenF1 network access.
|
||||
|
||||
## Deliverable
|
||||
|
||||
Implement the Phase 8 frontend slice and report:
|
||||
|
||||
- files changed;
|
||||
- key UI behavior added;
|
||||
- tests run and results;
|
||||
- any follow-up risks or design refinements you recommend.
|
||||
@@ -1,72 +0,0 @@
|
||||
# Cursor Prompt: Phase 7 Analytics Data Foundation
|
||||
|
||||
You are working in the `box-box` repository.
|
||||
|
||||
Phase 6 added React Race Hub analytics tabs, but Strategy and Position Evolution
|
||||
still show honest missing states because the backend does not expose stints or
|
||||
position samples in `/api/v1/race-hub`.
|
||||
|
||||
Your task is Phase 7: expand the local-first backend data foundation for Race
|
||||
Hub analytics.
|
||||
|
||||
## Read First
|
||||
|
||||
- `CLAUDE.md`
|
||||
- `documentations/refactor/15-phase-7-analytics-data-foundation.md`
|
||||
- `internal/store/*`
|
||||
- `internal/ingest/*`
|
||||
- `internal/query/racehub.go`
|
||||
- `internal/api/openf1.go`
|
||||
- `internal/models/types.go`
|
||||
- `frontend/src/components/StrategyView.tsx`
|
||||
- `frontend/src/components/PositionEvolutionView.tsx`
|
||||
|
||||
## Goal
|
||||
|
||||
Add backend support for the datasets needed by strategy and position views,
|
||||
prioritizing stints and positions.
|
||||
|
||||
## Required Work
|
||||
|
||||
1. Add a new SQLite migration for selected analytics tables.
|
||||
2. Add store structs, upserts, and reads.
|
||||
3. Extend session ingestion to fetch and store:
|
||||
- stints;
|
||||
- pit stops if straightforward;
|
||||
- positions if volume is acceptable;
|
||||
- race control and weather if scoped cleanly.
|
||||
4. Store raw payloads for every fetched endpoint.
|
||||
5. Extend `internal/query.RaceHub` with available analytics datasets.
|
||||
6. Update dataset metadata counts.
|
||||
7. Add offline tests with fake OpenF1 source data.
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Do not fake frontend data.
|
||||
- Do not fetch OpenF1 from React.
|
||||
- Do not add high-volume car telemetry.
|
||||
- Keep migrations idempotent.
|
||||
- Keep existing Phase 5/6 React behavior working.
|
||||
|
||||
## Verification
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
go test ./internal/store/... ./internal/ingest/... ./internal/query/... ./internal/web/...
|
||||
go build -o /tmp/box-box ./cmd/main.go
|
||||
cd frontend && npm test -- --run && npm run build
|
||||
```
|
||||
|
||||
If `go test ./...` fails only on OpenF1 network integration tests, report it as
|
||||
unrelated.
|
||||
|
||||
## Final Response
|
||||
|
||||
Report:
|
||||
|
||||
- tables added;
|
||||
- datasets ingested;
|
||||
- Race Hub API fields added;
|
||||
- tests/builds run;
|
||||
- whether frontend Strategy/Position tabs now have real data available.
|
||||
Reference in New Issue
Block a user