# shapniljoy/delivery-time-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/shapniljoy/delivery-time-prediction
- Repository: https://github.com/shapniljoy/delivery-time-prediction

## Overview

1. **Repository purpose**
   - This is a **Python-based machine learning research repo** for predicting **Swiggy food delivery time**.
   - The repo is organized around an **offline experimentation workflow** rather than a running application or API.

2. **Primary data boundary**
   - The dataset is managed as a **versioned artifact with DVC**.
   - `data/raw/swiggy.csv.dvc` points to the raw source data, while `data/processed/cleaned_swiggy.csv` holds the cleaned modeling dataset.
   - `data/interim`, `data/external`, and `data/processed` separate raw inputs, intermediate transformations, and final training-ready data.

3. **Notebook-driven analysis and modeling**
   - Most of the active experimentation lives in `notebooks/`.
   - The notebook set maps closely to the ML lifecycle:
     - EDA and missing-value inspection
     - data cleaning and imputation
     - feature selection
     - baseline model selection
     - hyperparameter tuning for multiple model families
     - final stacked model assembly
   - `notebooks/Data_cleaning_utils.py` is the main reusable helper outside the notebooks.

4. **Modeling architecture**
   - The final predictive system is a **stacked regression ensemble**.
   - Base learners are **CatBoost, LightGBM, and Random Forest**.
   - A **Lasso regression meta-learner** combines their out-of-fold predictions.
   - The repo also includes a smaller **ANN experiment**, but the tree-based ensemble is the selected final architecture.

5. **Feature engineering and selection flow**
   - The project explicitly evaluates **imputation vs row dropping** and concludes that dropping missing rows performed better.
   - Feature selection was explored with **Random Forest importance, GBM importance, and RFE**.
   - The modeling set keeps the full feature set for final robustness, even though a small subset explains most importance.

6. **Artifacts and outputs**
   - `models/` is the designated home for saved model artifacts, though the tree shows it as mostly empty in source control.
   - `reports/EDA_Report.pdf` captures the exploratory analysis output.
   - `reports/figures/` is reserved for generated plots and visual assets.
   - `notebooks/catboost_info/` contains CatBoost training logs and metrics artifacts, showing that some experiment outputs are captured directly from training runs.

7. **Reusable source package**
   - `src/` is structured as a standard Python package with logical boundaries:
     - `src/data` for data access and preparation
     - `src/features` for feature logic
     - `src/models` for training/inference/model utilities
     - `src/visualization` for plotting/reporting helpers
   - These directories are mostly scaffolding in the tree, but they define the intended productionization boundary beyond notebooks.

8. **Experiment tracking and reproducibility**
   - The README states that the final model and metrics were tracked with **MLflow** and **DagsHub**.
   - This means the project treats model training as a **repeatable experiment pipeline** with external tracking/versioning, not just local notebook outputs.

9. **Project orchestration and developer tooling**
   - `Makefile`, `tox.ini`, and `test_environment.py` provide environment and quality checks.
   - `requirements.txt`, `requirement-dev.txt`, and `requirement-dockers.txt` indicate separate dependency sets for runtime, development, and containerized execution.
   - `setup.py` makes the package installable as a Python project.

10. **Documentation layer**
   - `docs/` is a Sphinx documentation site, with pages for getting started and commands.
   - This suggests the repo is meant to be understandable and reproducible by other engineers, not just the original notebook author.
   - `extract_notebooks.py` and `notebook_summaries.txt` imply an effort to summarize notebook work into more durable documentation.

11. **End-to-end data flow**
   - The effective pipeline is:
     - raw Swiggy data enters via DVC
     - cleaning and missing-value handling produce a processed CSV
     - EDA and feature selection define the modeling inputs
     - multiple regressors are trained and tuned
     - stacked ensemble predictions are evaluated
     - final metrics and artifacts are stored in reports/models/tracking systems

12. **Architectural takeaway**
   - The repo’s main boundary is between **data/experimentation** and **reusable ML code**.
   - The notebooks hold the research workflow; `src/` and the artifact directories are the scaffold for a more modular, reproducible ML pipeline.

