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 (free, no auth required).

Commands

# 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

3.4 KiB Raw Blame History