# Variable Products - Data Flow Diagram

## Database → API → Frontend Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                         DATABASE                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  styles                          items                           │
│  ┌──────────┐                    ┌──────────────────────┐      │
│  │ id: 5    │◄───style_id────────│ id: 101              │      │
│  │ name:    │                    │ barcode: SKU-W-41    │      │
│  │ "m1s26"  │                    │ name: "Air Force 1"  │      │
│  │ active:1 │                    │ style_id: 5          │      │
│  └──────────┘                    │ color_id: 1 (White)  │      │
│       ▲                          │ size_id: 10 (41)     │      │
│       │                          │ price: 399           │      │
│       │                          └──────────────────────┘      │
│       │                                                         │
│       │                          ┌──────────────────────┐      │
│       └──────────────────────────│ id: 102              │      │
│                                  │ barcode: SKU-W-42    │      │
│                                  │ name: "Air Force 1"  │      │
│                                  │ style_id: 5          │      │
│                                  │ color_id: 1 (White)  │      │
│                                  │ size_id: 11 (42)     │      │
│                                  │ price: 399           │      │
│                                  └──────────────────────┘      │
│                                                                  │
│                                  ┌──────────────────────┐      │
│                                  │ id: 103              │      │
│                                  │ barcode: SKU-B-43    │      │
│                                  │ name: "Air Force 1"  │      │
│                                  │ style_id: 5          │      │
│                                  │ color_id: 2 (Black)  │      │
│                                  │ size_id: 12 (43)     │      │
│                                  │ price: 449           │      │
│                                  └──────────────────────┘      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    BACKEND API PROCESSING                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Step 1: Group by style_id                                      │
│  ┌────────────────────────────────────────────────────┐        │
│  │ SELECT MIN(id) as rep_id                           │        │
│  │ FROM items                                          │        │
│  │ GROUP BY COALESCE(style_id, id)                    │        │
│  │                                                     │        │
│  │ Result: rep_id = 101 (represents style_id 5)      │        │
│  └────────────────────────────────────────────────────┘        │
│                                                                  │
│  Step 2: Fetch all variants for style_id = 5                   │
│  ┌────────────────────────────────────────────────────┐        │
│  │ SELECT * FROM items WHERE style_id = 5             │        │
│  │                                                     │        │
│  │ Results: [101, 102, 103]                           │        │
│  └────────────────────────────────────────────────────┘        │
│                                                                  │
│  Step 3: Enrich card with variant data                         │
│  ┌────────────────────────────────────────────────────┐        │
│  │ • Collect unique colors: [White, Black]            │        │
│  │ • Collect unique sizes: [41, 42, 43]               │        │
│  │ • Calculate price range: 399 - 449                 │        │
│  │ • Aggregate stock: 45 total                        │        │
│  │ • Set requires_variant_selection: true             │        │
│  └────────────────────────────────────────────────────┘        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        API RESPONSE                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  {                                                               │
│    "id": 101,                                                    │
│    "barcode": "SKU-W-41",                                        │
│    "name": "Air Force 1",                                        │
│    "style": { "id": 5, "name": "m1s26" },                       │
│    "price": 399,                                                 │
│    "price_max": 449,                                             │
│    "available_qty": 45,                                          │
│    "in_stock": true,                                             │
│    "requires_variant_selection": true,                           │
│    "colors_preview": [                                           │
│      { "id": 1, "name": "White", "code": "#FFFFFF" },           │
│      { "id": 2, "name": "Black", "code": "#000000" }            │
│    ],                                                            │
│    "sizes_preview": [                                            │
│      { "id": 10, "name": "41" },                                 │
│      { "id": 11, "name": "42" },                                 │
│      { "id": 12, "name": "43" }                                  │
│    ],                                                            │
│    "image_url": "/api/storefront/media/...",                     │
│    "category": { "id": 3, "name": "Shoes" }                     │
│  }                                                               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     FRONTEND RENDERING                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────────────────────────────────────┐           │
│  │                                                  │           │
│  │  ┌────────────────────────────────────────┐    │           │
│  │  │                                         │    │           │
│  │  │         [Product Image]                 │    │           │
│  │  │                                         │    │           │
│  │  └────────────────────────────────────────┘    │           │
│  │                                                  │           │
│  │  Air Force 1                                    │           │
│  │                                                  │           │
│  │  Colors: ⚪ White  ⚫ Black                     │           │
│  │  Sizes:  [41] [42] [43]                        │           │
│  │                                                  │           │
│  │  399 EGP – 449 EGP                              │           │
│  │                                                  │           │
│  │  ┌──────────────────┐                          │           │
│  │  │  Select option   │ ◄── Not "Add to Cart"   │           │
│  │  └──────────────────┘                          │           │
│  │                                                  │           │
│  └─────────────────────────────────────────────────┘           │
│           ONE CARD (not 3 separate cards)                       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ User clicks "Select option"
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   PRODUCT DETAIL PAGE                            │
│                   /products/SKU-W-41                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  [Product Images Gallery]                                       │
│                                                                  │
│  Air Force 1                                                     │
│  Style: m1s26                                                    │
│                                                                  │
│  Select Color:                                                   │
│  ┌───────┐  ┌───────┐                                          │
│  │ White │  │ Black │  ◄── Clickable buttons                   │
│  └───────┘  └───────┘                                          │
│     ✓                                                            │
│                                                                  │
│  Select Size:                                                    │
│  ┌────┐  ┌────┐  ┌────┐                                        │
│  │ 41 │  │ 42 │  │ 43 │  ◄── Clickable buttons                │
│  └────┘  └────┘  └────┘                                        │
│    ✓                                                             │
│                                                                  │
│  Selected: White / 41                                            │
│  Barcode: SKU-W-41                                               │
│  Price: 399 EGP                                                  │
│  Stock: 15 available                                             │
│                                                                  │
│  ┌──────────────────┐                                           │
│  │  Add to Cart     │  ◄── Adds specific barcode to cart       │
│  └──────────────────┘                                           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## Key Points

