How horserider2146/f1-dashboard works
1. Overall shape
This repository is a two-process full-stack application: a FastAPI backend exposes race/analytics/statistics endpoints, and a Streamlit dashboard consumes those endpoints to render the user interface. The dashboard is not doing the heavy data work itself; it is mainly a presentation layer over the API.
2. Primary request flow
The normal runtime flow is: user opens Streamlit page → dashboard/api_client calls FastAPI → API router invokes analytics/data layer → results are returned as JSON → dashboard renders tables/charts. This separation is important for the architecture diagram because the UI and computation layers are decoupled by HTTP.
3. Backend API layer
The backend is organized under api/ with four route groups:
- races.py for race-level data and summaries
- telemetry.py for per-lap/per-metric telemetry
- analytics.py for strategy, tyre, event detection, and prediction features
- stats.py for statistical analysis outputs
api/schemas.py defines the Pydantic response/request shapes that stabilize the boundary between backend and dashboard.
4. Data acquisition layer
The data/ package is the ingestion boundary to external F1 data sources:
- fastf1_loader.py loads official timing/telemetry data via FastF1
- ergast_client.py connects to the Ergast API for historical F1 results/metadata
- ingestion.py likely coordinates loading/normalization of race data
This layer feeds the analytics modules with race sessions, lap timing, telemetry, and race metadata.
5. Local persistence and cache
The repo is designed to cache expensive assets locally instead of keeping a central server-side datastore in the critical path:
- cache/fastf1/ stores downloaded FastF1 race data
- cache/models/ stores trained predictor models
There is also a database/ package and init.sql, indicating a database-related boundary exists, but the dominant architecture in the README is file-cache driven rather than DB-centric.
6. Analytics / domain computation
The analytics/ package contains the core F1 domain logic:
- strategy.py handles stint composition, pit-stop strategy, undercut/overcut-style comparisons
- tyre_model.py models degradation and pit-window behavior
- events.py detects overtakes and safety car / VSC patterns
- predictor.py implements the race outcome ML model
This is the main computation layer between raw race data and the API responses.
7. Statistical analysis subsystem
analytics/stats/ is a separate analytical subdomain focused on classical statistics rather than race strategy:
- dci.py computes the Driver Consistency Index
- inference.py covers MLE, Bayesian win probability, t-tests, and z-tests
- anova.py handles one-way/two-way ANOVA and Tukey-style comparisons
- regression.py provides OLS/Ridge/Lasso and correlation analysis
- logistic.py handles podium probability modeling
- nonparametric.py provides Wilcoxon, Mann-Whitney, Friedman tests
In the diagram, this should be shown as a distinct analytics branch because it serves the “Statistical Analysis” dashboard pages and API endpoints.
8. Dashboard layer
dashboard/ is the presentation tier built with Streamlit. It is split into:
- app.py as the entry point
- api_client.py as the HTTP boundary to FastAPI
- components/ for reusable visual pieces like charts
- views/ with one module per page: race overview, telemetry, strategy, predictor, stats analysis, and lap analysis
This layer consumes structured API data and turns it into interactive plots, tables, and narratives.
9. Feature-to-page mapping
The UI pages align closely with backend domains:
- Race Overview: lap times, fastest laps, position history, track map/animation
- Telemetry: speed traces and DRS-related interpretation
- Strategy: stints, pit stops, tyre degradation, undercuts, safety car laps
- Predictor: model training and race-result prediction
- Stats Analysis: statistical testing and model comparison
That mapping makes the architecture easy to diagram: each page is a thin consumer of a specific API/router + analytics module combination.
10. External services and runtimes
The system depends on external F1 data services and standard Python ML/statistics libraries:
- FastF1 for official timing/telemetry data
- Ergast API for historical race data
- XGBoost / scikit-learn / statsmodels / scipy for modeling and inference
- Plotly for charting in the dashboard
Runtime entry points are uvicorn api.main:app for the backend and streamlit run dashboard/app.py for the frontend.
11. Deployment and packaging boundaries
There are separate container definitions for the API and dashboard (Dockerfile.api, Dockerfile.dashboard), plus docker-compose.yml and a run_local.sh helper. This indicates the repo supports both local split-process execution and containerized deployment, reinforcing the two-tier architecture.
12. Model lifecycle
The race predictor has an explicit training lifecycle: the dashboard/API can trigger a training endpoint, the model is persisted under cache/models/, and then reloaded on restart. This is a notable stateful path in an otherwise mostly read-heavy analytics system.
13. What to emphasize in a diagram
A clean architecture diagram should show:
- Users → Streamlit dashboard
- Dashboard → FastAPI API over HTTP
- API → analytics/statistics modules
- API → data loaders → FastF1/Ergast
- analytics → local caches/models
- optional database layer as secondary/supporting storage
The main boundary is not “frontend vs backend” only; it is also interactive UI vs data acquisition/analysis engine.
Main entry points: analytics.py Analytics routes · main.py FastAPI app · ingestion.py Ingestion · schemas.py API schemas
Components 25
Users
Interactive dashboard consumers
- User · Opens the dashboard and consumes the app
Dashboard
Streamlit presentation tier
- Streamlit app · Dashboard runtime entrypoint
dashboard/app.py - API client · Calls backend endpoints over HTTP
dashboard/api_client.py - Views · Race, telemetry, strategy, predictor, stats, and lap analysis pages
dashboard/views - Charts · Reusable chart and visual components
dashboard/components/charts.py
API
FastAPI service layer
- FastAPI app · Backend application entrypoint
api/main.py - Race routes · Race summaries and overview endpoints
api/routers/races.py - Telemetry routes · Lap and metric telemetry endpoints
api/routers/telemetry.py - Analytics routes · Strategy, tyre, events, and prediction endpoints
api/routers/analytics.py - Stats routes · Statistical analysis endpoints
api/routers/stats.py - API schemas · Pydantic request and response models
api/schemas.py
Analytics
Domain computation and statistics
- Strategy engine · Stints, pit strategy, and undercut/overcut analysis
analytics/strategy.py - Tyre model · Degradation and pit-window modeling
analytics/tyre_model.py - Event detection · Overtakes and safety-car/VSC detection
analytics/events.py - Predictor · Race outcome training and inference
analytics/predictor.py - Stats suite · Classical statistical analysis modules
analytics/stats
Data
Ingestion and normalization
- FastF1 loader · Loads timing and telemetry data
data/fastf1_loader.py - Ergast client · Fetches historical race metadata
data/ergast_client.py - Ingestion · Coordinates loading and normalization
data/ingestion.py
Storage
Local persistence and database boundary
- FastF1 cache · Downloaded race data cache
- Model cache · Persisted predictor models
- DB connection · Database boundary for persisted data
database/connection.py - Init SQL · Database initialization script
database/init.sql
External
Third-party data and model services
- FastF1 · Official timing and telemetry source
- Ergast API · Historical Formula 1 data source
Connections 29
- User → Streamlit app: uses · Opens the dashboard UI
- Streamlit app → API client: fetches data · UI delegates data access to the API client
- Streamlit app → Views: renders · Loads page modules
- Views → Charts: draws · Uses shared chart components
- API client → FastAPI app: HTTP · Requests backend endpoints
- FastAPI app → Race routes: routes · Registers race endpoints
- FastAPI app → Telemetry routes: routes · Registers telemetry endpoints
- FastAPI app → Analytics routes: routes · Registers analytics endpoints
- FastAPI app → Stats routes: routes · Registers stats endpoints
- Race routes → API schemas: serializes · Uses shared response models
- Telemetry routes → API schemas: serializes · Uses shared response models
- Analytics routes → API schemas: serializes · Uses shared response models
- Stats routes → API schemas: serializes · Uses shared response models
- Race routes → Ingestion: reads · Pulls normalized race data
- Telemetry routes → Ingestion: reads · Pulls lap and telemetry data
- Analytics routes → Strategy engine: computes · Strategy analysis responses
- Analytics routes → Tyre model: computes · Tyre and degradation outputs
- Analytics routes → Event detection: computes · Event detection outputs
- Analytics routes → Predictor: predicts · Training and inference endpoints
- Stats routes → Stats suite: analyzes · Statistical testing and modeling
- Ingestion → FastF1 loader: loads · Uses FastF1 timing and telemetry loader
- Ingestion → Ergast client: loads · Uses Ergast historical data client
- FastF1 loader → FastF1: API · Pulls official session data
- Ergast client → Ergast API: API · Pulls historical race data
- FastF1 loader → FastF1 cache: caches · Stores downloaded race data locally
- Predictor → Model cache: persists · Stores trained models
- Predictor → FastF1 cache: trains on · Uses cached race data for training
- Stats suite → DB connection: optionally reads · Database-backed analysis boundary
- DB connection → Init SQL: initializes · Schema setup for persistent storage