# ash469/smart-return-risk-analytics architecture

> Architecture diagram of the GitHub repository ash469/smart-return-risk-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ash469/smart-return-risk-analytics
- Repository: https://github.com/ash469/smart-return-risk-analytics

## Overview

#### Purpose and Entry Points
Smart Return Risk Analytics is an offline e-commerce ML pipeline plus Streamlit decision-support UI. It ingests Olist CSV data, builds SQLite analytics tables/features, simulates return labels, trains binary classifiers, and serves return-risk predictions and historical analysis.

Primary execution entry points:
- Database initialization: `src/db_setup.py`
- CSV ingestion: `src/data_loader.py`
- SQL pipeline execution: `src/sql_executor.py`
- Model training/artifact export: `src/train_and_save_models.py`
- Dashboard runtime: `dashboard/app.py`

#### Source Data and Persistence Boundary
Raw Olist entities are versioned as CSVs under `data/raw/`, including orders, items, products, customers, and reviews. SQLite is the system’s relational processing boundary, with persisted databases at `data/database.sqlite`, `data/ecommerce.db`, and `data/ecommerce_returns.db`.

The pipeline converts raw operational-like data into queryable tables before ML-ready feature assembly, rather than having the dashboard query CSVs directly.

#### SQL Analytics and Feature Stage
Ordered SQL scripts define the analytics pipeline:
- Schema/table setup: `sql/01_setup_tables.sql`
- Data validation: `sql/02_data_quality_checks.sql`
- Customer and product aggregations: `sql/03_customer_features.sql`, `sql/04_product_features.sql`
- Order-level features and return-oriented data: `sql/05_order_level_features.sql`

Materialized SQL outputs provide intermediate contracts for downstream modeling: `data/sql_outputs/customer_features.csv`, `data/sql_outputs/product_features.csv`, and `data/sql_outputs/order_features_with_returns.csv`. The return target is synthetic, based on business signals such as review, delivery, and freight behavior.

#### ML Dataset and Training
The consolidated modeling contract is `data/final/ml_ready_dataset.csv`. Training experiments exist as notebooks and one executable model script, while `src/train_and_save_models.py` is the intended repeatable artifact-building path.

The system evaluates multiple binary classifiers—logistic regression, decision tree, random forest, and XGBoost—with class-imbalance and explainability capabilities described as part of the stack. Core model development paths are `models/01_logistic_regression.ipynb`, `models/03_random_forest.ipynb`, and `models/04_xgboost.py`.

#### Model Artifact Boundary
The dashboard consumes serialized inference artifacts rather than retraining models:
- Classifiers: `dashboard/models/lr_model.pkl`, `dashboard/models/rf_model.pkl`, `dashboard/models/xgb_model.pkl`
- Input schema and imputation metadata: `dashboard/models/feature_columns.pkl`, `dashboard/models/feature_medians.pkl`

This establishes a deployment boundary: training produces stable model/feature contracts; interactive pages load those contracts for prediction.

#### Dashboard Application Flow
`dashboard/app.py` is the Streamlit shell and routes users to three business workflows:
- Single-order/customer risk prediction: `dashboard/pages/1_Single_Predictor.py`
- Interactive scenario and cost/risk simulation: `dashboard/pages/2_What_If_Simulator.py`
- Aggregate historical metrics and trends: `dashboard/pages/3_Historical_Analytics.py`

Shared UI-side preprocessing and model-loading behavior belongs in `dashboard/utils.py`. Dashboard execution requires Python, Streamlit, the serialized model artifacts, and local data/database resources; no hosted service or API integration is represented.

#### Key Runtime Stack
The repository runs locally on Python 3.8+, using Pandas/NumPy for data processing, SQLite for storage and SQL transformation, scikit-learn and XGBoost for classification, and Streamlit/Plotly-oriented visualization for interactive analysis. Notebooks in `notebooks/` are exploratory and feature-engineering stages, whereas `src/`, `sql/`, and `dashboard/` define the operational pipeline and serving surface.

