# akshat12bhardwaj/f1-race-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/akshat12bhardwaj/f1-race-prediction
- Repository: https://github.com/akshat12bhardwaj/f1-race-prediction

## Overview

APEX is an educational F1 race-prediction product. Users configure a historical driver/car lineup, circuit, weather and two model choices; the frontend sends the scenario to FastAPI, which predicts an order that the UI presents as standings and an illustrative 3D replay. The graph also preserves the documented data, feature, training and evaluation branches. Source-index references and README statements support the main connections; unsampled implementation details are not expanded into speculative call chains.

Main entry points: [`frontend/src/App.jsx`](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/App.jsx) (Race dashboard), [`src/api.py`](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/api.py) (FastAPI service), [`src/simulate.py`](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/simulate.py) (Scenario simulator), [`src/multi_sim.py`](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/multi_sim.py) (Model pair simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Race experience"]
  node_app["Race dashboard<br/>[App.jsx]"]
  node_lineup["Lineup editor<br/>[LineupEditor.jsx]"]
  node_lineup_rules["Lineup rules<br/>[lineup.js]"]
  node_conditions["Race conditions<br/>[Conditions.jsx]"]
  node_circuit["Circuit picker<br/>[CircuitPicker.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_results["Standings panel<br/>[RaceBoard.jsx]"]
  node_replay["3D race replay<br/>[Track3D.jsx]"]
  node_motion["Replay motion<br/>[motion.js]"]
end

subgraph group_prediction["Prediction engine"]
  node_backend["FastAPI service<br/>[api.py]"]
  node_simulate["Scenario simulator<br/>[simulate.py]"]
  node_pair_sim["Model pair simulation<br/>[multi_sim.py]"]
  node_algorithms["Model algorithms<br/>[algorithms.py]"]
  node_ranking["Race ranking<br/>[ranking.py]"]
  node_predict["Prediction logic<br/>[predict.py]"]
end

subgraph group_data["Historical data"]
  node_weather["Weather features<br/>[weather.py]"]
  node_features["Race features<br/>[features.py]"]
  node_ratings["Driver ratings<br/>[driver_ratings.py]"]
  node_collection["Data collection<br/>[collect.py]"]
  node_jolpica["Jolpica client<br/>[api_client.py]"]
  node_validation["Raw data validation<br/>[validate_raw.py]"]
end

subgraph group_research["Model research"]
  node_training["Algorithm training"]
  node_policy["Policy definitions<br/>[policies.py]"]
  node_policy_analysis["Policy analysis<br/>[policy_analysis.py]"]
end

node_user(("Race creator"))
node_historical_api["Jolpica F1 data"]

node_user -->|"configures"| node_app
node_app -->|"edits grid"| node_lineup
node_lineup -->|"checks assignments"| node_lineup_rules
node_app -->|"sets weather"| node_conditions
node_app -->|"selects circuit"| node_circuit
node_app -->|"requests prediction"| node_api_client
node_api_client -->|"sends scenario"| node_backend
node_backend -->|"runs scenario"| node_simulate
node_backend -->|"compares models"| node_pair_sim
node_backend -->|"requests prediction"| node_predict
node_simulate -->|"builds inputs"| node_features
node_simulate -->|"uses driver form"| node_ratings
node_simulate -->|"ranks race"| node_ranking
node_pair_sim -->|"scores models"| node_algorithms
node_pair_sim -->|"uses ranking model"| node_ranking
node_pair_sim -->|"uses race simulation"| node_simulate
node_features -->|"uses weather data"| node_weather
node_backend -->|"returns standings"| node_results
node_app -->|"renders race"| node_replay
node_replay -->|"computes replay"| node_motion
node_app -->|"shows standings"| node_results
node_collection -->|"fetches history"| node_jolpica
node_jolpica -->|"requests race data"| node_historical_api
node_validation -->|"validates weather"| node_weather
node_training -->|"trains models"| node_algorithms
node_training -->|"uses features"| node_features
node_policy_analysis -->|"analyzes policies"| node_policy

click node_app "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/App.jsx"
click node_lineup "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/components/LineupEditor.jsx"
click node_lineup_rules "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/lineup.js"
click node_conditions "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/components/Conditions.jsx"
click node_circuit "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/components/CircuitPicker.jsx"
click node_api_client "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/api.js"
click node_backend "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/api.py"
click node_simulate "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/simulate.py"
click node_pair_sim "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/multi_sim.py"
click node_algorithms "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/algorithms.py"
click node_ranking "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/ranking.py"
click node_predict "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/predict.py"
click node_results "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/components/RaceBoard.jsx"
click node_replay "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/components/Track3D.jsx"
click node_motion "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/motion.js"
click node_weather "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/weather.py"
click node_features "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/features.py"
click node_ratings "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/driver_ratings.py"
click node_collection "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/collect.py"
click node_jolpica "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/api_client.py"
click node_validation "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/validate_raw.py"
click node_training "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/train_algorithms.py"
click node_policy "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/policies.py"
click node_policy_analysis "https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/policy_analysis.py"

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_app,node_lineup,node_lineup_rules,node_conditions,node_circuit,node_api_client,node_results,node_replay,node_motion toneBlue
class node_backend,node_simulate,node_pair_sim,node_algorithms,node_ranking,node_predict toneAmber
class node_weather,node_features,node_ratings,node_collection,node_jolpica,node_validation toneMint
class node_training,node_policy,node_policy_analysis toneRose
class node_user,node_historical_api toneIndigo
```

## Components

### Race experience

- [Race dashboard](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Lineup editor](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/components/LineupEditor.jsx): `frontend/src/components/LineupEditor.jsx`
- [Lineup rules](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/lineup.js): `frontend/src/lineup.js`
- [Race conditions](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/components/Conditions.jsx): `frontend/src/components/Conditions.jsx`
- [Circuit picker](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/components/CircuitPicker.jsx): `frontend/src/components/CircuitPicker.jsx`
- [API client](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Standings panel](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/components/RaceBoard.jsx): `frontend/src/components/RaceBoard.jsx`
- [3D race replay](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/components/Track3D.jsx): `frontend/src/components/Track3D.jsx`
- [Replay motion](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/frontend/src/motion.js): `frontend/src/motion.js`

### Prediction engine

- [FastAPI service](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/api.py): `src/api.py`
- [Scenario simulator](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/simulate.py): `src/simulate.py`
- [Model pair simulation](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/multi_sim.py): `src/multi_sim.py`
- [Model algorithms](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/algorithms.py): `src/algorithms.py`
- [Race ranking](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/ranking.py): `src/ranking.py`
- [Prediction logic](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/predict.py): `src/predict.py`

### Historical data

- [Weather features](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/weather.py): `src/weather.py`
- [Race features](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/features.py): `src/features.py`
- [Driver ratings](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/driver_ratings.py): `src/driver_ratings.py`
- [Data collection](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/collect.py): `src/collect.py`
- [Jolpica client](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/api_client.py): `src/api_client.py`
- [Raw data validation](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/validate_raw.py): `src/validate_raw.py`

### Model research

- [Algorithm training](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/train_algorithms.py): `src/train_algorithms.py`
- [Policy definitions](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/policies.py): `src/policies.py`
- [Policy analysis](https://github.com/akshat12bhardwaj/f1-race-prediction/blob/main/src/policy_analysis.py): `src/policy_analysis.py`

### Other components

- **Race creator**
- **Jolpica F1 data**

## Connections

- Race creator → Race dashboard: configures
- Race dashboard → Lineup editor: edits grid (evidence: `frontend/src/App.jsx`)
- Lineup editor → Lineup rules: checks assignments (evidence: `frontend/src/components/LineupEditor.jsx`)
- Race dashboard → Race conditions: sets weather (evidence: `frontend/src/App.jsx`)
- Race dashboard → Circuit picker: selects circuit (evidence: `frontend/src/App.jsx`)
- Race dashboard → API client: requests prediction (evidence: `frontend/src/App.jsx`)
- API client → FastAPI service: sends scenario
- FastAPI service → Scenario simulator: runs scenario (evidence: `src/api.py`)
- FastAPI service → Model pair simulation: compares models (evidence: `src/api.py`)
- FastAPI service → Prediction logic: requests prediction (evidence: `src/api.py`)
- Scenario simulator → Race features: builds inputs (evidence: `src/simulate.py`)
- Scenario simulator → Driver ratings: uses driver form (evidence: `src/simulate.py`)
- Scenario simulator → Race ranking: ranks race (evidence: `src/simulate.py`)
- Model pair simulation → Model algorithms: scores models (evidence: `src/multi_sim.py`)
- Model pair simulation → Race ranking: uses ranking model (evidence: `src/multi_sim.py`)
- Model pair simulation → Scenario simulator: uses race simulation (evidence: `src/multi_sim.py`)
- Race features → Weather features: uses weather data (evidence: `src/features.py`)
- FastAPI service → Standings panel: returns standings
- Race dashboard → 3D race replay: renders race (evidence: `frontend/src/App.jsx`)
- 3D race replay → Replay motion: computes replay (evidence: `frontend/src/components/Track3D.jsx`)
- Race dashboard → Standings panel: shows standings (evidence: `frontend/src/App.jsx`)
- Data collection → Jolpica client: fetches history (evidence: `src/collect.py`)
- Jolpica client → Jolpica F1 data: requests race data (evidence: `src/api_client.py`)
- Raw data validation → Weather features: validates weather (evidence: `src/validate_raw.py`)
- Algorithm training → Model algorithms: trains models (evidence: `src/train_algorithms.py`)
- Algorithm training → Race features: uses features (evidence: `src/train_algorithms.py`)
- Policy analysis → Policy definitions: analyzes policies (evidence: `src/policy_analysis.py`)
