mirror of
https://github.com/AmanTahiliani/box-box.git
synced 2026-08-07 11:54:59 -04:00
Add weekend ingestion orchestration
This commit is contained in:
40
documentations/refactor/20-phase-12-data-library-ui.md
Normal file
40
documentations/refactor/20-phase-12-data-library-ui.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Phase 12 Data Library UI
|
||||
|
||||
## Purpose
|
||||
|
||||
The app can now ingest full weekends and browse local seasons, meetings, and
|
||||
sessions. Phase 12 should make local data health visible in the Web UI so users
|
||||
can understand what is stored, what is partial, and what command to run next.
|
||||
|
||||
This is a frontend slice. Keep it practical and built on the APIs already
|
||||
available.
|
||||
|
||||
## Scope
|
||||
|
||||
Add a Data Library style surface that shows:
|
||||
|
||||
- local seasons and meetings;
|
||||
- sessions per meeting;
|
||||
- dataset coverage per session;
|
||||
- clear empty states;
|
||||
- suggested CLI commands for ingestion/backfill.
|
||||
|
||||
This can be a new route or a tab/section reachable from the existing Race Hub
|
||||
shell, depending on the current router structure.
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Do not fetch OpenF1 from React.
|
||||
- Do not trigger ingestion from the browser.
|
||||
- Keep Race Hub direct links working.
|
||||
- Reuse existing local navigation APIs unless a small backend gap is genuinely
|
||||
blocking.
|
||||
- Keep styling dense, operational, and restrained.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- User can inspect local data coverage without opening a specific session.
|
||||
- Partial weekends/sessions are visibly distinct from complete ones.
|
||||
- Empty database state explains the relevant CLI command.
|
||||
- Existing Race Hub navigation continues to work.
|
||||
- Frontend tests/build/e2e pass.
|
||||
@@ -73,8 +73,10 @@ not implementation tickets yet.
|
||||
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.
|
||||
- [Cursor Phase 11 Prompt](cursor-phase-11-weekend-ingestion-prompt.md):
|
||||
current handoff prompt for the next backend phase.
|
||||
- [20 Phase 12 Data Library UI](20-phase-12-data-library-ui.md): frontend slice
|
||||
for showing local ingestion coverage and next CLI actions.
|
||||
- [Cursor Phase 12 Prompt](cursor-phase-12-data-library-ui-prompt.md): current
|
||||
handoff prompt for the next frontend phase.
|
||||
|
||||
## External References
|
||||
|
||||
|
||||
@@ -1,78 +0,0 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,71 @@
|
||||
# Prompt For Cursor: Phase 12 Data Library UI
|
||||
|
||||
You are working in the `box-box` repository on Phase 12. Build a practical Web
|
||||
UI surface for inspecting local data coverage and ingestion status.
|
||||
|
||||
## Read First
|
||||
|
||||
Open these files first:
|
||||
|
||||
- `documentations/refactor/20-phase-12-data-library-ui.md`
|
||||
- `frontend/src/components/LocalDataNavigator.tsx`
|
||||
- `frontend/src/pages/RaceHubPage.tsx`
|
||||
- `frontend/src/api.ts`
|
||||
- `frontend/src/types.ts`
|
||||
- `frontend/src/main.tsx`
|
||||
- `frontend/src/styles/app.css`
|
||||
- `tests/race-hub.spec.ts`
|
||||
|
||||
Only open older docs if you are blocked.
|
||||
|
||||
## Goal
|
||||
|
||||
Let a user inspect what is in the local database and understand what is missing
|
||||
without needing to open every Race Hub session manually.
|
||||
|
||||
## APIs Available
|
||||
|
||||
- `GET /api/v1/seasons`
|
||||
- `GET /api/v1/meetings?year=<year>&source=local`
|
||||
- `GET /api/v1/weekend?meeting_key=<key>`
|
||||
- `GET /api/v1/race-hub?session_key=<key>`
|
||||
|
||||
Do not fetch OpenF1 from React.
|
||||
|
||||
## Work To Do
|
||||
|
||||
1. Add a Data Library route or reachable section in the React app.
|
||||
2. Show local years/meetings/sessions and dataset coverage.
|
||||
3. Make partial vs complete sessions visually clear.
|
||||
4. Include copyable/reference CLI commands, such as:
|
||||
- `box-box --ingest-year 2025`
|
||||
- `box-box --ingest-meeting <meeting_key>`
|
||||
- `box-box --ingest-session <session_key>`
|
||||
5. Preserve direct Race Hub navigation.
|
||||
6. Add focused frontend tests and update e2e if stable.
|
||||
|
||||
## Design Notes
|
||||
|
||||
- Keep it operational and table-like.
|
||||
- Avoid decorative cards and generic dashboard clutter.
|
||||
- Use the existing dataset/status visual language where possible.
|
||||
- Mobile should remain usable.
|
||||
|
||||
## Verification
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd frontend && npm test -- --run
|
||||
cd frontend && npm run build
|
||||
npm run test:e2e
|
||||
```
|
||||
|
||||
## Report Back
|
||||
|
||||
Summarize:
|
||||
|
||||
- files changed;
|
||||
- Data Library behavior added;
|
||||
- tests run and results;
|
||||
- follow-up API or design gaps.
|
||||
Reference in New Issue
Block a user