Main entry points: [`src/sql_executor.py`](https://github.com/ash469/smart-return-risk-analytics/blob/master/src/sql_executor.py) (SQL pipeline runner), [`data/database.sqlite`](https://github.com/ash469/smart-return-risk-analytics/blob/master/data/database.sqlite) (SQLite analytics store), [`data/sql_outputs/order_features_with_returns.csv`](https://github.com/ash469/smart-return-risk-analytics/blob/master/data/sql_outputs/order_features_with_returns.csv) (Materialized SQL features), [`dashboard/app.py`](https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/app.py) (Dashboard shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data & SQLite"]
  node_raw_csv[("Olist raw CSVs<br/>raw data")]
  node_db_setup["Database initialization<br/>Python entry point<br/>[db_setup.py]"]
  node_data_loader["CSV ingestion<br/>Python entry point<br/>[data_loader.py]"]
  node_sqlite[("SQLite analytics store<br/>SQLite databases<br/>[database.sqlite]")]
end

subgraph group_sql["SQL Analytics"]
  node_sql_executor["SQL pipeline runner<br/>Python entry point<br/>[sql_executor.py]"]
  node_schema_sql["Schema setup<br/>SQL stage"]
  node_quality_sql["Data quality checks<br/>SQL stage"]
  node_customer_sql["Customer features<br/>SQL stage"]
  node_product_sql["Product features<br/>SQL stage"]
  node_order_sql["Order features &amp; returns<br/>SQL stage"]
  node_sql_outputs[("Materialized SQL features<br/>CSV contracts")]
end

subgraph group_ml["ML Training"]
  node_ml_dataset[("ML-ready dataset<br/>modeling dataset")]
  node_trainer["Training &amp; artifact export<br/>Python entry point"]
  node_model_dev["Model development<br/>experiments"]
end

subgraph group_ui["Streamlit Dashboard"]
  node_artifacts[("Inference artifacts<br/>serialized models<br/>[lr_model.pkl]")]
  node_app["Dashboard shell<br/>Streamlit runtime<br/>[app.py]"]
  node_ui_utils["UI preprocessing<br/>shared Python module<br/>[utils.py]"]
  node_predictor["Single predictor<br/>Streamlit page"]
  node_simulator["What-if simulator<br/>Streamlit page"]
  node_history["Historical analytics<br/>Streamlit page"]
end

node_db_setup -->|"initializes"| node_sqlite
node_raw_csv -->|"ingests"| node_data_loader
node_data_loader -->|"loads tables"| node_sqlite
node_sql_executor -->|"runs first"| node_schema_sql
node_sql_executor -->|"runs"| node_quality_sql
node_sql_executor -->|"runs"| node_customer_sql
node_sql_executor -->|"runs"| node_product_sql
node_sql_executor -->|"runs"| node_order_sql
node_sqlite -->|"queries"| node_sql_executor
node_order_sql -->|"materializes"| node_sql_outputs
node_customer_sql -->|"materializes"| node_sql_outputs
node_product_sql -->|"materializes"| node_sql_outputs
node_sql_outputs -->|"consolidates into"| node_ml_dataset
node_model_dev -.->|"informs experiments"| node_trainer
node_ml_dataset -->|"trains on"| node_trainer
node_trainer -->|"exports"| node_artifacts
node_app -->|"routes to"| node_predictor
node_app -->|"routes to"| node_simulator
node_app -->|"routes to"| node_history
node_ui_utils -->|"loads"| node_artifacts
node_predictor -->|"uses"| node_ui_utils
node_simulator -->|"uses"| node_ui_utils
node_history -->|"reads local data"| node_sqlite

click node_db_setup "https://github.com/ash469/smart-return-risk-analytics/blob/master/src/db_setup.py"
click node_data_loader "https://github.com/ash469/smart-return-risk-analytics/blob/master/src/data_loader.py"
click node_sqlite "https://github.com/ash469/smart-return-risk-analytics/blob/master/data/database.sqlite"
click node_sql_executor "https://github.com/ash469/smart-return-risk-analytics/blob/master/src/sql_executor.py"
click node_schema_sql "https://github.com/ash469/smart-return-risk-analytics/blob/master/sql/01_setup_tables.sql"
click node_quality_sql "https://github.com/ash469/smart-return-risk-analytics/blob/master/sql/02_data_quality_checks.sql"
click node_customer_sql "https://github.com/ash469/smart-return-risk-analytics/blob/master/sql/03_customer_features.sql"
click node_product_sql "https://github.com/ash469/smart-return-risk-analytics/blob/master/sql/04_product_features.sql"
click node_order_sql "https://github.com/ash469/smart-return-risk-analytics/blob/master/sql/05_order_level_features.sql"
click node_sql_outputs "https://github.com/ash469/smart-return-risk-analytics/blob/master/data/sql_outputs/order_features_with_returns.csv"
click node_ml_dataset "https://github.com/ash469/smart-return-risk-analytics/blob/master/data/final/ml_ready_dataset.csv"
click node_trainer "https://github.com/ash469/smart-return-risk-analytics/blob/master/src/train_and_save_models.py"
click node_model_dev "https://github.com/ash469/smart-return-risk-analytics/blob/master/models/01_logistic_regression.ipynb"
click node_artifacts "https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/models/lr_model.pkl"
click node_app "https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/app.py"
click node_ui_utils "https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/utils.py"
click node_predictor "https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/pages/1_Single_Predictor.py"
click node_simulator "https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/pages/2_What_If_Simulator.py"
click node_history "https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/pages/3_Historical_Analytics.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_raw_csv,node_db_setup,node_data_loader,node_sqlite toneBlue
class node_sql_executor,node_schema_sql,node_quality_sql,node_customer_sql,node_product_sql,node_order_sql,node_sql_outputs toneAmber
class node_ml_dataset,node_trainer,node_model_dev toneMint
class node_artifacts,node_app,node_ui_utils,node_predictor,node_simulator,node_history toneRose
```

## Components

### Data & SQLite

Offline ingestion and relational processing boundary.

- **Olist raw CSVs**: raw data · Orders, items, products, customers, and reviews.
- [Database initialization](https://github.com/ash469/smart-return-risk-analytics/blob/master/src/db_setup.py): Python entry point · `src/db_setup.py`
- [CSV ingestion](https://github.com/ash469/smart-return-risk-analytics/blob/master/src/data_loader.py): Python entry point · `src/data_loader.py`
- [SQLite analytics store](https://github.com/ash469/smart-return-risk-analytics/blob/master/data/database.sqlite): SQLite databases · Relational boundary for ingestion, SQL processing, and local dashboard data. · `data/database.sqlite`

### SQL Analytics

Ordered transformations and materialized feature contracts.

- [SQL pipeline runner](https://github.com/ash469/smart-return-risk-analytics/blob/master/src/sql_executor.py): Python entry point · `src/sql_executor.py`
- [Schema setup](https://github.com/ash469/smart-return-risk-analytics/blob/master/sql/01_setup_tables.sql): SQL stage · `sql/01_setup_tables.sql`
- [Data quality checks](https://github.com/ash469/smart-return-risk-analytics/blob/master/sql/02_data_quality_checks.sql): SQL stage · `sql/02_data_quality_checks.sql`
- [Customer features](https://github.com/ash469/smart-return-risk-analytics/blob/master/sql/03_customer_features.sql): SQL stage · `sql/03_customer_features.sql`
- [Product features](https://github.com/ash469/smart-return-risk-analytics/blob/master/sql/04_product_features.sql): SQL stage · `sql/04_product_features.sql`
- [Order features & returns](https://github.com/ash469/smart-return-risk-analytics/blob/master/sql/05_order_level_features.sql): SQL stage · Builds order-level features and synthetic return target. · `sql/05_order_level_features.sql`
- [Materialized SQL features](https://github.com/ash469/smart-return-risk-analytics/blob/master/data/sql_outputs/order_features_with_returns.csv): CSV contracts · Customer, product, and return-oriented order feature outputs. · `data/sql_outputs/order_features_with_returns.csv`

### ML Training

Dataset assembly, model evaluation, and artifact export.

- [ML-ready dataset](https://github.com/ash469/smart-return-risk-analytics/blob/master/data/final/ml_ready_dataset.csv): modeling dataset · Consolidated training contract. · `data/final/ml_ready_dataset.csv`
- [Training & artifact export](https://github.com/ash469/smart-return-risk-analytics/blob/master/src/train_and_save_models.py): Python entry point · Evaluates binary classifiers and exports stable inference contracts. · `src/train_and_save_models.py`
- [Model development](https://github.com/ash469/smart-return-risk-analytics/blob/master/models/01_logistic_regression.ipynb): experiments · Logistic regression, random forest, and XGBoost development paths. · `models/01_logistic_regression.ipynb`

### Streamlit Dashboard

Local decision-support serving surface.

- [Inference artifacts](https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/models/lr_model.pkl): serialized models · Classifiers plus feature columns and imputation medians. · `dashboard/models/lr_model.pkl`
- [Dashboard shell](https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/app.py): Streamlit runtime · Routes local users to prediction, simulation, and history workflows. · `dashboard/app.py`
- [UI preprocessing](https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/utils.py): shared Python module · Shared model loading and preprocessing. · `dashboard/utils.py`
- [Single predictor](https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/pages/1_Single_Predictor.py): Streamlit page · `dashboard/pages/1_Single_Predictor.py`
- [What-if simulator](https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/pages/2_What_If_Simulator.py): Streamlit page · `dashboard/pages/2_What_If_Simulator.py`
- [Historical analytics](https://github.com/ash469/smart-return-risk-analytics/blob/master/dashboard/pages/3_Historical_Analytics.py): Streamlit page · `dashboard/pages/3_Historical_Analytics.py`

## Connections

- Database initialization → SQLite analytics store: initializes
- Olist raw CSVs → CSV ingestion: ingests
- CSV ingestion → SQLite analytics store: loads tables
- SQL pipeline runner → Schema setup: runs first
- SQL pipeline runner → Data quality checks: runs
- SQL pipeline runner → Customer features: runs
- SQL pipeline runner → Product features: runs
- SQL pipeline runner → Order features & returns: runs
- SQLite analytics store → SQL pipeline runner: queries
- Order features & returns → Materialized SQL features: materializes
- Customer features → Materialized SQL features: materializes
- Product features → Materialized SQL features: materializes
- Materialized SQL features → ML-ready dataset: consolidates into
- Model development → Training & artifact export: informs experiments
- ML-ready dataset → Training & artifact export: trains on
- Training & artifact export → Inference artifacts: exports
- Dashboard shell → Single predictor: routes to
- Dashboard shell → What-if simulator: routes to
- Dashboard shell → Historical analytics: routes to
- UI preprocessing → Inference artifacts: loads
- Single predictor → UI preprocessing: uses
- What-if simulator → UI preprocessing: uses
- Historical analytics → SQLite analytics store: reads local data