# jayasuriya24/salespulse architecture

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

- Interactive diagram: https://gitdiagram.com/jayasuriya24/salespulse
- Repository: https://github.com/jayasuriya24/salespulse

## Overview

SalesPulse turns official M5 sales, calendar, and price data into a processed retail dataset, evaluates forecasting models, and serves sales analytics and recursive forecasts through a FastAPI dashboard/API. The main runtime path is dataset upload or preparation, feature generation and model training, then API forecast requests using fitted artifacts. The graph also preserves documented baselines, generic uploads, and optional MLflow tracking. Some API implementation is excerpted only partially, so links for unsampled endpoints and integrations are limited to README statements or omitted.

Main entry points: [`app/main.py`](https://github.com/jayasuriya24/salespulse/blob/main/app/main.py) (FastAPI service), [`ml/pipeline.py`](https://github.com/jayasuriya24/salespulse/blob/main/ml/pipeline.py) (M5 processing), [`ml/train.py`](https://github.com/jayasuriya24/salespulse/blob/main/ml/train.py) (Model evaluation), [`scripts/train.py`](https://github.com/jayasuriya24/salespulse/blob/main/scripts/train.py) (Tracking integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_prep_cli["Data preparation CLI<br/>[prepare_data.py]"]
  node_data_pipeline["M5 processing<br/>[pipeline.py]"]
end

subgraph group_modeling["Forecast modeling"]
  node_features["Feature engineering<br/>[pipeline.py]"]
  node_trainer["Model evaluation<br/>[train.py]"]
  node_artifacts[("Dataset and artifacts<br/>[train.py]")]
end

subgraph group_product["SalesPulse application"]
  node_api["FastAPI service<br/>[main.py]"]
  node_dashboard["Browser dashboard<br/>[main.py]"]
  node_analytics["Sales analytics<br/>[main.py]"]
  node_upload_auth["Protected M5 upload<br/>[main.py]"]
  node_forecast["Recursive forecasts<br/>[main.py]"]
end

subgraph group_tracking["Experiment tracking"]
  node_tracking_cli["Tracking integration<br/>[train.py]"]
end

node_user(("Analyst"))
node_m5_files["M5 CSV data"]
node_browser(("Browser client"))
node_mlflow[("MLflow")]

node_user -->|"uses"| node_dashboard
node_browser -->|"requests"| node_api
node_api -->|"serves"| node_dashboard
node_user -->|"provides"| node_m5_files
node_m5_files -->|"prepares"| node_prep_cli
node_prep_cli -->|"calls"| node_data_pipeline
node_data_pipeline -->|"writes dataset"| node_artifacts
node_upload_auth -->|"processes"| node_data_pipeline
node_api -->|"routes upload"| node_upload_auth
node_api -->|"trains on upload"| node_trainer
node_data_pipeline -->|"provides data"| node_features
node_trainer -->|"calls"| node_features
node_trainer -->|"writes models and report"| node_artifacts
node_api -.->|"reads dataset and models"| node_artifacts
node_api -->|"serves"| node_analytics
node_dashboard -->|"displays"| node_analytics
node_api -->|"routes request"| node_forecast
node_dashboard -->|"requests"| node_forecast
node_forecast -->|"loads model"| node_artifacts
node_tracking_cli -->|"runs training"| node_trainer
node_tracking_cli -->|"logs experiments"| node_mlflow

click node_prep_cli "https://github.com/jayasuriya24/salespulse/blob/main/scripts/prepare_data.py"
click node_data_pipeline "https://github.com/jayasuriya24/salespulse/blob/main/ml/pipeline.py"
click node_features "https://github.com/jayasuriya24/salespulse/blob/main/ml/pipeline.py"
click node_trainer "https://github.com/jayasuriya24/salespulse/blob/main/ml/train.py"
click node_artifacts "https://github.com/jayasuriya24/salespulse/blob/main/ml/train.py"
click node_tracking_cli "https://github.com/jayasuriya24/salespulse/blob/main/scripts/train.py"
click node_api "https://github.com/jayasuriya24/salespulse/blob/main/app/main.py"
click node_dashboard "https://github.com/jayasuriya24/salespulse/blob/main/app/main.py"
click node_analytics "https://github.com/jayasuriya24/salespulse/blob/main/app/main.py"
click node_upload_auth "https://github.com/jayasuriya24/salespulse/blob/main/app/main.py"
click node_forecast "https://github.com/jayasuriya24/salespulse/blob/main/app/main.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_prep_cli,node_data_pipeline,node_browser toneBlue
class node_features,node_trainer,node_artifacts,node_mlflow toneAmber
class node_api,node_dashboard,node_analytics,node_upload_auth,node_forecast toneMint
class node_tracking_cli toneRose
class node_user,node_m5_files toneIndigo
```

## Components

### Data ingestion

- [Data preparation CLI](https://github.com/jayasuriya24/salespulse/blob/main/scripts/prepare_data.py): `scripts/prepare_data.py`
- [M5 processing](https://github.com/jayasuriya24/salespulse/blob/main/ml/pipeline.py): `ml/pipeline.py`

### Forecast modeling

- [Feature engineering](https://github.com/jayasuriya24/salespulse/blob/main/ml/pipeline.py): `ml/pipeline.py`
- [Model evaluation](https://github.com/jayasuriya24/salespulse/blob/main/ml/train.py): `ml/train.py`
- [Dataset and artifacts](https://github.com/jayasuriya24/salespulse/blob/main/ml/train.py): `ml/train.py`

### SalesPulse application

- [FastAPI service](https://github.com/jayasuriya24/salespulse/blob/main/app/main.py): `app/main.py`
- [Browser dashboard](https://github.com/jayasuriya24/salespulse/blob/main/app/main.py): `app/main.py`
- [Sales analytics](https://github.com/jayasuriya24/salespulse/blob/main/app/main.py): `app/main.py`
- [Protected M5 upload](https://github.com/jayasuriya24/salespulse/blob/main/app/main.py): `app/main.py`
- [Recursive forecasts](https://github.com/jayasuriya24/salespulse/blob/main/app/main.py): `app/main.py`

### Experiment tracking

- [Tracking integration](https://github.com/jayasuriya24/salespulse/blob/main/scripts/train.py): `scripts/train.py`

### Other components

- **Analyst**
- **M5 CSV data**
- **Browser client**
- **MLflow**

## Connections

- Analyst → Browser dashboard: uses (evidence: `README.md`)
- Browser client → FastAPI service: requests (evidence: `README.md`)
- FastAPI service → Browser dashboard: serves (evidence: `app/main.py`)
- Analyst → M5 CSV data: provides (evidence: `README.md`)
- M5 CSV data → Data preparation CLI: prepares (evidence: `README.md`)
- Data preparation CLI → M5 processing: calls (evidence: `scripts/prepare_data.py`)
- M5 processing → Dataset and artifacts: writes dataset (evidence: `ml/pipeline.py`)
- Protected M5 upload → M5 processing: processes (evidence: `README.md`)
- FastAPI service → Protected M5 upload: routes upload (evidence: `app/main.py`)
- FastAPI service → Model evaluation: trains on upload (evidence: `app/main.py`)
- M5 processing → Feature engineering: provides data (evidence: `README.md`)
- Model evaluation → Feature engineering: calls (evidence: `ml/train.py`)
- Model evaluation → Dataset and artifacts: writes models and report (evidence: `ml/train.py`)
- FastAPI service → Dataset and artifacts: reads dataset and models (evidence: `app/main.py`)
- FastAPI service → Sales analytics: serves (evidence: `app/main.py`)
- Browser dashboard → Sales analytics: displays (evidence: `README.md`)
- FastAPI service → Recursive forecasts: routes request (evidence: `app/main.py`)
- Browser dashboard → Recursive forecasts: requests (evidence: `README.md`)
- Recursive forecasts → Dataset and artifacts: loads model (evidence: `app/main.py`)
- Tracking integration → Model evaluation: runs training (evidence: `scripts/train.py`)
- Tracking integration → MLflow: logs experiments (evidence: `scripts/train.py`)