# vedthacker/ecommerce-rto-predictor architecture

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

- Interactive diagram: https://gitdiagram.com/vedthacker/ecommerce-rto-predictor
- Repository: https://github.com/vedthacker/ecommerce-rto-predictor

## Overview

This is a pre-dispatch e-commerce Return-to-Origin (RTO) prediction engine. Its principal workflow is order entry in the Streamlit interface, inference and risk/action presentation; a separate batch workflow generates synthetic orders, explores and engineers data, trains and evaluates a model, scores orders, and analyzes those scores in SQLite. SQL business intelligence and real-time contextual signals are distinct capabilities. The real-time module is present, but the excerpts do not show it being wired into inference. Edges reflect shown calls or README-documented behavior; generated data flow details are limited where artifacts are not in the tree.

Main entry points: [`main.py`](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/main.py) (Pipeline Runner), [`src/model.py`](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/model.py) (Model Training), [`src/predictor.py`](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/predictor.py) (Risk Inference), [`src/sql_analysis.py`](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/sql_analysis.py) (SQL Business Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prediction["Order Risk Prediction"]
  node_streamlit["Order Entry UI<br/>[app.py]"]
  node_inference["Risk Inference<br/>[predictor.py]"]
  node_model_file["Saved Model<br/>[rto_model.pkl]"]
  node_risk_result["Risk and Action<br/>[predictor.py]"]
end

subgraph group_training["Data and Model"]
  node_pipeline["Pipeline Runner<br/>[main.py]"]
  node_generator["Synthetic Order Generator<br/>[generate_data.py]"]
  node_raw_orders["Raw Order Data<br/>[generate_data.py]"]
  node_eda["Exploratory Analysis<br/>[eda.py]"]
  node_features["Feature Engineering<br/>[preprocess.py]"]
  node_training_model["Model Training<br/>[model.py]"]
end

subgraph group_analytics["Business Analytics"]
  node_scored_orders["Scored Orders<br/>[model.py]"]
  node_sql_analysis["SQL Business Analysis<br/>[sql_analysis.py]"]
  node_sqlite[("SQLite Orders Store<br/>[sql_analysis.py]")]
end

subgraph group_context["Context Signals"]
  node_realtime["Real-Time Signals"]
end

node_operator(("Operations User"))
node_weather_service{{"Open-Meteo"}}

node_operator -->|"enters order"| node_streamlit
node_streamlit -->|"requests prediction"| node_inference
node_inference -.->|"loads model"| node_model_file
node_inference -->|"returns score"| node_risk_result
node_pipeline -->|"runs generation"| node_generator
node_generator -->|"writes orders"| node_raw_orders
node_pipeline -->|"runs analysis"| node_eda
node_pipeline -->|"runs training"| node_training_model
node_pipeline -->|"runs SQL analysis"| node_sql_analysis
node_eda -->|"uses engineering"| node_features
node_training_model -->|"engineers features"| node_features
node_training_model -->|"saves model"| node_model_file
node_training_model -->|"writes scores"| node_scored_orders
node_sql_analysis -->|"loads scores"| node_scored_orders
node_sql_analysis -->|"loads and queries"| node_sqlite
node_realtime -->|"requests weather"| node_weather_service

click node_streamlit "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/app.py"
click node_inference "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/predictor.py"
click node_model_file "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/outputs/models/rto_model.pkl"
click node_risk_result "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/predictor.py"
click node_pipeline "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/main.py"
click node_generator "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/data/generate_data.py"
click node_raw_orders "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/data/generate_data.py"
click node_eda "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/eda.py"
click node_features "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/preprocess.py"
click node_training_model "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/model.py"
click node_scored_orders "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/model.py"
click node_sql_analysis "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/sql_analysis.py"
click node_sqlite "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/sql_analysis.py"
click node_realtime "https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/realtime_features.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_streamlit,node_inference,node_model_file,node_risk_result,node_operator toneBlue
class node_pipeline,node_generator,node_raw_orders,node_eda,node_features,node_training_model toneAmber
class node_scored_orders,node_sql_analysis,node_sqlite toneMint
class node_realtime toneRose
class node_weather_service toneIndigo
```

## Components

### Order Risk Prediction

- [Order Entry UI](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/app.py): `app.py`
- [Risk Inference](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/predictor.py): `src/predictor.py`
- [Saved Model](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/outputs/models/rto_model.pkl): `outputs/models/rto_model.pkl`
- [Risk and Action](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/predictor.py): `src/predictor.py`

### Data and Model

- [Pipeline Runner](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/main.py): `main.py`
- [Synthetic Order Generator](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/data/generate_data.py): `data/generate_data.py`
- [Raw Order Data](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/data/generate_data.py): `data/generate_data.py`
- [Exploratory Analysis](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/eda.py): `src/eda.py`
- [Feature Engineering](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/preprocess.py): `src/preprocess.py`
- [Model Training](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/model.py): `src/model.py`

### Business Analytics

- [Scored Orders](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/model.py): `src/model.py`
- [SQL Business Analysis](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/sql_analysis.py): `src/sql_analysis.py`
- [SQLite Orders Store](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/sql_analysis.py): `src/sql_analysis.py`

### Context Signals

- [Real-Time Signals](https://github.com/vedthacker/ecommerce-rto-predictor/blob/main/src/realtime_features.py): `src/realtime_features.py`

### Other components

- **Operations User**
- **Open-Meteo**

## Connections

- Operations User → Order Entry UI: enters order (evidence: `app.py`)
- Order Entry UI → Risk Inference: requests prediction (evidence: `app.py`)
- Risk Inference → Saved Model: loads model (evidence: `README.md`)
- Risk Inference → Risk and Action: returns score (evidence: `src/predictor.py`)
- Pipeline Runner → Synthetic Order Generator: runs generation (evidence: `main.py`)
- Synthetic Order Generator → Raw Order Data: writes orders (evidence: `data/generate_data.py`)
- Pipeline Runner → Exploratory Analysis: runs analysis (evidence: `main.py`)
- Pipeline Runner → Model Training: runs training (evidence: `main.py`)
- Pipeline Runner → SQL Business Analysis: runs SQL analysis (evidence: `main.py`)
- Exploratory Analysis → Feature Engineering: uses engineering (evidence: `src/eda.py`)
- Model Training → Feature Engineering: engineers features (evidence: `src/model.py`)
- Model Training → Saved Model: saves model (evidence: `src/model.py`)
- Model Training → Scored Orders: writes scores (evidence: `src/model.py`)
- SQL Business Analysis → Scored Orders: loads scores (evidence: `src/sql_analysis.py`)
- SQL Business Analysis → SQLite Orders Store: loads and queries (evidence: `src/sql_analysis.py`)
- Real-Time Signals → Open-Meteo: requests weather (evidence: `src/realtime_features.py`)
