# retail-analytical-platform/retail-analytics-ml architecture

> Architecture diagram of the GitHub repository retail-analytical-platform/retail-analytics-ml, 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/retail-analytical-platform/retail-analytics-ml
- Repository: https://github.com/retail-analytical-platform/retail-analytics-ml

## Overview

This repository is an early-stage retail-demand forecasting project, but its implemented workflow currently centers on a CLI data-validation stage: it loads configured tables from a PostgreSQL-compatible database, checks their schema and date coverage, and reports failures. The CLI exposes feature, training, backtest, selection, forecast, and report stages, but those handlers are placeholders. The README describes a broader intended forecasting workflow; the graph preserves those planned capabilities without implying they are implemented. The substantial ETL files describe a separate pollution-forecast workflow, so they are shown as a distinct legacy branch. Evidence for unsampled planned subsystems is limited to the README.

Main entry points: [`main.py`](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py) (Stage dispatcher), [`src/data/ingestion.py`](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/data/ingestion.py) (Table ingestion), [`src/ETL/transform.py`](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/ETL/transform.py) (Cleaning and features), [`src/run_id.py`](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/run_id.py) (Run ID)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Retail CLI"]
  node_cli["Stage dispatcher<br/>[main.py]"]
  node_runid["Run ID<br/>[run_id.py]"]
  node_logging["Logging setup<br/>[logging_setup.py]"]
end

subgraph group_data["Retail Data"]
  node_config["Config loader<br/>[config.py]"]
  node_ingestion["Table ingestion<br/>[ingestion.py]"]
  node_database[("Supabase database")]
  node_validation["Data validation<br/>[validation.py]"]
end

subgraph group_planned["Planned Forecasting"]
  node_features["Feature engineering<br/>[main.py]"]
  node_training["Model training<br/>[main.py]"]
  node_evaluation["Backtesting<br/>[main.py]"]
  node_selection["Model selection<br/>[main.py]"]
  node_forecast["Demand forecasts<br/>[main.py]"]
  node_report["Forecast reporting<br/>[main.py]"]
end

subgraph group_legacy["Pollution ETL"]
  node_pollution_extract["CSV extraction<br/>[extract.py]"]
  node_pollution_transform["Cleaning and features<br/>[transform.py]"]
  node_pollution_load["Modeling and forecasts<br/>[load.py]"]
end

node_operator(("CLI operator"))

node_operator -->|"invokes"| node_cli
node_cli -->|"creates"| node_runid
node_cli -->|"configures"| node_logging
node_cli -->|"loads tables"| node_ingestion
node_cli -->|"loads config"| node_config
node_cli -->|"validates tables"| node_validation
node_ingestion -->|"queries tables"| node_database
node_cli -->|"dispatches"| node_features
node_cli -->|"dispatches"| node_training
node_cli -->|"dispatches"| node_evaluation
node_cli -->|"dispatches"| node_selection
node_cli -->|"dispatches"| node_forecast
node_cli -->|"dispatches"| node_report
node_pollution_transform -->|"loads extracted data"| node_pollution_extract

click node_cli "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py"
click node_runid "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/run_id.py"
click node_logging "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/logging_setup.py"
click node_config "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/config.py"
click node_ingestion "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/data/ingestion.py"
click node_validation "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/data/validation.py"
click node_features "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py"
click node_training "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py"
click node_evaluation "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py"
click node_selection "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py"
click node_forecast "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py"
click node_report "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py"
click node_pollution_extract "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/ETL/extract.py"
click node_pollution_transform "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/ETL/transform.py"
click node_pollution_load "https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/ETL/load.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_cli,node_runid,node_logging toneBlue
class node_config,node_ingestion,node_database,node_validation toneAmber
class node_features,node_training,node_evaluation,node_selection,node_forecast,node_report toneMint
class node_pollution_extract,node_pollution_transform,node_pollution_load toneRose
class node_operator toneIndigo
```

## Components

### Retail CLI

- [Stage dispatcher](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py): `main.py`
- [Run ID](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/run_id.py): `src/run_id.py`
- [Logging setup](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/logging_setup.py): `src/logging_setup.py`

### Retail Data

- [Config loader](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/config.py): `src/config.py`
- [Table ingestion](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/data/ingestion.py): `src/data/ingestion.py`
- **Supabase database**
- [Data validation](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/data/validation.py): `src/data/validation.py`

### Planned Forecasting

- [Feature engineering](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py): `main.py`
- [Model training](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py): `main.py`
- [Backtesting](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py): `main.py`
- [Model selection](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py): `main.py`
- [Demand forecasts](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py): `main.py`
- [Forecast reporting](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/main.py): `main.py`

### Pollution ETL

- [CSV extraction](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/ETL/extract.py): `src/ETL/extract.py`
- [Cleaning and features](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/ETL/transform.py): `src/ETL/transform.py`
- [Modeling and forecasts](https://github.com/retail-analytical-platform/retail-analytics-ml/blob/main/src/ETL/load.py): `src/ETL/load.py`

### Other components

- **CLI operator**

## Connections

- CLI operator → Stage dispatcher: invokes (evidence: `README.md`)
- Stage dispatcher → Run ID: creates (evidence: `main.py`)
- Stage dispatcher → Logging setup: configures (evidence: `main.py`)
- Stage dispatcher → Table ingestion: loads tables (evidence: `main.py`)
- Stage dispatcher → Config loader: loads config (evidence: `main.py`)
- Stage dispatcher → Data validation: validates tables (evidence: `main.py`)
- Table ingestion → Supabase database: queries tables (evidence: `src/data/ingestion.py`)
- Stage dispatcher → Feature engineering: dispatches (evidence: `main.py`)
- Stage dispatcher → Model training: dispatches (evidence: `main.py`)
- Stage dispatcher → Backtesting: dispatches (evidence: `main.py`)
- Stage dispatcher → Model selection: dispatches (evidence: `main.py`)
- Stage dispatcher → Demand forecasts: dispatches (evidence: `main.py`)
- Stage dispatcher → Forecast reporting: dispatches (evidence: `main.py`)
- Cleaning and features → CSV extraction: loads extracted data (evidence: `src/ETL/transform.py`)