mirror of
https://github.com/AmanTahiliani/box-box.git
synced 2026-08-07 11:54:59 -04:00
Add local data navigation UI
This commit is contained in:
40
documentations/refactor/19-phase-11-weekend-ingestion.md
Normal file
40
documentations/refactor/19-phase-11-weekend-ingestion.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Phase 11 Weekend Ingestion
|
||||
|
||||
## Purpose
|
||||
|
||||
Phase 10 made local data navigable in the Web UI, but the app still needs a
|
||||
practical way to populate a complete weekend. Phase 11 should make ingestion
|
||||
work at the same shape users browse: meeting/weekend first, then sessions.
|
||||
|
||||
This is a backend/CLI slice for Cursor.
|
||||
|
||||
## Scope
|
||||
|
||||
Add or refine CLI ingestion so a user can ingest a whole meeting/weekend into
|
||||
the domain database without manually running one command per session.
|
||||
|
||||
The target workflow is:
|
||||
|
||||
- ingest meeting metadata and sessions for a `meeting_key`;
|
||||
- for each session in that meeting, ingest Race Hub datasets;
|
||||
- report per-session success, partial failure, and row counts clearly;
|
||||
- keep raw payload provenance.
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Do not remove single-session ingestion.
|
||||
- Do not fetch data from React.
|
||||
- Do not make failed optional analytics endpoints destroy already-ingested
|
||||
meeting/session metadata.
|
||||
- Keep tests offline with fake sources.
|
||||
- Be careful with live/current sessions; completed historical sessions are the
|
||||
primary target.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- A single CLI path can ingest all sessions for a meeting.
|
||||
- Ingestion summaries make per-session results clear.
|
||||
- Existing `--ingest-session` behavior still works.
|
||||
- Store/query/web/frontend tests still pass.
|
||||
- Add focused ingestion tests for full-weekend orchestration and partial
|
||||
failures where practical.
|
||||
@@ -71,8 +71,10 @@ not implementation tickets yet.
|
||||
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.
|
||||
- [Cursor Phase 10 Prompt](cursor-phase-10-navigation-ui-prompt.md): current
|
||||
handoff prompt for the next frontend phase.
|
||||
- [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.
|
||||
- [Cursor Phase 11 Prompt](cursor-phase-11-weekend-ingestion-prompt.md):
|
||||
current handoff prompt for the next backend phase.
|
||||
|
||||
## External References
|
||||
|
||||
|
||||
@@ -1,83 +0,0 @@
|
||||
# Prompt For Cursor: Phase 10 Navigation UI
|
||||
|
||||
You are working in the `box-box` repository on Phase 10. This is a frontend
|
||||
phase, but keep it pragmatic and low-context: build functional local-first
|
||||
navigation around the existing Race Hub without redesigning the whole app.
|
||||
|
||||
## Read First
|
||||
|
||||
Open these files first:
|
||||
|
||||
- `documentations/refactor/18-phase-10-navigation-ui.md`
|
||||
- `frontend/src/pages/RaceHubPage.tsx`
|
||||
- `frontend/src/api.ts`
|
||||
- `frontend/src/types.ts`
|
||||
- `frontend/src/main.tsx`
|
||||
- `frontend/src/styles.css`
|
||||
- `tests/race-hub.spec.ts`
|
||||
|
||||
Only open older docs if you are blocked.
|
||||
|
||||
## Backend APIs Available
|
||||
|
||||
- `GET /api/v1/seasons`
|
||||
- returns local years, newest first, e.g. `[2025]`.
|
||||
- `GET /api/v1/meetings?year=2025&source=local`
|
||||
- returns locally ingested meetings for the year.
|
||||
- `GET /api/v1/weekend?meeting_key=1229`
|
||||
- returns meeting metadata, sessions, `default_session_key`, and per-session
|
||||
dataset coverage.
|
||||
|
||||
Use `source=local` for meetings so React does not fall back to OpenF1.
|
||||
|
||||
## Goal
|
||||
|
||||
Let users browse local data into Race Hub without knowing a raw `session_key`.
|
||||
|
||||
## Work To Do
|
||||
|
||||
1. Add TypeScript types and API functions for seasons, local meetings, and
|
||||
weekend details.
|
||||
2. Add a simple local data navigator in the React app:
|
||||
- year selector/list;
|
||||
- meetings for selected year;
|
||||
- sessions for selected weekend;
|
||||
- dataset coverage hints.
|
||||
3. Selecting a session should navigate to `/race-hub?session_key=<key>`.
|
||||
4. Keep the current manual session key entry as a fallback.
|
||||
5. Preserve the existing Race Hub tabs and analytics views.
|
||||
6. Add focused tests where practical.
|
||||
7. Update Playwright coverage if a stable seeded navigation path is easy.
|
||||
|
||||
## Design Notes
|
||||
|
||||
- Keep it dense and operational, not a marketing page.
|
||||
- Avoid card-heavy dashboard sludge.
|
||||
- Reuse existing type, spacing, tab, and table conventions where possible.
|
||||
- Mobile should remain usable.
|
||||
|
||||
## Do Not Do
|
||||
|
||||
- Do not fetch OpenF1 from React.
|
||||
- Do not remove direct `session_key` routing.
|
||||
- Do not introduce a new UI framework.
|
||||
- Do not touch backend unless you find a blocking API bug.
|
||||
|
||||
## Verification
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd frontend && npm test -- --run
|
||||
cd frontend && npm run build
|
||||
npm run test:e2e
|
||||
```
|
||||
|
||||
## Report Back
|
||||
|
||||
Summarize:
|
||||
|
||||
- files changed;
|
||||
- navigation behavior added;
|
||||
- tests run and results;
|
||||
- follow-up polish or data needs.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Prompt For Cursor: Phase 11 Weekend Ingestion
|
||||
|
||||
You are working in the `box-box` repository on Phase 11. The Web UI can now
|
||||
browse local years, meetings, and sessions. Your task is to make the CLI able
|
||||
to populate a whole race weekend/meeting in one backend ingestion flow.
|
||||
|
||||
## Read First
|
||||
|
||||
Open these files first:
|
||||
|
||||
- `documentations/refactor/19-phase-11-weekend-ingestion.md`
|
||||
- `cmd/main.go`
|
||||
- `internal/ingest/ingest.go`
|
||||
- `internal/ingest/ingest_test.go`
|
||||
- `internal/ingest/openf1.go`
|
||||
- `internal/store/meetings.go`
|
||||
- `internal/query/navigation.go`
|
||||
|
||||
Only open older docs if you are blocked.
|
||||
|
||||
## Goal
|
||||
|
||||
Make meeting/weekend ingestion useful for the local-first Web UI. A user should
|
||||
be able to ingest a meeting and have all sessions for that meeting populated
|
||||
with Race Hub datasets where available.
|
||||
|
||||
## Current Shape
|
||||
|
||||
The project already has:
|
||||
|
||||
- `--ingest-year`
|
||||
- `--ingest-meeting`
|
||||
- `--ingest-session`
|
||||
- session-level Race Hub ingestion datasets;
|
||||
- local navigation APIs and UI that depend on ingested meeting/session data.
|
||||
|
||||
Confirm the exact current behavior before editing. If `--ingest-meeting`
|
||||
currently only stores meeting/session metadata, extend it or add a clearly named
|
||||
flag. Prefer the least surprising CLI behavior.
|
||||
|
||||
## Work To Do
|
||||
|
||||
1. Add meeting/weekend orchestration that fetches sessions for a meeting and
|
||||
ingests Race Hub datasets for each session.
|
||||
2. Preserve single-session ingestion behavior.
|
||||
3. Return/report per-session summaries clearly.
|
||||
4. Keep raw payload provenance for all fetched endpoints.
|
||||
5. Make partial failures visible without erasing successful session data.
|
||||
6. Add focused offline tests with fake sources.
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Do not fetch OpenF1 from React.
|
||||
- Do not introduce background ingestion from normal page views.
|
||||
- Do not persist high-volume car telemetry in this phase.
|
||||
- Do not break existing e2e seed behavior.
|
||||
- Keep completed historical sessions as the default mental model.
|
||||
|
||||
## Verification
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
go test ./internal/ingest/... ./internal/store/... ./internal/query/... ./internal/web/...
|
||||
go build -o /private/tmp/box-box ./cmd/main.go
|
||||
cd frontend && npm test -- --run
|
||||
cd frontend && npm run build
|
||||
npm run test:e2e
|
||||
```
|
||||
|
||||
## Report Back
|
||||
|
||||
Summarize:
|
||||
|
||||
- files changed;
|
||||
- CLI behavior added or changed;
|
||||
- tests run and results;
|
||||
- follow-up risks, especially around OpenF1 rate limits or partial sessions.
|
||||
Reference in New Issue
Block a user