Fix README: spread screenshots one-at-a-time, fix broken image paths, remove duplicate architecture
Browse files
README.md
CHANGED
|
@@ -34,6 +34,8 @@ If you are reviewing this project for a **Senior Data Scientist**, **Machine Lea
|
|
| 34 |
* **Predictive & Segment ML Engines:** Built a **LightGBM time-series revenue forecasting model** (with residual analysis) and an **RFM K-Means Clustering model** (validated via Silhouette & Davies-Bouldin scores with PCA 2D projections).
|
| 35 |
* **Automated AI Executive Insights:** Includes an automated C-suite report generator synthesizing revenue health, segment risks, and forecast projections into actionable strategic recommendations.
|
| 36 |
|
|
|
|
|
|
|
| 37 |
---
|
| 38 |
|
| 39 |
## 🎥 Full System Walkthrough & Demo Video
|
|
@@ -44,52 +46,6 @@ https://github.com/user-attachments/assets/e9e9354d-bc9d-4434-b829-712ba0c8069a
|
|
| 44 |
|
| 45 |
---
|
| 46 |
|
| 47 |
-
## 📸 Executive Platform Showcase (Live Dashboard Screenshots)
|
| 48 |
-
|
| 49 |
-
### 1. C-Suite Executive Overview & KPI Dashboard
|
| 50 |
-
*Real-time executive cockpit displaying revenue metrics, order velocity, customer acquisition, and dynamic multi-dimensional filters.*
|
| 51 |
-

|
| 52 |
-
|
| 53 |
-
<br/>
|
| 54 |
-
|
| 55 |
-
### 2. Machine Learning Customer Segmentation (RFM + PCA K-Means)
|
| 56 |
-
*Unsupervised ML model segmenting 100k+ customers into behavioral personas with 2D PCA cluster visualization and metrics.*
|
| 57 |
-

|
| 58 |
-
|
| 59 |
-
<br/>
|
| 60 |
-
|
| 61 |
-
### 3. LightGBM Time-Series Revenue Forecasting Engine
|
| 62 |
-
*Predictive time-series model forecasting daily revenue trends with historical accuracy comparison and residual error distributions.*
|
| 63 |
-

|
| 64 |
-
|
| 65 |
-
<br/>
|
| 66 |
-
|
| 67 |
-
### 4. Automated AI Business Summary & C-Suite Report Generator
|
| 68 |
-
*Data synthesis engine combining financial health, customer churn risks, and category growth opportunities into dynamic markdown reports.*
|
| 69 |
-

|
| 70 |
-
|
| 71 |
-
<br/>
|
| 72 |
-
|
| 73 |
-
<details>
|
| 74 |
-
<summary><b>🔍 View Additional Workspace Screenshots (Sales, Customers, Products, Geography, Reports)</b></summary>
|
| 75 |
-
|
| 76 |
-
#### Sales & Revenue Analytics Workspace
|
| 77 |
-

|
| 78 |
-
|
| 79 |
-
#### Customer Health & Retention Analytics
|
| 80 |
-

|
| 81 |
-
|
| 82 |
-
#### Product & Category Performance
|
| 83 |
-

|
| 84 |
-
|
| 85 |
-
#### Geographic Revenue Distribution
|
| 86 |
-

|
| 87 |
-
|
| 88 |
-
#### Enterprise Data Reports Explorer
|
| 89 |
-

