# kumudha818/f1 architecture

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

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

## Overview

F1 PitLab loads race schedules and sessions from FastF1, extracts pit stops and tyre stints, and presents analysis through GUI or CLI. Analysis includes driver/team comparisons, strategy visualizations, ML duration predictions, anomaly detection, tyre degradation, and pit-window suggestions. Database persistence supports historical and prediction analytics; model training is available in both interfaces. The graph follows documented capabilities, but unsampled GUI wiring and some database integrations are left out where exact calls cannot be confirmed.

Main entry points: [`src/analysis.py`](https://github.com/kumudha818/f1/blob/main/src/analysis.py) (Analysis Runner), [`src/cli/race_selection.py`](https://github.com/kumudha818/f1/blob/main/src/cli/race_selection.py) (Terminal UI), [`src/database/repository.py`](https://github.com/kumudha818/f1/blob/main/src/database/repository.py) (Data Repository), [`src/gui/race_selection.py`](https://github.com/kumudha818/f1/blob/main/src/gui/race_selection.py) (Desktop UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_gui["Desktop UI<br/>[race_selection.py]"]
  node_cli["Terminal UI<br/>[race_selection.py]"]
  node_training_ui["Training Dialog<br/>[ml_training.py]"]
end

subgraph group_race_data["Race Data"]
  node_race_select["Race Selection<br/>[race_selection.py]"]
  node_data_loader["Session &amp; Cache<br/>[f1_data.py]"]
  node_pit_extract["Pit Stop Extraction<br/>[f1_data.py]"]
  node_tyre_stints["Tyre Stints<br/>[f1_data.py]"]
end

subgraph group_analysis["Analysis &amp; Strategy"]
  node_analysis_runner["Analysis Runner<br/>[analysis.py]"]
  node_charts["Interactive Charts<br/>[visualizations.py]"]
  node_basic_ml["Duration Predictor<br/>[predictor.py]"]
  node_advanced_ml["Enhanced Models"]
  node_training_data["Training Data"]
end

subgraph group_persistence["Models &amp; Persistence"]
  node_db_repo["Data Repository<br/>[repository.py]"]
  node_db_models["Race Data Models<br/>[models.py]"]
  node_db_connection["Database Connection<br/>[connection.py]"]
end

node_user(("Analyst"))
node_fastf1["FastF1"]
node_db[("SQLite / PostgreSQL")]
node_model_file["Saved ML Model"]

node_user -->|"selects race"| node_gui
node_user -->|"selects race"| node_cli
node_gui -->|"chooses event"| node_race_select
node_race_select -->|"requests schedule"| node_fastf1
node_race_select -->|"loads session"| node_data_loader
node_cli -->|"requests schedule"| node_fastf1
node_cli -->|"loads session"| node_fastf1
node_data_loader -->|"loads and caches"| node_fastf1
node_data_loader -->|"provides session"| node_pit_extract
node_pit_extract -->|"uses lap data"| node_tyre_stints
node_gui -->|"runs analysis"| node_analysis_runner
node_cli -->|"runs analysis"| node_analysis_runner
node_analysis_runner -->|"predicts and flags"| node_basic_ml
node_analysis_runner -->|"requests strategy"| node_advanced_ml
node_analysis_runner -->|"renders analysis"| node_charts
node_training_ui -->|"collects samples"| node_training_data
node_training_ui -->|"trains model"| node_advanced_ml
node_training_data -->|"collects race data"| node_fastf1
node_basic_ml -->|"loads or saves"| node_model_file
node_advanced_ml -->|"saves model"| node_model_file
node_db_repo -->|"queries entities"| node_db_models
node_db_repo -->|"uses sessions"| node_db_connection
node_db_connection -->|"connects"| node_db
node_db_repo -->|"reads and writes"| node_db

click node_gui "https://github.com/kumudha818/f1/blob/main/src/gui/race_selection.py"
click node_cli "https://github.com/kumudha818/f1/blob/main/src/cli/race_selection.py"
click node_training_ui "https://github.com/kumudha818/f1/blob/main/src/gui/ml_training.py"
click node_race_select "https://github.com/kumudha818/f1/blob/main/src/gui/race_selection.py"
click node_data_loader "https://github.com/kumudha818/f1/blob/main/src/f1_data.py"
click node_pit_extract "https://github.com/kumudha818/f1/blob/main/src/f1_data.py"
click node_tyre_stints "https://github.com/kumudha818/f1/blob/main/src/f1_data.py"
click node_analysis_runner "https://github.com/kumudha818/f1/blob/main/src/analysis.py"
click node_charts "https://github.com/kumudha818/f1/blob/main/src/charts/visualizations.py"
click node_basic_ml "https://github.com/kumudha818/f1/blob/main/src/ml/predictor.py"
click node_advanced_ml "https://github.com/kumudha818/f1/blob/main/src/ml/enhanced_predictor.py"
click node_training_data "https://github.com/kumudha818/f1/blob/main/src/ml/enhanced_predictor.py"
click node_db_repo "https://github.com/kumudha818/f1/blob/main/src/database/repository.py"
click node_db_models "https://github.com/kumudha818/f1/blob/main/src/database/models.py"
click node_db_connection "https://github.com/kumudha818/f1/blob/main/src/database/connection.py"
click node_model_file "https://github.com/kumudha818/f1/blob/main/ml_models/pitstop_predictor.pkl"

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_gui,node_cli,node_training_ui toneBlue
class node_race_select,node_data_loader,node_pit_extract,node_tyre_stints,node_db toneAmber
class node_analysis_runner,node_charts,node_basic_ml,node_advanced_ml,node_training_data toneMint
class node_db_repo,node_db_models,node_db_connection toneRose
class node_user,node_fastf1,node_model_file toneIndigo
```

## Components

### User Interfaces

- [Desktop UI](https://github.com/kumudha818/f1/blob/main/src/gui/race_selection.py): `src/gui/race_selection.py`
- [Terminal UI](https://github.com/kumudha818/f1/blob/main/src/cli/race_selection.py): `src/cli/race_selection.py`
- [Training Dialog](https://github.com/kumudha818/f1/blob/main/src/gui/ml_training.py): `src/gui/ml_training.py`

### Race Data

- [Race Selection](https://github.com/kumudha818/f1/blob/main/src/gui/race_selection.py): `src/gui/race_selection.py`
- [Session & Cache](https://github.com/kumudha818/f1/blob/main/src/f1_data.py): `src/f1_data.py`
- [Pit Stop Extraction](https://github.com/kumudha818/f1/blob/main/src/f1_data.py): `src/f1_data.py`
- [Tyre Stints](https://github.com/kumudha818/f1/blob/main/src/f1_data.py): `src/f1_data.py`

### Analysis & Strategy

- [Analysis Runner](https://github.com/kumudha818/f1/blob/main/src/analysis.py): `src/analysis.py`
- [Interactive Charts](https://github.com/kumudha818/f1/blob/main/src/charts/visualizations.py): `src/charts/visualizations.py`
- [Duration Predictor](https://github.com/kumudha818/f1/blob/main/src/ml/predictor.py): `src/ml/predictor.py`
- [Enhanced Models](https://github.com/kumudha818/f1/blob/main/src/ml/enhanced_predictor.py): `src/ml/enhanced_predictor.py`
- [Training Data](https://github.com/kumudha818/f1/blob/main/src/ml/enhanced_predictor.py): `src/ml/enhanced_predictor.py`

### Models & Persistence

- [Data Repository](https://github.com/kumudha818/f1/blob/main/src/database/repository.py): `src/database/repository.py`
- [Race Data Models](https://github.com/kumudha818/f1/blob/main/src/database/models.py): `src/database/models.py`
- [Database Connection](https://github.com/kumudha818/f1/blob/main/src/database/connection.py): `src/database/connection.py`

### Other components

- **Analyst**
- **FastF1**
- **SQLite / PostgreSQL**
- [Saved ML Model](https://github.com/kumudha818/f1/blob/main/ml_models/pitstop_predictor.pkl): `ml_models/pitstop_predictor.pkl`

## Connections

- Analyst → Desktop UI: selects race
- Analyst → Terminal UI: selects race
- Desktop UI → Race Selection: chooses event
- Race Selection → FastF1: requests schedule
- Race Selection → Session & Cache: loads session
- Terminal UI → FastF1: requests schedule
- Terminal UI → FastF1: loads session
- Session & Cache → FastF1: loads and caches
- Session & Cache → Pit Stop Extraction: provides session
- Pit Stop Extraction → Tyre Stints: uses lap data
- Desktop UI → Analysis Runner: runs analysis
- Terminal UI → Analysis Runner: runs analysis
- Analysis Runner → Duration Predictor: predicts and flags
- Analysis Runner → Enhanced Models: requests strategy
- Analysis Runner → Interactive Charts: renders analysis
- Training Dialog → Training Data: collects samples
- Training Dialog → Enhanced Models: trains model
- Training Data → FastF1: collects race data
- Duration Predictor → Saved ML Model: loads or saves
- Enhanced Models → Saved ML Model: saves model
- Data Repository → Race Data Models: queries entities
- Data Repository → Database Connection: uses sessions
- Database Connection → SQLite / PostgreSQL: connects
- Data Repository → SQLite / PostgreSQL: reads and writes