RaceBox - F1 Race Intelligence Platform

RaceBox is a full-stack Formula 1 analytics platform that combines live and historical race data, strategy modeling, Monte Carlo simulation, telemetry comparison, and championship projections.

Features

Module	Description
Race Wall	Race classification, lap-time trends, DNF tracking
Strategy Engine	Tyre degradation model, pit-window analysis, undercut/overcut checks
Monte Carlo Sim	Win, podium, points, and position probability distributions
Telemetry	Driver-vs-driver speed/throttle/brake comparison + pace analysis
Championship	Current standings with title probability simulations

Tech Stack

• Backend: FastAPI + Uvicorn
• Data: fastf1, Jolpica Ergast-compatible API, OpenF1
• Analytics: pandas, numpy
• Frontend: single-page dashboard (frontend/index.html) + external CSS/JS with Chart.js

Project Layout

This repository uses a clean backend/frontend split:

F1-Simulator/
|- backend/
|  |- __init__.py
|  |- main.py
|  |- data_loader.py
|  |- strategy.py
|  |- simulator.py
|  |- telemetry.py
|  |- championship.py
|- frontend/
|  |- index.html
|  |- static/
|     |- css/
|     |  |- styles.css
|     |- js/
|        |- app.js
|- run.py
|- requirements.txt
|- cache/                # auto-created fastf1 cache

Setup

1) Create and activate a virtual environment

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate

Windows PowerShell:

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

2) Install dependencies

pip install -r requirements.txt

Run

python run.py

Dev mode:

python run.py --reload

Custom port:

python run.py --port 8080

Open:

• Dashboard: http://localhost:8000
• API docs: http://localhost:8000/docs

Key API Endpoints

GET  /api/schedule/{year}
GET  /api/race/{year}/{gp}/results
GET  /api/race/{year}/{gp}/laps
POST /api/strategy/compare
GET  /api/strategy/undercut/{year}/{gp}?attacker=VER&defender=NOR&current_lap=30
POST /api/simulate
GET  /api/telemetry/{year}/{gp}/compare?driver_a=VER&driver_b=NOR
GET  /api/telemetry/{year}/{gp}/heatmap?driver=VER
GET  /api/telemetry/{year}/{gp}/sectors?drivers=VER,NOR,HAM
GET  /api/championship/{year}?completed_rounds=10
GET  /api/standings/drivers/{year}
GET  /api/standings/constructors/{year}

Data Sources

• fastf1: session, laps, telemetry, weather, GPS
• Jolpica Ergast-compatible API: standings, historical race data
• OpenF1: live timing, pit, weather, session metadata

Notes and Troubleshooting

• First-time fastf1 session loads can download large datasets and may take time.
• Cached data is stored in cache/ and makes repeat requests much faster.
• If you are on Ubuntu/Debian and see externally-managed-environment, install packages inside .venv (recommended) instead of system Python.
• Static dashboard assets are served from /static/ (for example /static/css/styles.css and /static/js/app.js).

Contributing

Contributions are welcome.

If you want to add features, fix bugs, or improve docs:

1. Fork this repository.
2. Create a new branch in your fork.
3. Commit your changes with clear messages.
4. Open a Pull Request to this repository.

License

Copyright (c) 2026 Sanaullah Turab. All rights reserved.

This project is proprietary and confidential. Unauthorized copying, distribution, modification, or commercial use is strictly prohibited.

See LICENSE for full terms.