|
| 90 |
-
|
| 91 |
-
</details>
|
| 92 |
-
|
| 93 |
---
|
| 94 |
|
| 95 |
## 🏗️ System Architecture
|
|
@@ -121,6 +77,8 @@ flowchart TD
|
|
| 121 |
```
|
| 122 |
| Deployment | Docker |
|
| 123 |
|
|
|
|
|
|
|
| 124 |
---
|
| 125 |
|
| 126 |
## What this project demonstrates
|
|
@@ -134,37 +92,6 @@ flowchart TD
|
|
| 134 |
|
| 135 |
---
|
| 136 |
|
| 137 |
-
## Architecture
|
| 138 |
-
>>>>>>> 88deff280f44abd7f8785c4f8e41bf841b4bc0eb
|
| 139 |
-
|
| 140 |
-
```mermaid
|
| 141 |
-
flowchart TD
|
| 142 |
-
subgraph Data Layer
|
| 143 |
-
A[Olist Raw CSVs] -->|Polars ETL| B[(MySQL Star Schema)]
|
| 144 |
-
B --> C[reporting_sales_summary]
|
| 145 |
-
B --> D[reporting_customer_summary]
|
| 146 |
-
B --> E[reporting_state_summary]
|
| 147 |
-
end
|
| 148 |
-
|
| 149 |
-
subgraph ML Layer
|
| 150 |
-
F[LightGBM Forecast Model] --> H[FastAPI Backend]
|
| 151 |
-
G[RFM K-Means Segmentation] --> H
|
| 152 |
-
B -->|async SQLAlchemy| H
|
| 153 |
-
end
|
| 154 |
-
|
| 155 |
-
subgraph API Layer
|
| 156 |
-
H[FastAPI Async Backend] <--> I[Redis / TTL Cache]
|
| 157 |
-
end
|
| 158 |
-
|
| 159 |
-
subgraph Presentation Layer
|
| 160 |
-
J[Next.js Dashboard] <-->|TanStack Query| H
|
| 161 |
-
J --> K[AI Executive Summary]
|
| 162 |
-
J --> L[Filter Bar]
|
| 163 |
-
end
|
| 164 |
-
```
|
| 165 |
-
|
| 166 |
-
---
|
| 167 |
-
|
| 168 |
## Engineering decisions (and why I made them)
|
| 169 |
|
| 170 |
**Why a star schema over a snowflake schema:** the dashboard's query patterns are almost entirely single-join aggregations (revenue by state, revenue by month, revenue by segment). A star schema keeps those joins shallow and avoids the multi-hop joins a snowflake design would force for the same queries.
|
|
@@ -173,8 +100,12 @@ flowchart TD
|
|
| 173 |
|
| 174 |
**Why LightGBM over ARIMA/Prophet for forecasting:** the revenue series has irregular seasonality and several categorical drivers (state, category) that a pure time-series model can't easily incorporate. A gradient-boosted tree model lets me treat forecasting as regression with time-based and categorical features, at the cost of losing some classical time-series interpretability — a tradeoff I'm explicit about in the model docs.
|
| 175 |
|
|
|
|
|
|
|
| 176 |
**Why K-Means over hierarchical/DBSCAN for segmentation:** RFM features are low-dimensional and roughly convex per cluster after scaling, which is exactly where K-Means performs well and stays interpretable for a business audience. I validated cluster count with silhouette score and Davies-Bouldin index rather than picking K arbitrarily.
|
| 177 |
|
|
|
|
|
|
|
| 178 |
**Why a caching layer at all:** several endpoints aggregate across the full fact table on every request. Rather than optimize every query indefinitely, I cached the aggregation layer — the more common and more defensible fix in a real system with a mixed read/write pattern.
|
| 179 |
|
| 180 |
---
|
|
|
|
| 34 |
* **Predictive & Segment ML Engines:** Built a **LightGBM time-series revenue forecasting model** (with residual analysis) and an **RFM K-Means Clustering model** (validated via Silhouette & Davies-Bouldin scores with PCA 2D projections).
|
| 35 |
* **Automated AI Executive Insights:** Includes an automated C-suite report generator synthesizing revenue health, segment risks, and forecast projections into actionable strategic recommendations.
|
| 36 |
|
| 37 |
+

|
| 38 |
+
|
| 39 |
---
|
| 40 |
|
| 41 |
## 🎥 Full System Walkthrough & Demo Video
|
|
|
|
| 46 |
|
| 47 |
---
|
| 48 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 49 |
---
|
| 50 |
|
| 51 |
## 🏗️ System Architecture
|
|
|
|
| 77 |
```
|
| 78 |
| Deployment | Docker |
|
| 79 |
|
| 80 |
+

|
| 81 |
+
|
| 82 |
---
|
| 83 |
|
| 84 |
## What this project demonstrates
|
|
|
|
| 92 |
|
| 93 |
---
|
| 94 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 95 |
## Engineering decisions (and why I made them)
|
| 96 |
|
| 97 |
**Why a star schema over a snowflake schema:** the dashboard's query patterns are almost entirely single-join aggregations (revenue by state, revenue by month, revenue by segment). A star schema keeps those joins shallow and avoids the multi-hop joins a snowflake design would force for the same queries.
|
|
|
|
| 100 |
|
| 101 |
**Why LightGBM over ARIMA/Prophet for forecasting:** the revenue series has irregular seasonality and several categorical drivers (state, category) that a pure time-series model can't easily incorporate. A gradient-boosted tree model lets me treat forecasting as regression with time-based and categorical features, at the cost of losing some classical time-series interpretability — a tradeoff I'm explicit about in the model docs.
|
| 102 |
|
| 103 |
+

|
| 104 |
+
|
| 105 |
**Why K-Means over hierarchical/DBSCAN for segmentation:** RFM features are low-dimensional and roughly convex per cluster after scaling, which is exactly where K-Means performs well and stays interpretable for a business audience. I validated cluster count with silhouette score and Davies-Bouldin index rather than picking K arbitrarily.
|
| 106 |
|
| 107 |
+

|
| 108 |
+
|
| 109 |
**Why a caching layer at all:** several endpoints aggregate across the full fact table on every request. Rather than optimize every query indefinitely, I cached the aggregation layer — the more common and more defensible fix in a real system with a mixed read/write pattern.
|
| 110 |
|
| 111 |
---
|