# gpa95/f1_pitstop_predictor architecture

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

- Interactive diagram: https://gitdiagram.com/gpa95/f1_pitstop_predictor
- Repository: https://github.com/gpa95/f1_pitstop_predictor

## Overview

1. This repository is a single-shot Kaggle machine learning workflow, centered around one notebook rather than a multi-module application. The architecture is: raw competition data in, preprocessing and model training in the notebook, predictions out to `submission.csv`.

2. The primary executable artifact is the Jupyter notebook `AAK_Prediction_f1.ipynb` (the README refers to a baseline LightGBM notebook). That notebook contains the full end-to-end pipeline: data loading, encoding, train/validation split, model fitting, evaluation, and test-set inference.

3. The input boundary is the Kaggle competition dataset for F1 pit stop prediction. The problem is structured as binary classification at the lap level: predict whether a driver will pit on the next lap. The training set is large (439k rows) and the test set is similarly structured (188k rows), with about 15 features spanning race context, tire state, and driver identity.

4. A key data-preparation subsystem handles categorical normalization. The repo uses label encoding for `Driver`, `Compound`, and `Race`, while other fields are consumed as numeric features. The README states there are no missing values, so there is no dedicated imputation stage.

5. The split strategy is a stratified 80/20 train-validation split. That matters architecturally because model quality is measured locally before producing the final submission, and the split preserves the target imbalance between pit and no-pit classes.

6. The learning subsystem is a LightGBM binary classifier. This is the core model boundary in the project: tabular features go in, pit probability comes out. The chosen settings are a modest baseline: `num_leaves=31`, `learning_rate=0.05`, `feature_fraction=0.9`, and `num_boost_round=500`.

7. Evaluation is centered on ROC AUC, which is both the competition metric and the notebook’s validation target. The README records a validation AUC of 0.9466 and a public leaderboard AUC of 0.94541, indicating the notebook is designed for offline validation followed by one Kaggle submission.

8. The output boundary is `submission.csv`, which is the only persisted artifact besides the notebook and README. This file contains the final test-set predictions in Kaggle submission format and is the handoff from the modeling pipeline to the competition platform.

9. There is no application server, API layer, database, or streaming component. The repo is a pure offline analytics/training workflow, with execution and orchestration handled inside the notebook environment.

10. The dependency footprint is lightweight and explicitly listed in the README: pandas, numpy, scikit-learn, and lightgbm. These libraries define the runtime stack: data manipulation, encoding/splitting, and gradient-boosted tree training.

11. The main architectural constraint is the class imbalance, roughly 80% no-pit and 20% pit. That affects training and validation design more than system design: the model must learn a rare-event prediction problem from static tabular data.

12. If you were drawing the architecture diagram, it would have one input lane from Kaggle data to the notebook, one preprocessing lane for categorical encoding and split, one model lane for LightGBM training/evaluation, and one output lane to `submission.csv` for Kaggle upload.

Main entry points: [`AAK_Prediction_f1.ipynb`](https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb) (LightGBM), [`README.md`](https://github.com/gpa95/f1_pitstop_predictor/blob/main/README.md) (README), [`submission.csv`](https://github.com/gpa95/f1_pitstop_predictor/blob/main/submission.csv) (submission.csv)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Input"]
  node_n1[("Kaggle data<br/>dataset")]
end

subgraph group_g2["Notebook"]
  node_n2["Load data<br/>pipeline step"]
  node_n3["Encode cats<br/>preprocess"]
  node_n4["Train split"]
  node_n5{{"LightGBM<br/>binary model"}}
  node_n6(("Validate AUC<br/>metric"))
  node_n7["Test inference"]
  node_n10["Core libs<br/>runtime stack"]
end

subgraph group_g3["Output"]
  node_n8["submission.csv<br/>submission file<br/>[submission.csv]"]
  node_n9["README<br/>documentation<br/>[README.md]"]
end

node_n1 -->|"input"| node_n2
node_n2 -->|"prepare"| node_n3
node_n3 -->|"split"| node_n4
node_n4 -->|"fit"| node_n5
node_n5 -->|"score"| node_n6
node_n5 -->|"predict"| node_n7
node_n7 -->|"write"| node_n8
node_n10 -.->|"support"| node_n2
node_n10 -.->|"train"| node_n5
node_n9 -.->|"describe"| node_n5

click node_n2 "https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb"
click node_n3 "https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb"
click node_n4 "https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb"
click node_n5 "https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb"
click node_n6 "https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb"
click node_n7 "https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb"
click node_n8 "https://github.com/gpa95/f1_pitstop_predictor/blob/main/submission.csv"
click node_n9 "https://github.com/gpa95/f1_pitstop_predictor/blob/main/README.md"

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_n1 toneBlue
class node_n2,node_n3,node_n4,node_n5,node_n6,node_n7,node_n10 toneAmber
class node_n8,node_n9 toneMint
```

## Components

### Input

Competition data boundary from Kaggle

- **Kaggle data**: dataset · Raw F1 pit-stop competition data: train and test tables

### Notebook

Single notebook pipeline

- [Load data](https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb): pipeline step · Notebook stage that reads the competition tables · `AAK_Prediction_f1.ipynb`
- [Encode cats](https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb): preprocess · Label encoding for Driver, Compound, and Race · `AAK_Prediction_f1.ipynb`
- [Train split](https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb): split · Stratified 80/20 train-validation split for imbalanced classes · `AAK_Prediction_f1.ipynb`
- [LightGBM](https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb): binary model · Baseline gradient-boosted tree classifier for pit prediction · `AAK_Prediction_f1.ipynb`
- [Validate AUC](https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb): metric · ROC AUC validation used for offline model selection · `AAK_Prediction_f1.ipynb`
- [Test inference](https://github.com/gpa95/f1_pitstop_predictor/blob/main/AAK_Prediction_f1.ipynb): inference · Score the held-out test set and produce submission predictions · `AAK_Prediction_f1.ipynb`
- **Core libs**: runtime stack · pandas, numpy, scikit-learn, and lightgbm used by the notebook

### Output

Submission artifact

- [submission.csv](https://github.com/gpa95/f1_pitstop_predictor/blob/main/submission.csv): submission file · Final Kaggle submission artifact · `submission.csv`
- [README](https://github.com/gpa95/f1_pitstop_predictor/blob/main/README.md): documentation · Project notes, baseline description, and reported scores · `README.md`

## Connections

- Kaggle data → Load data: input · Competition tables feed the notebook pipeline
- Load data → Encode cats: prepare · Raw columns are normalized and encoded
- Encode cats → Train split: split · Prepared features are partitioned into train and validation sets
- Train split → LightGBM: fit · Stratified training data is used to train the classifier
- LightGBM → Validate AUC: score · Validation predictions are evaluated with ROC AUC
- LightGBM → Test inference: predict · Trained model is applied to the test set
- Test inference → submission.csv: write · Final predictions are exported in Kaggle format
- Core libs → Load data: support · Notebook runtime uses the data stack for ingestion and manipulation
- Core libs → LightGBM: train · LightGBM and scikit-learn power model fitting and evaluation
- README → LightGBM: describe · README documents the baseline model and reported results
