TUI Build

CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**box-box** is a Formula 1 Terminal User Interface (TUI) application written in Go. It displays F1 standings, race calendar, results, and driver data sourced from the [OpenF1 API](https://openf1.org) (free, no auth required).
+
+## Commands
+
+```bash
+# Build
+go build ./cmd
+
+# Run
+go run ./cmd/main.go
+
+# Run all tests
+go test ./...
+
+# Run tests with output
+go test -v ./internal/api
+
+# Install dependencies (not yet done)
+go get github.com/charmbracelet/bubbletea
+go get github.com/charmbracelet/lipgloss
+go get github.com/charmbracelet/bubbles
+```
+
+Tests in `internal/api/openf1_test.go` are integration tests hitting the real OpenF1 API — they include rate-limit-aware skipping logic.
+
+## Architecture
+
+### Tech Stack
+
+| Tool | Purpose |
+|---|---|
+| **Bubble Tea** | TUI framework using Elm architecture (Model → Update → View) |
+| **Lipgloss** | Terminal styling — colors, borders, layout |
+| **Bubbles** | Pre-built TUI components (tables, spinners, viewports) |
+| **OpenF1 API** | F1 data source at `https://api.openf1.org/v1/` |
+
+### Elm Architecture (Bubble Tea)
+
+All UI follows the unidirectional flow: `event → Update → View`
+
+- **Model** — app state (active tab, loaded data, loading flags)
+- **Update(msg)** — handles keypresses and API response messages, returns new model + optional `tea.Cmd`
+- **View()** — renders model to a string printed to terminal
+- **Cmd** — async work (API calls) that runs outside the Update loop and sends a `Msg` back when done
+
+Each tab (standings, calendar, results, driver) is its own Bubble Tea sub-model. The root `app.go` holds all tabs and delegates input to the active one.
+
+### Package Structure
+
+```
+cmd/main.go              # Entry point — wire up and launch the TUI
+internal/
+  api/
+    client.go            # OpenF1Client: HTTP wrapper with 10s timeout
+    openf1.go            # 23 endpoint methods (meetings, drivers, results, telemetry, etc.)
+    openf1_test.go       # Integration tests for API layer
+  models/
+    types.go             # 18 data structs: Circuit, Meeting, Session, Driver, Lap, Stint, etc.
+  ui/
+    app.go               # (planned) Root model, tab switching
+    standings.go         # (planned) Championship standings tab
+    calendar.go          # (planned) Race calendar tab
+    results.go           # (planned) Race results tab
+    driver.go            # (planned) Driver lookup tab
+```
+
+### Current Status
+
+- **API layer**: Complete — all 23 OpenF1 endpoints implemented
+- **Data models**: Complete — 18 structs covering all F1 entities
+- **UI layer**: Not yet implemented — `internal/ui/` is empty, `cmd/main.go` is a stub
+- **Dependencies**: Not yet installed — `go.mod` has no direct deps yet
+
+### API Layer
+
+`OpenF1Client` in `internal/api/client.go` wraps a standard `http.Client`. All methods in `openf1.go` follow the pattern: build query params → GET from `https://api.openf1.org/v1/{endpoint}` → decode JSON into model types.
+
+Key endpoint groups:
+- **Session context**: `GetMeetings`, `GetSessions`
+- **Standings**: `GetDriverChampionship`, `GetTeamChampionship`
+- **Race data**: `GetSessionResults`, `GetStartingGrid`, `GetLaps`, `GetStints`, `GetPits`
+- **Live telemetry**: `GetPositions`, `GetIntervals`, `GetCarData`, `GetLocations`
+- **Race events**: `GetRaceControl`, `GetOvertakes`, `GetWeather`, `GetTeamRadio`