# yashpatel2777/f1_race_strategy_predictor architecture

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

- Interactive diagram: https://gitdiagram.com/yashpatel2777/f1_race_strategy_predictor
- Repository: https://github.com/yashpatel2777/f1_race_strategy_predictor

## Overview

This project learns F1 pit strategy from historical session data, then trains and evaluates a PPO agent in a configurable race simulator. The main workflow runs from data download and tire-model fitting through simulated strategy training, baseline comparison, and race visualization. The graph also includes telemetry visualization as a separate capability. Some script and subsystem wiring is based on the README and tree; unsampled implementation details are not inferred.

Main entry points: [`src/environment/race_simulator.py`](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/environment/race_simulator.py) (Race simulator), [`src/data/fastf1_loader.py`](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/data/fastf1_loader.py) (Session loader), [`src/data_pipeline/telemetry_loader.py`](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/data_pipeline/telemetry_loader.py) (Telemetry pipeline), [`scripts/evaluate_agent.py`](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/scripts/evaluate_agent.py) (Evaluate agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Historical Data"]
  node_download["Download sessions<br/>[download_data.py]"]
  node_loader["Session loader<br/>[fastf1_loader.py]"]
  node_preprocess["Lap preprocessing"]
  node_historical[("Cached session data")]
end

subgraph group_models["Models"]
  node_fit["Fit degradation<br/>[fit_degradation.py]"]
  node_degradation["Tire degradation"]
  node_lapmodel["Lap-time model<br/>[lap_time_model.py]"]
end

subgraph group_simulation["Race Simulation"]
  node_config["Track configuration"]
  node_state["Race state<br/>[race_state.py]"]
  node_simulator["Race simulator<br/>[race_simulator.py]"]
  node_environment["Gym strategy env<br/>[f1_strategy_env.py]"]
  node_ppo["PPO agent<br/>[ppo_agent.py]"]
  node_train["Train agent<br/>[train_agent.py]"]
  node_baselines["Strategy baselines<br/>[baselines.py]"]
end

subgraph group_outputs["Evaluation &amp; Visualization"]
  node_evaluate["Evaluate agent<br/>[evaluate_agent.py]"]
  node_visualize["Race charts<br/>[visualize_race.py]"]
  node_telemetry["Telemetry pipeline"]
  node_plots["Telemetry plots<br/>[telemetry_plots.py]"]
  node_trackmaps["Track maps<br/>[track_maps.py]"]
  node_animation["Lap animation<br/>[animator.py]"]
end

node_user(("Engineer"))
node_fastf1["FastF1"]

node_user -->|"starts workflow"| node_download
node_download -->|"requests sessions"| node_loader
node_loader -->|"loads session"| node_fastf1
node_loader -->|"caches data"| node_historical
node_fit -->|"prepares laps"| node_preprocess
node_preprocess -->|"loads laps"| node_loader
node_fit -->|"fits model"| node_degradation
node_degradation -->|"supplies degradation"| node_lapmodel
node_train -->|"trains"| node_ppo
node_ppo -->|"learns policy"| node_environment
node_environment -->|"advances race"| node_simulator
node_simulator -->|"updates"| node_state
node_simulator -->|"predicts lap time"| node_lapmodel
node_simulator -->|"reads track settings"| node_config
node_evaluate -->|"loads agent"| node_ppo
node_evaluate -->|"compares strategies"| node_baselines
node_evaluate -->|"runs races"| node_environment
node_visualize -->|"visualizes races"| node_simulator
node_telemetry -->|"loads session data"| node_loader
node_plots -->|"plots telemetry"| node_telemetry
node_trackmaps -->|"maps telemetry"| node_telemetry
node_animation -->|"animates telemetry"| node_telemetry

click node_download "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/scripts/download_data.py"
click node_loader "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/data/fastf1_loader.py"
click node_preprocess "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/data/data_preprocessor.py"
click node_historical "https://github.com/yashpatel2777/f1_race_strategy_predictor/tree/main/data"
click node_fit "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/scripts/fit_degradation.py"
click node_degradation "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/models/tire_degradation.py"
click node_lapmodel "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/models/lap_time_model.py"
click node_config "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/track_database.yaml"
click node_state "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/environment/race_state.py"
click node_simulator "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/environment/race_simulator.py"
click node_environment "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/environment/f1_strategy_env.py"
click node_ppo "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/models/ppo_agent.py"
click node_train "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/scripts/train_agent.py"
click node_baselines "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/models/baselines.py"
click node_evaluate "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/scripts/evaluate_agent.py"
click node_visualize "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/scripts/visualize_race.py"
click node_telemetry "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/data_pipeline/telemetry_loader.py"
click node_plots "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/visualization/telemetry_plots.py"
click node_trackmaps "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/visualization/track_maps.py"
click node_animation "https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/visualization/animator.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_download,node_loader,node_preprocess,node_historical toneBlue
class node_fit,node_degradation,node_lapmodel toneAmber
class node_config,node_state,node_simulator,node_environment,node_ppo,node_train,node_baselines toneMint
class node_evaluate,node_visualize,node_telemetry,node_plots,node_trackmaps,node_animation toneRose
class node_user,node_fastf1 toneIndigo
```

## Components

### Historical Data

- [Download sessions](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/scripts/download_data.py): `scripts/download_data.py`
- [Session loader](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/data/fastf1_loader.py): `src/data/fastf1_loader.py`
- [Lap preprocessing](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/data/data_preprocessor.py): `src/data/data_preprocessor.py`
- [Cached session data](https://github.com/yashpatel2777/f1_race_strategy_predictor/tree/main/data): `data`

### Models

- [Fit degradation](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/scripts/fit_degradation.py): `scripts/fit_degradation.py`
- [Tire degradation](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/models/tire_degradation.py): `src/models/tire_degradation.py`
- [Lap-time model](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/models/lap_time_model.py): `src/models/lap_time_model.py`

### Race Simulation

- [Track configuration](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/track_database.yaml): `track_database.yaml`
- [Race state](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/environment/race_state.py): `src/environment/race_state.py`
- [Race simulator](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/environment/race_simulator.py): `src/environment/race_simulator.py`
- [Gym strategy env](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/environment/f1_strategy_env.py): `src/environment/f1_strategy_env.py`
- [PPO agent](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/models/ppo_agent.py): `src/models/ppo_agent.py`
- [Train agent](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/scripts/train_agent.py): `scripts/train_agent.py`
- [Strategy baselines](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/models/baselines.py): `src/models/baselines.py`

### Evaluation & Visualization

- [Evaluate agent](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/scripts/evaluate_agent.py): `scripts/evaluate_agent.py`
- [Race charts](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/scripts/visualize_race.py): `scripts/visualize_race.py`
- [Telemetry pipeline](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/data_pipeline/telemetry_loader.py): `src/data_pipeline/telemetry_loader.py`
- [Telemetry plots](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/visualization/telemetry_plots.py): `src/visualization/telemetry_plots.py`
- [Track maps](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/visualization/track_maps.py): `src/visualization/track_maps.py`
- [Lap animation](https://github.com/yashpatel2777/f1_race_strategy_predictor/blob/main/src/visualization/animator.py): `src/visualization/animator.py`

### Other components

- **Engineer**
- **FastF1**

## Connections

- Engineer → Download sessions: starts workflow
- Download sessions → Session loader: requests sessions
- Session loader → FastF1: loads session
- Session loader → Cached session data: caches data
- Fit degradation → Lap preprocessing: prepares laps
- Lap preprocessing → Session loader: loads laps
- Fit degradation → Tire degradation: fits model
- Tire degradation → Lap-time model: supplies degradation
- Train agent → PPO agent: trains
- PPO agent → Gym strategy env: learns policy
- Gym strategy env → Race simulator: advances race
- Race simulator → Race state: updates
- Race simulator → Lap-time model: predicts lap time
- Race simulator → Track configuration: reads track settings
- Evaluate agent → PPO agent: loads agent
- Evaluate agent → Strategy baselines: compares strategies
- Evaluate agent → Gym strategy env: runs races
- Race charts → Race simulator: visualizes races
- Telemetry pipeline → Session loader: loads session data
- Telemetry plots → Telemetry pipeline: plots telemetry
- Track maps → Telemetry pipeline: maps telemetry
- Lap animation → Telemetry pipeline: animates telemetry