Project preview

---

F1 Race Strategy Optimization Engine

FastAPI dashboard for F1-style race strategy, simulation, and AIML demos—built on historical F1DB CSV data. The goal is a credible decision-support feel (race wall, optimizer, engineer view), not a static chart page.

Backend	FastAPI, Pydantic
Data	F1DB CSVs under data/f1db/; DuckDB-ready layer with Pandas/CSV fallback
Frontend	Vanilla HTML / CSS / JavaScript in src/f1_strategy_engine/static/
ML / analytics	NumPy, Pandas, scikit-learn; Model Lab + training script

---

Contents

• Features
• Repository layout
• Data
• Run locally
• Tests
• Documentation

---

Features

Race control & history

• Multi-season browsing from 2018 onward; race, circuit, and driver selection
• Pit-stop board from real CSV-backed stints (compound colouring inferred where the dataset does not expose compound-by-stint)

Strategy & simulation

• Optimizer: recommended plan, ranked alternatives, baseline vs optimized, timing and risk-style signals; reacts to driver selection in the UI
• Monte Carlo–style simulation: scenario cards, position bands, win probability, pit/compound summaries

Live-style race flow

• HTTP live race preview (POST /api/live-race) and WebSocket stream (/ws/live-race) for local Uvicorn
• Pluggable live provider layer for future timing/weather feeds

AIML-focused views

• Race Engineer: primary/fallback strategy, assumptions, lap-by-lap callouts, scenario comparison (green / safety car / rain / traffic)
• Model Lab: proxy models, metrics (MAE / RMSE / R²), feature importance, backtesting rows, calibration-style bins
• Archive and tyre degradation views

Platform & APIs

• /api/platform: data platform / engine summary
• DataPlatformService: DuckDB path when available; on Vercel, warehouse writes are skipped in favour of CSV mode (read-only filesystem constraints)

---

Repository layout

.
├── main.py, index.py, app.py     # Vercel FastAPI entrypoints (bootstrap src/ + re-export app)
├── run_dashboard.py              # Local Uvicorn (127.0.0.1:8000)
├── start_dashboard.bat           # Launch dashboard in a new window
├── start_dashboard_detached.bat  # Detached launcher variant
├── pyproject.toml                # Package metadata, deps, Vercel app script + build hook
├── requirements.txt              # Editable install: -e .
├── .python-version               # Python 3.12 (tooling / Vercel hint)
├── .vercelignore                 # Trim deploy upload
│
├── src/
│   ├── index.py                  # Alternate Vercel entry under src/
│   └── f1_strategy_engine/
│       ├── api/main.py           # FastAPI app, routes, static mount, WebSockets
│       ├── domain/models.py      # Pydantic / shared models
│       ├── ml/baseline.py
│       ├── optimizer/engine.py
│       ├── services/
│       │   ├── history_service.py
│       │   ├── data_platform_service.py
│       │   ├── live_data_provider_service.py
│       │   ├── live_race_service.py
│       │   ├── model_lab_service.py
│       │   ├── race_engineer_service.py
│       │   ├── simulation_service.py
│       │   └── strategy_service.py
│       └── static/               # index.html, app.js, styles.css
│
├── data/f1db/                    # F1DB CSV dataset (large; not listed file-by-file)
├── artifacts/                    # Generated model_lab.pkl (gitignored; built on CI/Vercel)
├── assets/screenshots/           # SVG previews for docs / readme
├── docs/                         # Product & architecture notes
├── examples/                     # Sample JSON payloads
├── scripts/train_model_lab.py    # Trains / refreshes Model Lab artifact
└── tests/                        # pytest (API + optimizer)

---

Data

Open F1DB CSVs live in data/f1db/. Pit counts and stint structure follow the files; compound colours on the board are inferred when stint-level compounds are missing.

---

Run locally

1. Virtual environment (Windows PowerShell)

python -m venv .venv
.venv\Scripts\Activate.ps1

2. Install

.venv\Scripts\python.exe -m pip install -r requirements.txt

3. Run

.venv\Scripts\python.exe run_dashboard.py

Or double-click / run start_dashboard.bat.

4. Open http://127.0.0.1:8000/

---

Tests

Install dev extras once, then run pytest:

.venv\Scripts\python.exe -m pip install -e ".[dev]"
.venv\Scripts\python.exe -m pytest -q

---

Documentation

• Product brief
• Architecture
• MVP backlog

---

Why this project

• Optimization and simulation tied to real historical motorsport data
• Explainable strategy-style outputs and engineer-facing UX
• Clear path from data → models → UI, suitable for portfolio and AIML coursework

---

Possible next steps

• Stronger predictive models trained end-to-end on historical seasons
• Systematic backtesting against past races
• Richer uncertainty and calibration in simulation
• Deeper model evaluation dashboards