# amrit-sarker/bpl-win-probability-predictor architecture

> Architecture diagram of the GitHub repository amrit-sarker/bpl-win-probability-predictor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amrit-sarker/bpl-win-probability-predictor
- Repository: https://github.com/amrit-sarker/bpl-win-probability-predictor

## Overview

1. **What this repository is**
   - A small machine-learning project for **ball-by-ball win probability prediction** in the Bangladesh Premier League (BPL).
   - It is split into two clear phases: **offline model training** and **online/scripted inference**.

2. **Core runtime boundary**
   - The only executable runtime component in the repo is **`predict.py`**.
   - The trained model is stored separately in **`bpl_predictor.pkl`**, so inference does not retrain anything at runtime.

3. **Training subsystem**
   - **`bpl_win_predictor.ipynb`** contains the full data cleaning, feature engineering, and model training workflow.
   - This notebook is the source of the model artifact and is where the architecture’s learning logic lives.

4. **Model artifact**
   - **`bpl_predictor.pkl`** is the serialized trained model, described as the project’s “brain.”
   - The README indicates the model is a **Logistic Regression** classifier with about **82.28% accuracy**.

5. **Data source and preprocessing boundary**
   - Historical match data was collected from **Cricsheet JSON** files.
   - The training set spans **2012–2025** and includes **435 matches**.
   - The raw source data is not stored as JSON in the repo; instead, the repo keeps a processed CSV artifact.

6. **Prepared dataset artifact**
   - **`bpl_all_matches.csv`** appears to be the consolidated dataset used for analysis/training.
   - This file likely represents the boundary between raw external match feeds and the cleaned modeling dataset.

7. **Inference flow**
   - `predict.py` takes match-state inputs such as:
     - batting team
     - bowling team
     - venue
     - target
     - current runs
     - wickets lost
     - current over and ball
   - These inputs are passed into the loaded pickle model to produce the **chasing team’s win probability**.

8. **Input normalization constraint**
   - The model expects **city-based labels only**, not full franchise or venue names.
   - This is an important architectural constraint because it means the inference layer depends on the exact categorical encoding used during training.

9. **Key feature shape**
   - The prediction problem is ball-by-ball and state-based, meaning the model is driven by the current match situation rather than a full sequence model.
   - The critical state variables are score, wickets, overs, target, teams, and venue.

10. **External dependencies**
   - The repo’s functional dependencies are lightweight: **pandas** and **scikit-learn**.
   - The trained artifact and inference script together imply a standard Python ML deployment pattern, not a web service or API server.

11. **Validation context**
   - The README mentions informal comparison against **ESPN Cricinfo** during live matches.
   - That is validation context only; it is not part of the repo’s runtime architecture.

12. **Best way to draw the architecture**
   - Draw three main blocks:
     - **Data ingestion/prep** from Cricsheet into a cleaned dataset
     - **Training notebook** producing the pickle model
     - **Prediction script** consuming user inputs plus the pickle model to output win probability
   - The central boundary is the transition from **offline training artifacts** to **runtime inference**.

Main entry points: [`predict.py`](https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/predict.py) (Predict script), [`bpl_win_predictor.ipynb`](https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/bpl_win_predictor.ipynb) (Training notebook), [`bpl_all_matches.csv`](https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/bpl_all_matches.csv) (Match CSV), [`bpl_predictor.pkl`](https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/bpl_predictor.pkl) (Logistic model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Data prep"]
  node_n1["Cricsheet data<br/>external source"]
end

subgraph group_g2["Training"]
  node_n3["Training notebook<br/>offline training"]
  node_n4{{"Feature logic<br/>state features"}}
  node_n9{{"Dependencies<br/>python ml stack"}}
end

subgraph group_g3["Runtime"]
  node_n6["Predict script<br/>inference script<br/>[predict.py]"]
  node_n7{{"Match inputs<br/>runtime inputs"}}
  node_n8(("Win probability<br/>prediction output"))
end

subgraph group_g4["Artifacts"]
  node_n2["Match CSV<br/>prepared dataset"]
  node_n5[("Logistic model<br/>serialized classifier<br/>[bpl_predictor.pkl]")]
end

node_n1 -->|"consolidate"| node_n2
node_n2 -->|"train from"| node_n3
node_n3 -->|"engineer"| node_n4
node_n4 -->|"fit model"| node_n5
node_n9 -.->|"support"| node_n3
node_n9 -.->|"support"| node_n6
node_n7 -->|"feed"| node_n6
node_n5 -->|"load"| node_n6
node_n6 -->|"emit"| node_n8

click node_n2 "https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/bpl_all_matches.csv"
click node_n3 "https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/bpl_win_predictor.ipynb"
click node_n5 "https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/bpl_predictor.pkl"
click node_n6 "https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/predict.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_n1 toneBlue
class node_n3,node_n4,node_n9 toneAmber
class node_n6,node_n7,node_n8 toneMint
class node_n2,node_n5 toneRose
```

## Components

### Data prep

Raw match feeds are consolidated into the training dataset.

- **Cricsheet data**: external source · Historical BPL match feeds used to build the dataset.

### Training

Offline model-building workflow.

- [Training notebook](https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/bpl_win_predictor.ipynb): offline training · Data cleaning, feature engineering, and model fitting workflow. · `bpl_win_predictor.ipynb`
- **Feature logic**: state features · Encodes match-state variables such as teams, venue, target, runs, wickets, and over/ball.
- **Dependencies**: python ml stack · pandas and scikit-learn support data handling and model training/inference.

### Runtime

Scripted prediction path used for inference.

- [Predict script](https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/predict.py): inference script · Loads the trained model and produces win probabilities from live match inputs. · `predict.py`
- **Match inputs**: runtime inputs · Batting team, bowling team, venue, target, runs, wickets, overs, and ball.
- **Win probability**: prediction output · Chasing team win probability returned by the inference script.

### Artifacts

Persisted dataset and serialized model.

- [Match CSV](https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/bpl_all_matches.csv): prepared dataset · Consolidated ball-by-ball dataset used for analysis and training. · `bpl_all_matches.csv`
- [Logistic model](https://github.com/amrit-sarker/bpl-win-probability-predictor/blob/main/bpl_predictor.pkl): serialized classifier · Trained win-probability model saved as a pickle artifact. · `bpl_predictor.pkl`

## Connections

- Cricsheet data → Match CSV: consolidate · Historical JSON feeds are transformed into the prepared CSV dataset.
- Match CSV → Training notebook: train from · The notebook consumes the consolidated dataset.
- Training notebook → Feature logic: engineer · Training builds the state-based features used by the classifier.
- Feature logic → Logistic model: fit model · Feature set is used to train the logistic regression model.
- Dependencies → Training notebook: support · Training relies on the Python ML stack.
- Dependencies → Predict script: support · Inference relies on the same lightweight Python dependencies.
- Match inputs → Predict script: feed · User-supplied match state is passed into the prediction script.
- Logistic model → Predict script: load · The script loads the serialized model artifact at runtime.
- Predict script → Win probability: emit · Script outputs the chasing team's win probability.