Main entry points: [`notebooks/Final_model.ipynb`](https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/Final_model.ipynb) (Final stack), [`notebooks/Feature Selection.ipynb`](https://github.com/shapniljoy/delivery-time-prediction/blob/HEAD/notebooks/Feature%20Selection.ipynb) (Feature selection), [`data/processed/cleaned_swiggy.csv`](https://github.com/shapniljoy/delivery-time-prediction/blob/main/data/processed/cleaned_swiggy.csv) (Cleaned dataset), [`notebooks/Data Cleaing.ipynb`](https://github.com/shapniljoy/delivery-time-prediction/blob/HEAD/notebooks/Data%20Cleaing.ipynb) (Cleaning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_data["Data & artifacts"]
  node_node_dvc_raw[("Raw Swiggy data<br/>DVC artifact<br/>[swiggy.csv.dvc]")]
  node_node_data_interim[("Interim data<br/>staging data")]
  node_node_data_processed[("Cleaned dataset<br/>training data<br/>[cleaned_swiggy.csv]")]
  node_node_reports["Reports<br/>analysis outputs"]
  node_node_models[("Saved models<br/>artifacts")]
  node_node_tracking(("MLflow / DagsHub<br/>experiment tracking"))
end

subgraph group_grp_research["Notebook workflow"]
  node_node_eda["EDA<br/>notebook<br/>[EDA.ipynb]"]
  node_node_missing["Missing values<br/>notebook"]
  node_node_cleaning["Cleaning<br/>notebook<br/>[Data Cleaing.ipynb]"]
  node_node_imputation["Imputation<br/>notebook<br/>[Imputation.ipynb]"]
  node_node_featuresel["Feature selection<br/>notebook"]
  node_node_baseline["Baselines<br/>notebook"]
  node_node_tuning{{"Model tuning<br/>notebook cluster"}}
  node_node_ann["ANN trial<br/>experiment notebook<br/>[ANN.ipynb]"]
  node_node_final["Final stack<br/>ensemble notebook<br/>[Final_model.ipynb]"]
  node_node_utils["Cleaning utils<br/>notebook helper"]
end

subgraph group_grp_code["Reusable package"]
  node_node_src_data["src.data"]
  node_node_src_features["src.features"]
  node_node_src_models["src.models"]
  node_node_src_viz["src.visualization"]
end

subgraph group_grp_ops["Docs & tooling"]
  node_node_docs["Docs site<br/>Sphinx docs"]
  node_node_make["Makefile<br/>build tooling"]
  node_node_setup["Packaging<br/>[setup.py]"]
  node_node_tests(("Env checks<br/>quality checks"))
end

node_node_dvc_raw -->|"stage"| node_node_data_interim
node_node_data_interim -->|"feed"| node_node_cleaning
node_node_cleaning -->|"produce"| node_node_data_processed
node_node_missing -->|"inform"| node_node_imputation
node_node_eda -->|"guide"| node_node_featuresel
node_node_imputation -->|"compare"| node_node_featuresel
node_node_data_processed -->|"train"| node_node_baseline
node_node_data_processed -->|"train"| node_node_tuning
node_node_featuresel -->|"shape"| node_node_tuning
node_node_tuning -->|"assemble"| node_node_final
node_node_baseline -->|"compare"| node_node_final
node_node_ann -.->|"side experiment"| node_node_final
node_node_final -->|"log"| node_node_tracking
node_node_final -->|"persist"| node_node_models
node_node_final -->|"report"| node_node_reports
node_node_utils -->|"support"| node_node_cleaning
node_node_utils -->|"support"| node_node_imputation
node_node_src_data -.->|"wrap"| node_node_dvc_raw
node_node_src_features -.->|"encapsulate"| node_node_featuresel
node_node_src_models -.->|"encapsulate"| node_node_final
node_node_src_viz -.->|"generate"| node_node_reports
node_node_docs -->|"document"| node_node_reports
node_node_make -->|"orchestrate"| node_node_setup
node_node_tests -->|"validate"| node_node_setup

click node_node_dvc_raw "https://github.com/shapniljoy/delivery-time-prediction/blob/main/data/raw/swiggy.csv.dvc"
click node_node_data_interim "https://github.com/shapniljoy/delivery-time-prediction/tree/main/data/interim"
click node_node_data_processed "https://github.com/shapniljoy/delivery-time-prediction/blob/main/data/processed/cleaned_swiggy.csv"
click node_node_reports "https://github.com/shapniljoy/delivery-time-prediction/tree/main/reports"
click node_node_models "https://github.com/shapniljoy/delivery-time-prediction/tree/main/models"
click node_node_eda "https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/EDA.ipynb"
click node_node_missing "https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/missing Values Inspection.ipynb"
click node_node_cleaning "https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/Data Cleaing.ipynb"
click node_node_imputation "https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/Imputation.ipynb"
click node_node_featuresel "https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/Feature Selection.ipynb"
click node_node_baseline "https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/Baseline Model Selection.ipynb"
click node_node_ann "https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/ANN.ipynb"
click node_node_final "https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/Final_model.ipynb"
click node_node_utils "https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/Data_cleaning_utils.py"
click node_node_src_data "https://github.com/shapniljoy/delivery-time-prediction/tree/main/src/data"
click node_node_src_features "https://github.com/shapniljoy/delivery-time-prediction/tree/main/src/features"
click node_node_src_models "https://github.com/shapniljoy/delivery-time-prediction/tree/main/src/models"
click node_node_src_viz "https://github.com/shapniljoy/delivery-time-prediction/tree/main/src/visualization"
click node_node_docs "https://github.com/shapniljoy/delivery-time-prediction/tree/main/docs"
click node_node_make "https://github.com/shapniljoy/delivery-time-prediction/tree/main/Makefile"
click node_node_setup "https://github.com/shapniljoy/delivery-time-prediction/blob/main/setup.py"
click node_node_tests "https://github.com/shapniljoy/delivery-time-prediction/blob/main/test_environment.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_node_dvc_raw,node_node_data_interim,node_node_data_processed,node_node_reports,node_node_models,node_node_tracking toneBlue
class node_node_eda,node_node_missing,node_node_cleaning,node_node_imputation,node_node_featuresel,node_node_baseline,node_node_tuning,node_node_ann,node_node_final,node_node_utils toneAmber
class node_node_src_data,node_node_src_features,node_node_src_models,node_node_src_viz toneMint
class node_node_docs,node_node_make,node_node_setup,node_node_tests toneRose
```

## Components

### Data & artifacts

Versioned inputs, processed datasets, and persisted experiment outputs.

- [Raw Swiggy data](https://github.com/shapniljoy/delivery-time-prediction/blob/main/data/raw/swiggy.csv.dvc): DVC artifact · Versioned raw source dataset tracked through DVC. · `data/raw/swiggy.csv.dvc`
- [Interim data](https://github.com/shapniljoy/delivery-time-prediction/tree/main/data/interim): staging data · Intermediate transformed data kept between raw and cleaned datasets. · `data/interim`
- [Cleaned dataset](https://github.com/shapniljoy/delivery-time-prediction/blob/main/data/processed/cleaned_swiggy.csv): training data · Training-ready cleaned CSV used for modeling experiments. · `data/processed/cleaned_swiggy.csv`
- [Reports](https://github.com/shapniljoy/delivery-time-prediction/tree/main/reports): analysis outputs · EDA report and generated figures for sharing results. · `reports`
- [Saved models](https://github.com/shapniljoy/delivery-time-prediction/tree/main/models): artifacts · Directory reserved for persisted model artifacts and exports. · `models`
- **MLflow / DagsHub**: experiment tracking · External tracking and versioning for runs, metrics, and model artifacts.

### Notebook workflow

Exploratory analysis, cleaning, selection, tuning, and final ensemble assembly.

- [EDA](https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/EDA.ipynb): notebook · Exploratory analysis and missing-value inspection. · `notebooks/EDA.ipynb`
- [Missing values](https://github.com/shapniljoy/delivery-time-prediction/blob/HEAD/notebooks/missing%20Values%20Inspection.ipynb): notebook · Focused inspection of missingness patterns and data quality. · `notebooks/missing Values Inspection.ipynb`
- [Cleaning](https://github.com/shapniljoy/delivery-time-prediction/blob/HEAD/notebooks/Data%20Cleaing.ipynb): notebook · Data cleaning and transformation workflow. · `notebooks/Data Cleaing.ipynb`
- [Imputation](https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/Imputation.ipynb): notebook · Comparison of imputation strategies versus dropping rows. · `notebooks/Imputation.ipynb`
- [Feature selection](https://github.com/shapniljoy/delivery-time-prediction/blob/HEAD/notebooks/Feature%20Selection.ipynb): notebook · Selection using importance methods and RFE. · `notebooks/Feature Selection.ipynb`
- [Baselines](https://github.com/shapniljoy/delivery-time-prediction/blob/HEAD/notebooks/Baseline%20Model%20Selection.ipynb): notebook · Baseline model selection and early model comparisons. · `notebooks/Baseline Model Selection.ipynb`
- **Model tuning**: notebook cluster · Hyperparameter search for CatBoost, LightGBM, Random Forest, and stacking.
- [ANN trial](https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/ANN.ipynb): experiment notebook · Smaller neural-network experiment alongside tree-based models. · `notebooks/ANN.ipynb`
- [Final stack](https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/Final_model.ipynb): ensemble notebook · Final stacked regression assembly and evaluation. · `notebooks/Final_model.ipynb`
- [Cleaning utils](https://github.com/shapniljoy/delivery-time-prediction/blob/main/notebooks/Data_cleaning_utils.py): notebook helper · Reusable cleaning and preprocessing helpers shared across notebooks. · `notebooks/Data_cleaning_utils.py`

### Reusable package

Installable Python package boundaries for data, features, models, and visualization.

- [src.data](https://github.com/shapniljoy/delivery-time-prediction/tree/main/src/data): package · Package boundary for data access and preparation code. · `src/data`
- [src.features](https://github.com/shapniljoy/delivery-time-prediction/tree/main/src/features): package · Feature engineering and feature logic package boundary. · `src/features`
- [src.models](https://github.com/shapniljoy/delivery-time-prediction/tree/main/src/models): package · Training, inference, and model utility package boundary. · `src/models`
- [src.visualization](https://github.com/shapniljoy/delivery-time-prediction/tree/main/src/visualization): package · Plotting and reporting helpers package boundary. · `src/visualization`

### Docs & tooling

Documentation, environment setup, packaging, and project maintenance tooling.

- [Docs site](https://github.com/shapniljoy/delivery-time-prediction/tree/main/docs): Sphinx docs · Project documentation site with getting started and command guides. · `docs`
- [Makefile](https://github.com/shapniljoy/delivery-time-prediction/tree/main/Makefile): build tooling · Project automation for common development and workflow commands. · `Makefile`
- [Packaging](https://github.com/shapniljoy/delivery-time-prediction/blob/main/setup.py): python packaging · Installable project setup and dependency management entrypoint. · `setup.py`
- [Env checks](https://github.com/shapniljoy/delivery-time-prediction/blob/main/test_environment.py): quality checks · Environment and tooling validation for development reproducibility. · `test_environment.py`

## Connections

- Raw Swiggy data → Interim data: stage · Raw versioned data is prepared into intermediate form.
- Interim data → Cleaning: feed · Intermediate data is consumed by cleaning workflows.
- Cleaning → Cleaned dataset: produce · Cleaning produces the training-ready CSV.
- Missing values → Imputation: inform · Missingness analysis informs imputation experiments.
- EDA → Feature selection: guide · EDA findings guide feature selection choices.
- Imputation → Feature selection: compare · Imputation is contrasted with row-dropping before selection.
- Cleaned dataset → Baselines: train · Cleaned data feeds baseline model evaluation.
- Cleaned dataset → Model tuning: train · Training data feeds hyperparameter optimization.
- Feature selection → Model tuning: shape · Selected feature set constrains tuning experiments.
- Model tuning → Final stack: assemble · Tuned base learners are combined in the final stack.
- Baselines → Final stack: compare · Baseline results are used as reference for the final model.
- ANN trial → Final stack: side experiment · ANN work runs alongside the selected ensemble path.
- Final stack → MLflow / DagsHub: log · Final metrics and artifacts are tracked externally.
- Final stack → Saved models: persist · Final model artifacts are saved under the models directory.
- Final stack → Reports: report · Final results are summarized into reports and figures.
- Cleaning utils → Cleaning: support · Reusable helper functions support notebook cleaning steps.
- Cleaning utils → Imputation: support · Shared preprocessing utilities support imputation experiments.
- src.data → Raw Swiggy data: wrap · Package-level data code is expected to operate on raw inputs.
- src.features → Feature selection: encapsulate · Feature package is the reusable home for feature logic.
- src.models → Final stack: encapsulate · Model package is the reusable home for training and inference logic.
- src.visualization → Reports: generate · Visualization helpers support report and figure generation.
- Docs site → Reports: document · Docs complement the analytical report outputs.
- Makefile → Packaging: orchestrate · Build automation and packaging support project execution.
- Env checks → Packaging: validate · Environment checks validate the installable project setup.