# horserider2146/f1-dashboard architecture

> Architecture diagram of the GitHub repository horserider2146/f1-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/horserider2146/f1-dashboard
- Repository: https://github.com/horserider2146/f1-dashboard

## Overview

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: [`api/routers/analytics.py`](https://github.com/horserider2146/f1-dashboard/blob/main/api/routers/analytics.py) (Analytics routes), [`api/main.py`](https://github.com/horserider2146/f1-dashboard/blob/main/api/main.py) (FastAPI app), [`data/ingestion.py`](https://github.com/horserider2146/f1-dashboard/blob/main/data/ingestion.py) (Ingestion), [`api/schemas.py`](https://github.com/horserider2146/f1-dashboard/blob/main/api/schemas.py) (API schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_users["Users"]
  node_user(("User<br/>person"))
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_app["Streamlit app<br/>entrypoint<br/>[app.py]"]
  node_dashboard_client["API client<br/>http client<br/>[api_client.py]"]
  node_dashboard_views["Views<br/>ui pages"]
  node_dashboard_charts["Charts<br/>ui components<br/>[charts.py]"]
end

subgraph group_api["API"]
  node_api_main["FastAPI app<br/>entrypoint<br/>[main.py]"]
  node_api_races["Race routes<br/>router<br/>[races.py]"]
  node_api_telemetry["Telemetry routes<br/>router<br/>[telemetry.py]"]
  node_api_analytics["Analytics routes<br/>router<br/>[analytics.py]"]
  node_api_stats["Stats routes<br/>router<br/>[stats.py]"]
  node_api_schemas["API schemas<br/>contracts<br/>[schemas.py]"]
end

subgraph group_analytics["Analytics"]
  node_strategy["Strategy engine<br/>domain logic<br/>[strategy.py]"]
  node_tyre_model["Tyre model<br/>domain logic<br/>[tyre_model.py]"]
  node_events["Event detection<br/>domain logic<br/>[events.py]"]
  node_predictor["Predictor<br/>ml model<br/>[predictor.py]"]
  node_stats_suite["Stats suite<br/>analysis package"]
end

subgraph group_data["Data"]
  node_fastf1_loader["FastF1 loader<br/>ingestion<br/>[fastf1_loader.py]"]
  node_ergast_client["Ergast client<br/>ingestion<br/>[ergast_client.py]"]
  node_ingestion["Ingestion<br/>pipeline<br/>[ingestion.py]"]
end

subgraph group_storage["Storage"]
  node_cache_data[("FastF1 cache<br/>filesystem cache")]
  node_cache_models[("Model cache<br/>model store")]
  node_db_conn["DB connection<br/>database adapter<br/>[connection.py]"]
  node_db_schema["Init SQL<br/>schema<br/>[init.sql]"]
end

subgraph group_external["External"]
  node_fastf1{{"FastF1<br/>external service"}}
  node_ergast{{"Ergast API<br/>external service"}}
end

node_user -->|"uses"| node_dashboard_app
node_dashboard_app -->|"fetches data"| node_dashboard_client
node_dashboard_app -->|"renders"| node_dashboard_views
node_dashboard_views -->|"draws"| node_dashboard_charts
node_dashboard_client -->|"HTTP"| node_api_main
node_api_main -->|"routes"| node_api_races
node_api_main -->|"routes"| node_api_telemetry
node_api_main -->|"routes"| node_api_analytics
node_api_main -->|"routes"| node_api_stats
node_api_races -->|"serializes"| node_api_schemas
node_api_telemetry -->|"serializes"| node_api_schemas
node_api_analytics -->|"serializes"| node_api_schemas
node_api_stats -->|"serializes"| node_api_schemas
node_api_races -->|"reads"| node_ingestion
node_api_telemetry -->|"reads"| node_ingestion
node_api_analytics -->|"computes"| node_strategy
node_api_analytics -->|"computes"| node_tyre_model
node_api_analytics -->|"computes"| node_events
node_api_analytics -->|"predicts"| node_predictor
node_api_stats -->|"analyzes"| node_stats_suite
node_ingestion -->|"loads"| node_fastf1_loader
node_ingestion -->|"loads"| node_ergast_client
node_fastf1_loader -->|"API"| node_fastf1
node_ergast_client -->|"API"| node_ergast
node_fastf1_loader -->|"caches"| node_cache_data
node_predictor -->|"persists"| node_cache_models
node_predictor -->|"trains on"| node_cache_data
node_stats_suite -.->|"optionally reads"| node_db_conn
node_db_conn -->|"initializes"| node_db_schema

click node_dashboard_app "https://github.com/horserider2146/f1-dashboard/blob/main/dashboard/app.py"
click node_dashboard_client "https://github.com/horserider2146/f1-dashboard/blob/main/dashboard/api_client.py"
click node_dashboard_views "https://github.com/horserider2146/f1-dashboard/tree/main/dashboard/views"
click node_dashboard_charts "https://github.com/horserider2146/f1-dashboard/blob/main/dashboard/components/charts.py"
click node_api_main "https://github.com/horserider2146/f1-dashboard/blob/main/api/main.py"
click node_api_races "https://github.com/horserider2146/f1-dashboard/blob/main/api/routers/races.py"
click node_api_telemetry "https://github.com/horserider2146/f1-dashboard/blob/main/api/routers/telemetry.py"
click node_api_analytics "https://github.com/horserider2146/f1-dashboard/blob/main/api/routers/analytics.py"
click node_api_stats "https://github.com/horserider2146/f1-dashboard/blob/main/api/routers/stats.py"
click node_api_schemas "https://github.com/horserider2146/f1-dashboard/blob/main/api/schemas.py"
click node_strategy "https://github.com/horserider2146/f1-dashboard/blob/main/analytics/strategy.py"
click node_tyre_model "https://github.com/horserider2146/f1-dashboard/blob/main/analytics/tyre_model.py"
click node_events "https://github.com/horserider2146/f1-dashboard/blob/main/analytics/events.py"
click node_predictor "https://github.com/horserider2146/f1-dashboard/blob/main/analytics/predictor.py"
click node_stats_suite "https://github.com/horserider2146/f1-dashboard/tree/main/analytics/stats"
click node_fastf1_loader "https://github.com/horserider2146/f1-dashboard/blob/main/data/fastf1_loader.py"
click node_ergast_client "https://github.com/horserider2146/f1-dashboard/blob/main/data/ergast_client.py"
click node_ingestion "https://github.com/horserider2146/f1-dashboard/blob/main/data/ingestion.py"
click node_db_conn "https://github.com/horserider2146/f1-dashboard/blob/main/database/connection.py"
click node_db_schema "https://github.com/horserider2146/f1-dashboard/blob/main/database/init.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_user,node_fastf1,node_ergast toneBlue
class node_dashboard_app,node_dashboard_client,node_dashboard_views,node_dashboard_charts toneAmber
class node_api_main,node_api_races,node_api_telemetry,node_api_analytics,node_api_stats,node_api_schemas toneMint
class node_strategy,node_tyre_model,node_events,node_predictor,node_stats_suite toneRose
class node_fastf1_loader,node_ergast_client,node_ingestion toneIndigo
class node_cache_data,node_cache_models,node_db_conn,node_db_schema toneTeal
```

## Components

### Users

Interactive dashboard consumers

- **User**: person · Opens the dashboard and consumes the app

### Dashboard

Streamlit presentation tier

- [Streamlit app](https://github.com/horserider2146/f1-dashboard/blob/main/dashboard/app.py): entrypoint · Dashboard runtime entrypoint · `dashboard/app.py`
- [API client](https://github.com/horserider2146/f1-dashboard/blob/main/dashboard/api_client.py): http client · Calls backend endpoints over HTTP · `dashboard/api_client.py`
- [Views](https://github.com/horserider2146/f1-dashboard/tree/main/dashboard/views): ui pages · Race, telemetry, strategy, predictor, stats, and lap analysis pages · `dashboard/views`
- [Charts](https://github.com/horserider2146/f1-dashboard/blob/main/dashboard/components/charts.py): ui components · Reusable chart and visual components · `dashboard/components/charts.py`

### API

FastAPI service layer

- [FastAPI app](https://github.com/horserider2146/f1-dashboard/blob/main/api/main.py): entrypoint · Backend application entrypoint · `api/main.py`
- [Race routes](https://github.com/horserider2146/f1-dashboard/blob/main/api/routers/races.py): router · Race summaries and overview endpoints · `api/routers/races.py`
- [Telemetry routes](https://github.com/horserider2146/f1-dashboard/blob/main/api/routers/telemetry.py): router · Lap and metric telemetry endpoints · `api/routers/telemetry.py`
- [Analytics routes](https://github.com/horserider2146/f1-dashboard/blob/main/api/routers/analytics.py): router · Strategy, tyre, events, and prediction endpoints · `api/routers/analytics.py`
- [Stats routes](https://github.com/horserider2146/f1-dashboard/blob/main/api/routers/stats.py): router · Statistical analysis endpoints · `api/routers/stats.py`
- [API schemas](https://github.com/horserider2146/f1-dashboard/blob/main/api/schemas.py): contracts · Pydantic request and response models · `api/schemas.py`

### Analytics

Domain computation and statistics

- [Strategy engine](https://github.com/horserider2146/f1-dashboard/blob/main/analytics/strategy.py): domain logic · Stints, pit strategy, and undercut/overcut analysis · `analytics/strategy.py`
- [Tyre model](https://github.com/horserider2146/f1-dashboard/blob/main/analytics/tyre_model.py): domain logic · Degradation and pit-window modeling · `analytics/tyre_model.py`
- [Event detection](https://github.com/horserider2146/f1-dashboard/blob/main/analytics/events.py): domain logic · Overtakes and safety-car/VSC detection · `analytics/events.py`
- [Predictor](https://github.com/horserider2146/f1-dashboard/blob/main/analytics/predictor.py): ml model · Race outcome training and inference · `analytics/predictor.py`
- [Stats suite](https://github.com/horserider2146/f1-dashboard/tree/main/analytics/stats): analysis package · Classical statistical analysis modules · `analytics/stats`

### Data

Ingestion and normalization

- [FastF1 loader](https://github.com/horserider2146/f1-dashboard/blob/main/data/fastf1_loader.py): ingestion · Loads timing and telemetry data · `data/fastf1_loader.py`
- [Ergast client](https://github.com/horserider2146/f1-dashboard/blob/main/data/ergast_client.py): ingestion · Fetches historical race metadata · `data/ergast_client.py`
- [Ingestion](https://github.com/horserider2146/f1-dashboard/blob/main/data/ingestion.py): pipeline · Coordinates loading and normalization · `data/ingestion.py`

### Storage

Local persistence and database boundary

- **FastF1 cache**: filesystem cache · Downloaded race data cache
- **Model cache**: model store · Persisted predictor models
- [DB connection](https://github.com/horserider2146/f1-dashboard/blob/main/database/connection.py): database adapter · Database boundary for persisted data · `database/connection.py`
- [Init SQL](https://github.com/horserider2146/f1-dashboard/blob/main/database/init.sql): schema · Database initialization script · `database/init.sql`

### External

Third-party data and model services

- **FastF1**: external service · Official timing and telemetry source
- **Ergast API**: external service · Historical Formula 1 data source

## Connections

- 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
