Pranav's Pit Wall

Personal laptop-hosted Formula 1 pit-wall dashboard. FastAPI serves the API, WebSocket live feed, and the compiled React SPA from one origin.

Requirements

• Python 3.12+ with uv
• Node.js with pnpm via Corepack

Setup and launch

uv sync
corepack enable
pnpm --dir frontend install --frozen-lockfile
pnpm --dir frontend build
uv run python scripts/launch.py

The launcher migrates the SQLite database, checks for frontend/dist, then serves on port 8000. It prints:

• Pit Wall: http://127.0.0.1:8000
• LAN: http://<your-lan-ip>:8000 when a local interface is available

Open either URL. API and SPA share the same origin, so refreshing /telemetry (or any client route) keeps working.

Binding 0.0.0.0 is for a trusted home LAN only. Do not port-forward this service to the public internet. There is no TLS and no authentication.

Development

Run API and Vite together (Vite proxies /api and live WebSockets to FastAPI):

uv run python scripts/dev.py

scripts/dev.py sets PITWALL_DEV=1 so the API starts without a prior frontend/dist build. Use Vite on port 5173 for the SPA during development; port 8000 serves API and WebSockets only.

• API / WebSockets: http://127.0.0.1:8000
• Vite HMR: http://127.0.0.1:5173

Production-style serve (scripts/launch.py or direct uvicorn) still requires pnpm --dir frontend build.

Data and logs

Configure via .env (see .env.example). Defaults:

Setting	Default
PITWALL_DATA_DIR	data
PITWALL_FRONTEND_DIST	frontend/dist
PITWALL_LOG_LEVEL	INFO
PITWALL_LIVE_SOURCE	livef1

Rotating structured logs are written to data/logs/pitwall.log (10 MB × 3 backups). Key operational paths emit JSON fields such as session_id, job_id, lifecycle, error_code, attempt, and cleanup — never raw car-data or position batches.

Diagnostics: GET /api/v1/health reports disk free space, database probe, live source status, active session, and queued/failed job counts. Status is degraded when disk is below 1 GB, the database probe fails, or a live session's source is disconnected.

Acceptance gates

Automated release gate (from repo root):

uv run ruff check backend scripts
uv run mypy backend/pitwall
uv run pytest backend/tests --cov=pitwall --cov-report=term-missing
uv run python scripts/export_openapi.py
pnpm --dir frontend generate:api
pnpm --dir frontend lint
pnpm --dir frontend typecheck
pnpm --dir frontend test
pnpm --dir frontend build
pnpm --dir frontend e2e

pnpm --dir frontend e2e launches the packaged app with PITWALL_LIVE_SOURCE=fake and runs Playwright journeys (live reconnect, completed analysis, import/retention, render budget).

Operator docs: docs/operations/runbook.md.

Real-practice acceptance (manual, during an official practice session):

uv run python scripts/smoke_live.py
uv run python scripts/launch.py

Complete docs/operations/practice-smoke-checklist.md before race use.