1. **Database Level:**
   - Multiple items (SKUs) share the same `style_id`
   - Each item has unique `barcode`, `color_id`, `size_id`, `price`

2. **API Level:**
   - Groups items by `style_id` using SQL `GROUP BY`
   - Fetches all variants for displayed styles
   - Enriches card with aggregated data (colors, sizes, price range, stock)

3. **Frontend Level:**
   - Displays ONE card per style
   - Shows all available colors and sizes
   - "Select option" button for variable products
   - Detail page handles variant selection

4. **User Journey:**
   - Catalog: See all options at a glance
   - Click: Navigate to detail page
   - Select: Choose specific color/size
   - Add: Specific barcode added to cart

## Comparison: Before vs After

### BEFORE (Incorrect)
```
Catalog shows 5 cards:
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ AF1      │ │ AF1      │ │ AF1      │ │ AF1      │ │ AF1      │
│ White/41 │ │ White/42 │ │ White/44 │ │ Black/43 │ │ Black/44 │
│ 399 EGP  │ │ 399 EGP  │ │ 399 EGP  │ │ 449 EGP  │ │ 449 EGP  │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
```

### AFTER (Correct)
```
Catalog shows 1 card:
┌────────────────────────────┐
│ Air Force 1 (m1s26)        │
│ ⚪ White  ⚫ Black          │
│ [41] [42] [43] [44]        │
│ 399 - 449 EGP              │
│ [Select option]            │
└────────────────────────────┘
```

## Benefits

✅ **Cleaner catalog** - No duplicate listings  
✅ **Better UX** - See all options at once  
✅ **Accurate pagination** - Count products, not SKUs  
✅ **Faster browsing** - Fewer cards to scroll  
✅ **Clear pricing** - Price range visible upfront  
✅ **Stock visibility** - Aggregate stock shown  
✅ **Scalable** - Works with any number of variants