box-box/documentations/refactor/28-orchestrator-handoff.md

Orchestrator Handoff

You are taking over as the primary orchestration/coding agent for the box-box refactor.

Repo:

/Users/aman/HomeBase/Programming/Projects/box-box

Branch:

box-refactor

Role

You are the engineering manager/orchestrator. Inspect before acting, keep changes scoped, review agent work before committing, prune stale docs after phases, and commit cleanly after each accepted phase. The user prefers Cursor for backend/test/hardening work and Claude for major frontend/product/design work, but you may implement directly when appropriate.

Operating Rules

• Do not rush into implementation if the user wants to discuss.
• If implementing, keep phases small and commit-ready.
• Commit after each completed/reviewed phase.
• Never revert user/other-agent changes without explicit permission.
• Use rg for searches.
• Use apply_patch for manual edits.
• For frontend work, run browser or Playwright verification where practical.
• For review requests, lead with findings and file/line references.
• frontend/dist is ignored and should not be committed.
• Preserve TUI live mode and official F1 SignalR live behavior carefully.

Project Direction

box-box started as a Go Bubble Tea F1 TUI backed mostly by OpenF1. The refactor direction is now:

• Web UI is the primary product surface.
• React + TypeScript frontend is the production Web UI stack.
• Go backend remains the API/server.
• Historical/completed-session data should be local-first from SQLite.
• OpenF1 ingestion is explicit via CLI, not fetched live on every page load.
• Official F1 SignalR remains the live source.
• Desired product feel: clean, dense, technical F1 operations room. Avoid card-heavy AI-slop.

Important Commands

git status --short
git log --oneline -10

go test ./...
npm --prefix frontend test -- --run
npm --prefix frontend run build
npm run test:e2e
npm run test:e2e:prod
npm run test:visual
npm run test:visual:prod

Known test note: do not run Playwright suites that share the same seeded SQLite DB in parallel. Run prod E2E and prod visual sequentially, or they may hit database is locked.

Recent Commits

• a0f135a Update operator documentation
• 79b0b9f Rework command center for race weekends
• 84a8827 Add paddock briefing RSS backend spike
• ee88a07 Add paddock briefing feed ingestion
• Rework Race Hub as weekend workspace (latest Phase 19 commit)

Current State

Phase 19 and Phase 20 have been reviewed and committed. Start new work from a clean tree unless git status --short shows user changes made after this handoff.

Completed Phase 19: Weekend Workspace / Race Hub Flow V1

Claude implemented, and Codex reviewed/committed, a Race Hub redesign that turns /race-hub into a Weekend Workspace.

• New:
  • frontend/src/components/OverviewView.tsx
  • frontend/src/components/WeekendSwitcher.tsx
  • frontend/src/test/RaceHubPage.test.tsx
  • documentations/refactor/26-phase-19-weekend-workspace.md
• Modified:
  • frontend/src/pages/RaceHubPage.tsx
  • frontend/src/components/TabBar.tsx
  • frontend/src/components/DatasetStatusView.tsx
  • frontend/src/styles/app.css
  • tests for TabBar, DatasetStatusView, race-hub, command-center, data-library, production-smoke
  • tests/visual/helpers.ts
  • race-hub visual snapshots
  • root README.md
  • documentations/refactor/README.md

UX changes:

• Race Hub is now a Weekend Workspace.
• Compact GP identity band with country decal/accent strip.
• Horizontal session rail replaces “big table then analysis below.”
• Active session context stays visible above tabs.
• Tabs regrouped into Overview, Race Story, Strategy, Lap Data, Conditions, Race Control, Data Status.
• New Overview tab with winner/pole/fastest/podium cards, condition chips, latest race control, and local coverage meter.
• Inline Switch Weekend panel replaces legacy LocalDataNavigator on Race Hub.
• Data Status links to /admin; no CLI/admin text on fan surface.
• Mobile/iPad improved with wrapping identity band, horizontal session rail, single-column stats.
• /race-hub?session_key=9472 still works and loads Bahrain GP 2024 seeded session.
• Bare /race-hub now resolves to a focus weekend/session via pickFocusMeeting and navigation replace.

Verification run by Codex before commit:

• npm --prefix frontend test -- --run
• npm --prefix frontend run build
• npm run test:e2e
• npm run test:e2e:prod
• npm run test:visual
• npm run test:visual:prod

Small review fix included: frontend/src/test/setup.ts stubs window.scrollTo so TanStack Router scroll restoration does not spam jsdom test stderr.

Completed Phase 20: Paddock Briefing Ingestion CLI

A backend subagent implemented, and Codex reviewed/committed, Phase 20 after the RSS backend spike.

Phase 20 changes:

• Modified:
  • cmd/main.go
• New:
  • internal/news/refresh.go
  • internal/news/refresh_test.go
  • documentations/refactor/29-phase-20-paddock-briefing-ingestion.md

Behavior:

• Adds --ingest-news as a CLI mode.
• Keeps it mutually exclusive with --ingest-year, --ingest-meeting, and --ingest-session.
• Reuses --db for the domain SQLite path.
• Reuses --dry-run to fetch and report feed counts without opening or writing the domain database.
• Uses internal/news.Refresh, which fetches DefaultSources, upserts news_sources, upserts URL-deduped news_items, records fetched_at and expires_at, and continues through individual feed failures before returning a summary error.
• Web requests still do not fetch feeds; /api/v1/news remains read-only against SQLite.

Commands added:

go run ./cmd/main.go --ingest-news
go run ./cmd/main.go --dry-run --ingest-news
go run ./cmd/main.go --ingest-news --db /tmp/boxbox.db

Verification run by Codex before commit:

go test ./cmd/... ./internal/news ./internal/store
git diff --check

Immediate Task

Start with a quick sync:

git status --short
git diff --stat

Then continue with the next requested phase. The most natural next phase is Phase 21: Paddock Briefing UI, unless the user wants to deepen Race Story first.

RSS / Paddock Briefing Context

Cursor completed and Codex committed a backend spike as 84a8827 Add paddock briefing RSS backend spike.

Implemented:

• internal/news: RSS/Atom parser and fetch helper.
• SQLite tables:
  • news_sources
  • news_items
• Store/query methods for cached news.
• Read-only API:
  • GET /api/v1/news?limit=25&source=racefans-f1
• No request-time network fetching.
• Unit tests use local XML fixtures.

Recommended feed sources:

• FIA official RSS
• BBC Sport F1
• Autosport F1
• RaceFans F1
• Guardian Formula One

Optional:

• Motorsport.com
• RACER
• Formula 1 YouTube Atom

Avoid:

• Formula1.com scraping/hidden endpoints
• X/Twitter scraping
• Reddit as primary source
• RSS.app/Feedspot as primary source

Likely Next Phases After Phase 19 And 20

1. Phase 21: Paddock Briefing UI

   • Claude/frontend.
   • Add fan-facing briefing module, likely on Command Center first.
   • Query /api/v1/news.
   • Show source, title, age, category, short feed-provided snippet, external link.
   • Keep publisher attribution visible.
   • Avoid full article storage or scraping.

2. Phase 22: Race Story Deepening

   • Claude/frontend or mixed.
   • Collapse legacy classification/grid/position components into a more fluid Race Story canvas.
   • Improve mobile scanning and session narrative.

3. Phase 23: Full Season Backfill / ingest hardening

   • Cursor/backend.
   • Safer season workflows, resumability, rate-limit controls, coverage reporting.