┌─────────────────────────────────────────────────────────────────────┐
│ USER INTERFACE │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Browser: http://localhost:8000 │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Home Page │ │ About Page │ │ API Docs │ │ │
│ │ │ (index.html)│ │ (about.html) │ │ (Swagger) │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │
│ └─────────┼──────────────────┼──────────────────┼────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ JavaScript (app.js) │ │
│ │ - Form handling │ │
│ │ - AJAX requests │ │
│ │ - UI updates │ │
│ └─────────────────────────┬───────────────────────────────────┘ │
└────────────────────────────┼──────────────────────────────────────┘
│ HTTP Requests
│ (JSON)
▼
┌────────────────────────────────────────────────────────────────────┐
│ FASTAPI WEB SERVER │
│ (main.py) │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ MIDDLEWARE LAYER │ │
│ │ - CORS Handler │ │
│ │ - Request Validation │ │
│ │ - Error Handling │ │
│ └──────────────────────────┬───────────────────────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ CONTROLLER LAYER │ │
│ │ │ │
│ │ ┌────────────────────┐ ┌──────────────────────┐ │ │
│ │ │ API Controller │ │ View Controller │ │ │
│ │ │ │ │ │ │ │
│ │ │ POST /predict │ │ GET / │ │ │
│ │ │ GET /clusters │ │ GET /about │ │ │
│ │ │ GET /health │ │ │ │ │
│ │ │ GET /model/info │ │ │ │ │
│ │ └─────────┬──────────┘ └──────────┬───────────┘ │ │
│ └────────────┼────────────────────────┼──────────────────────┘ │
│ │ │ │
└───────────────┼────────────────────────┼──────────────────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────────────────────┐
│ SERVICE LAYER │
│ (Business Logic) │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PredictionService │ │
│ │ │ │
│ │ - predict_segment() │ │
│ │ - get_cluster_description() │ │
│ │ - get_marketing_strategy() │ │
│ │ - get_cluster_statistics() │ │
│ └─────────────────────────┬───────────────────────────────────┘ │
└────────────────────────────┼──────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ MODEL LAYER │
│ (Machine Learning) │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ CustomerSegmentationModel │ │
│ │ │ │
│ │ ┌──────────────────┐ ┌──────────────────┐ │ │
│ │ │ KMeans Model │ │ StandardScaler │ │ │
│ │ │ (k=5 clusters) │ │ (Normalization) │ │ │
│ │ └──────────────────┘ └──────────────────┘ │ │
│ │ │ │
│ │ Methods: │ │
│ │ - load_models() │ │
│ │ - predict() │ │
│ │ - get_cluster_centroids() │ │
│ └─────────────────────────┬───────────────────────────────────┘ │
└────────────────────────────┼──────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ DATA LAYER │
│ │
│ ┌────────────────────┐ ┌────────────────────┐ │
│ │ Model Artifacts │ │ Training Data │ │
│ │ │ │ │ │
│ │ kmeans_model.pkl │ │ mall_customers │ │
│ │ scaler.pkl │ │ _processed.csv │ │
│ └────────────────────┘ └────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
1. USER ACTION
├─ User enters: Income=$90k, Spending Score=85
├─ Clicks "Predict Segment" button
└─ JavaScript captures form data
2. FRONTEND (JavaScript)
├─ Validates inputs (annual_income, spending_score)
├─ Creates JSON request body
└─ Sends POST request to /api/v1/predict
3. CONTROLLER (api_controller.py)
├─ Receives HTTP request
├─ Pydantic validates CustomerInput schema
├─ Calls prediction_service.predict_segment()
└─ Returns PredictionResponse
4. SERVICE LAYER (prediction_service.py)
├─ Receives CustomerInput
├─ Calls ml_model.predict(90, 85)
├─ Gets cluster_id and cluster_name
├─ Adds business logic:
│ ├─ get_cluster_description(cluster_id)
│ └─ get_marketing_strategy(cluster_id)
└─ Returns PredictionResponse object
5. MODEL LAYER (ml_model.py)
├─ Creates DataFrame with input data
├─ Scales features using StandardScaler
├─ Predicts cluster using KMeans
└─ Returns (cluster_id: 1, cluster_name: "VIP / Whale")
6. RESPONSE
├─ Controller returns JSON response:
│ {
│ "cluster_id": 1,
│ "cluster_name": "VIP / Whale",
│ "annual_income": 90.0,
│ "spending_score": 85,
│ "description": "High income, high spending customers",
│ "marketing_strategy": "Premium products..."
│ }
└─ JavaScript receives and displays result
7. UI UPDATE
├─ JavaScript parses JSON response
├─ Creates result card with gradient
├─ Displays cluster badge
├─ Shows description and strategy
└─ Smooth scroll to result
┌─────────────────────────────────────────────────────────────┐
│ DATA PIPELINE │
└─────────────────────────────────────────────────────────────┘
TRAINING PHASE:
───────────────
Raw Data
│
│ (data/raw/mall_customers.csv)
▼
┌────────────────────┐
│ Data Cleaning │ (01_eda_preprocessing.ipynb)
│ - Remove ID │
│ - Encode Gender │
│ - Rename columns │
└─────────┬──────────┘
│
▼
Processed Data
│
│ (data/processed/mall_customers_processed.csv)
▼
┌────────────────────┐
│ Feature Selection │ (02_modeling_evaluation.ipynb)
│ - Annual_Income │
│ - Spending_Score │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Scaling │
│ StandardScaler │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Model Training │
│ KMeans (k=5) │
│ k-means++ │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Save Models │
│ - kmeans.pkl │
│ - scaler.pkl │
└────────────────────┘
PREDICTION PHASE:
────────────────
New Customer Data
│
│ {income: 90, score: 85}
▼
┌────────────────────┐
│ Load Models │
│ - KMeans │
│ - Scaler │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Create DataFrame │
│ [90, 85] │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Scale Features │
│ scaler.transform()│
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Predict Cluster │
│ kmeans.predict() │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Add Business Info │
│ - Description │
│ - Strategy │
└─────────┬──────────┘
│
▼
Prediction Result
│
│ {cluster_id: 1, cluster_name: "VIP / Whale", ...}
▼
Return to User
main.py
│
├──> app.core.config (Settings)
│
├──> app.models.ml_model (Model Loading)
│ │
│ └──> sklearn.cluster.KMeans
│ └──> sklearn.preprocessing.StandardScaler
│
├──> app.controllers.api_controller (API Routes)
│ │
│ ├──> app.services.prediction_service
│ │ │
│ │ └──> app.models.ml_model
│ │
│ └──> app.schemas.customer (Validation)
│
└──> app.controllers.view_controller (HTML Views)
│
└──> app.templates (Jinja2)
│
└──> app.static (CSS, JS)
┌─────────────────────────────────────────────────────────┐
│ BROWSER │
│ │
│ ┌────────────────────────────────────────────────┐ │
│ │ HTML (Structure) │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ index.html │ │ │
│ │ │ - Header/Navigation │ │ │
│ │ │ - Prediction Form │ │ │
│ │ │ - Result Display │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ └────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌────────────────────┴───────────────────────────┐ │
│ │ CSS (Styling) │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ style.css │ │ │
│ │ │ - Modern gradients │ │ │
│ │ │ - Responsive design │ │ │
│ │ │ - Animations │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ └────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌────────────────────┴───────────────────────────┐ │
│ │ JavaScript (Behavior) │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ app.js │ │ │
│ │ │ - predictSegment() │ │ │
│ │ │ - displayResult() │ │ │
│ │ │ - updateRangeValue() │ │ │
│ │ │ - fetch() API calls │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
User Input
│
▼
┌─────────────────────┐
│ Frontend │
│ Validation │
│ (JavaScript) │
│ - Range checks │
│ - Type checks │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Pydantic Schema │
│ Validation │
│ (CustomerInput) │
│ - Field types │
│ - Constraints │
│ - Validators │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Service Layer │
│ Business Logic │
│ - Model checks │
│ - Data integrity │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Model Layer │
│ ML Prediction │
│ - Safe transform │
│ - Error handling │
└──────────┬──────────┘
│
▼
Validated Response
┌─────────────────────────────────────────────────────────────┐
│ CUSTOMER SEGMENTATION MAP │
│ │
│ Spending │
│ Score │
│ 100 ┌──────────────────────────────────────────┐ │
│ │ │ │
│ 90 │ 💎 VIP/Whale ✨ Young │ │
│ │ (High/High) Trendsetter │ │
│ 80 │ (Low/High) │ │
│ │ │ │
│ 70 │ │ │
│ │ │ │
│ 60 │ 🎯 Average │ │
│ │ Customer │ │
│ 50 │ (Mid/Mid) │ │
│ │ │ │
│ 40 │ │ │
│ │ │ │
│ 30 │ 🎈 Budget 💰 High Earner │ │
│ │ Conscious Saver │ │
│ 20 │ (Low/Low) (High/Low) │ │
│ │ │ │
│ 10 └──────────────────────────────────────────┘ │
│ 15 30 50 70 90 120 150 │
│ Annual Income (k$) │
└─────────────────────────────────────────────────────────────┘
This visual architecture document helps understand:
- 🏗️ System structure
- 🔄 Data flow
- 📊 Request handling
- 🎨 Frontend organization
- 🔐 Security layers
- 📈 Customer segments
Perfect for:
- Understanding the system
- Onboarding new developers
- Planning enhancements
- Troubleshooting issues