# gulkhan92/retaildemand-modeling architecture

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

- Interactive diagram: https://gitdiagram.com/gulkhan92/retaildemand-modeling
- Repository: https://github.com/gulkhan92/retaildemand-modeling

## Overview

RetailDemand-Modeling is a Rossmann retail-sales forecasting project. Its main user-to-result path is the CLI runner: load raw Kaggle tables, engineer aligned features, train and compare tabular models, then write test predictions and run summaries. The runner also produces separate statistical and aggregate time-series baselines. README-described notebook analyses are preserved as a workflow branch; their runtime wiring was not sampled, so no implementation links are asserted for them.

Main entry points: [`main.py`](https://github.com/gulkhan92/retaildemand-modeling/blob/main/main.py) (Pipeline runner), [`src/ml_models.py`](https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/ml_models.py) (Prediction generation), [`notebooks`](https://github.com/gulkhan92/retaildemand-modeling/tree/main/notebooks) (EDA and modeling notebooks), [`data/raw`](https://github.com/gulkhan92/retaildemand-modeling/tree/main/data/raw) (Rossmann raw data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data preparation"]
  node_raw["Rossmann raw data"]
  node_features["Feature tables"]
  node_processed["Processed artifacts"]
end

subgraph group_analysis["Baseline analyses"]
  node_statistical["Statistical baseline"]
  node_timeseries["SARIMAX baseline"]
end

subgraph group_forecast["ML forecasting"]
  node_matrices["ML feature matrices<br/>[ml_models.py]"]
  node_preprocessor["Feature preprocessor<br/>[ml_models.py]"]
  node_trainer["Model training<br/>[ml_models.py]"]
  node_submission["Prediction generation<br/>[ml_models.py]"]
  node_submission_file["Kaggle submission"]
end

subgraph group_workflow["Exploration workflow"]
  node_notebooks["EDA and modeling notebooks"]
  node_reports["Analysis report"]
end

node_user(("Analyst"))
node_runner["Pipeline runner<br/>[main.py]"]

node_user -->|"runs"| node_runner
node_runner -->|"loads"| node_raw
node_runner -->|"builds"| node_features
node_runner -->|"writes tables"| node_processed
node_runner -->|"runs baseline"| node_statistical
node_runner -->|"runs baseline"| node_timeseries
node_runner -->|"builds matrices"| node_matrices
node_runner -->|"builds"| node_preprocessor
node_runner -->|"trains models"| node_trainer
node_runner -->|"generates predictions"| node_submission
node_trainer -->|"selects fitted model"| node_submission
node_submission -->|"writes"| node_submission_file
node_runner -.->|"supports analysis"| node_notebooks
node_notebooks -.->|"documents findings"| node_reports

click node_runner "https://github.com/gulkhan92/retaildemand-modeling/blob/main/main.py"
click node_raw "https://github.com/gulkhan92/retaildemand-modeling/tree/main/data/raw"
click node_features "https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/data_preprocessing.py"
click node_processed "https://github.com/gulkhan92/retaildemand-modeling/tree/main/data/processed"
click node_statistical "https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/statistical_models.py"
click node_timeseries "https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/timeseries_models.py"
click node_matrices "https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/ml_models.py"
click node_preprocessor "https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/ml_models.py"
click node_trainer "https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/ml_models.py"
click node_submission "https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/ml_models.py"
click node_notebooks "https://github.com/gulkhan92/retaildemand-modeling/tree/main/notebooks"
click node_reports "https://github.com/gulkhan92/retaildemand-modeling/blob/main/reports/analysis_summary.pdf"
click node_submission_file "https://github.com/gulkhan92/retaildemand-modeling/tree/main/data/processed"

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_raw,node_features,node_processed toneBlue
class node_statistical,node_timeseries toneAmber
class node_matrices,node_preprocessor,node_trainer,node_submission,node_submission_file toneMint
class node_notebooks,node_reports toneRose
class node_user toneIndigo
class node_runner toneTeal
```

## Components

### Data preparation

- [Rossmann raw data](https://github.com/gulkhan92/retaildemand-modeling/tree/main/data/raw): `data/raw`
- [Feature tables](https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/data_preprocessing.py): `src/data_preprocessing.py`
- [Processed artifacts](https://github.com/gulkhan92/retaildemand-modeling/tree/main/data/processed): `data/processed`

### Baseline analyses

- [Statistical baseline](https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/statistical_models.py): `src/statistical_models.py`
- [SARIMAX baseline](https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/timeseries_models.py): `src/timeseries_models.py`

### ML forecasting

- [ML feature matrices](https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/ml_models.py): `src/ml_models.py`
- [Feature preprocessor](https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/ml_models.py): `src/ml_models.py`
- [Model training](https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/ml_models.py): `src/ml_models.py`
- [Prediction generation](https://github.com/gulkhan92/retaildemand-modeling/blob/main/src/ml_models.py): `src/ml_models.py`
- [Kaggle submission](https://github.com/gulkhan92/retaildemand-modeling/tree/main/data/processed): `data/processed`

### Exploration workflow

- [EDA and modeling notebooks](https://github.com/gulkhan92/retaildemand-modeling/tree/main/notebooks): `notebooks`
- [Analysis report](https://github.com/gulkhan92/retaildemand-modeling/blob/main/reports/analysis_summary.pdf): `reports/analysis_summary.pdf`

### Other components

- **Analyst**
- [Pipeline runner](https://github.com/gulkhan92/retaildemand-modeling/blob/main/main.py): `main.py`

## Connections

- Analyst → Pipeline runner: runs (evidence: `README.md`)
- Pipeline runner → Rossmann raw data: loads
- Pipeline runner → Feature tables: builds (evidence: `main.py`)
- Pipeline runner → Processed artifacts: writes tables (evidence: `main.py`)
- Pipeline runner → Statistical baseline: runs baseline (evidence: `main.py`)
- Pipeline runner → SARIMAX baseline: runs baseline (evidence: `main.py`)
- Pipeline runner → ML feature matrices: builds matrices (evidence: `main.py`)
- Pipeline runner → Feature preprocessor: builds (evidence: `main.py`)
- Pipeline runner → Model training: trains models (evidence: `main.py`)
- Pipeline runner → Prediction generation: generates predictions (evidence: `main.py`)
- Model training → Prediction generation: selects fitted model (evidence: `main.py`)
- Prediction generation → Kaggle submission: writes
- Pipeline runner → EDA and modeling notebooks: supports analysis (evidence: `README.md`)
- EDA and modeling notebooks → Analysis report: documents findings (evidence: `README.md`)