# Onboarding Flow Reorganization - Aligned with JTBD Analysis

## Problem Statement

The current AI-assisted path has some confusion:
1. "Review Suggestions" step helps complete the product list (from AI analysis)
2. "Inventory Setup" step should capture **initial stock** (crucial for system)
3. These two steps need better alignment and clear purpose
4. Must align with JTBD Analysis: users need to get up and running quickly with accurate inventory

## JTBD Analysis Key Findings (Recap)

From the initial JTBD analysis, bakery owners need to:
- **Job 1**: Get their inventory into the system quickly and accurately
- **Job 2**: Understand what products/ingredients they have and in what quantities
- **Job 3**: Start managing daily operations (production, sales) as soon as possible

**Critical Insight**: Initial stock levels are CRUCIAL - without them, the system cannot:
- Calculate if there's enough stock for production
- Alert about low stock
- Track consumption
- Provide accurate cost calculations

## Current Flow (Problematic)

### AI-Assisted Path (Current):
1. **Upload Sales Data** → User uploads historical sales
2. **AI Analysis** → System analyzes and suggests products
3. **Review Suggestions** → User reviews/edits suggested products ❌ *Missing: initial stock*
4. **Suppliers Setup** → Add suppliers
5. **Inventory Setup** → Add ingredients ❌ *Confusing: what about the products from step 3?*
6. **Recipes Setup** → Add recipes
7. ...rest of flow

**Problems:**
- Step 3 creates products but doesn't capture stock levels
- Step 5 adds ingredients but unclear relationship to step 3 products
- User has to enter stock levels twice (or not at all)
- Confusing UX: "Didn't I already add my inventory in step 3?"

## Proposed Reorganized Flow

### AI-Assisted Path (Reorganized):

```
Phase 1: DISCOVERY
├─ 1. Bakery Type Selection (Production/Retail/Mixed)
└─ 2. Data Source Choice (AI-assisted vs Manual)

Phase 2a: AI-POWERED SMART SETUP
├─ 3. Upload & Analyze Sales Data
│   ├─ Upload historical sales (CSV/Excel/JSON)
│   ├─ AI automatically classifies products
│   ├─ AI suggests categories and groupings
│   └─ AI estimates typical costs from sales data
│
├─ 4. Review & Complete Product List ⭐ ENHANCED
│   ├─ **Sub-step 4a: Review AI-Suggested Products**
│   │   ├─ See all products AI found in sales data
│   │   ├─ AI confidence scores for each classification
│   │   ├─ Edit/merge/delete suggested products
│   │   ├─ Add product images (optional)
│   │   └─ Quick actions: "Accept all", "Reject low confidence"
│   │
│   ├─ **Sub-step 4b: Categorize as Ingredients vs Finished Products** ⭐ KEY STEP
│   │   ├─ AI suggests initial categorization
│   │   ├─ User confirms which are INGREDIENTS (flour, sugar, etc.)
│   │   ├─ User confirms which are FINISHED PRODUCTS (bread, pastries)
│   │   ├─ Drag-and-drop interface for easy sorting
│   │   └─ WHY: System needs to know what can be used in recipes
│   │
│   └─ **Sub-step 4c: Set Initial Stock Levels** ⭐ CRITICAL
│       ├─ For each ingredient: "What's your current stock?"
│       ├─ For each finished product: "How many do you have now?"
│       ├─ Smart defaults based on typical quantities
│       ├─ Unit conversion helper (kg → g, dozens → units)
│       ├─ Batch entry option: "Set all to 0" or "Skip for now"
│       └─ WHY: Without initial stock, system can't function
│
├─ 5. Suppliers Setup (Quick)
│   ├─ AI suggests suppliers from sales data (if available)
│   ├─ User adds main suppliers (name, contact)
│   ├─ Can be minimal - just names to start
│   └─ Link suppliers to ingredients (optional at this stage)
│
└─ 6. [SKIP INVENTORY SETUP - Already done in step 4!]

Phase 2b: PRODUCTION SETUP (Conditional)
├─ 7a. Recipes Setup (if Production/Mixed bakery)
│   ├─ Can use ingredients from step 4
│   ├─ Template recipes for common items
│   └─ AI may suggest recipes based on product names
│
└─ 7b. Production Processes (if Retail/Mixed bakery)
    ├─ Simple baking/finishing processes
    └─ Template processes for common items

Phase 3: OPTIONAL FEATURES
├─ 8. Quality Standards (optional)
└─ 9. Team Members (optional)

Phase 4: FINALIZATION
├─ 10. ML Training (with real-time progress)
├─ 11. Review & Summary (show everything configured)
└─ 12. Completion & Next Steps
```

## Manual Path (Reorganized for Consistency)

```
Phase 1: DISCOVERY
├─ 1. Bakery Type Selection
└─ 2. Data Source Choice → "Manual"

Phase 2: MANUAL SETUP
├─ 3. Suppliers Setup
│   └─ Add main suppliers manually
│
├─ 4. Inventory Setup ⭐ COMBINED STEP
│   ├─ **Sub-step 4a: Add Ingredients**
│   │   ├─ Name, category, unit, supplier
│   │   ├─ Standard cost per unit
│   │   └─ **Initial stock quantity** ⭐
│   │
│   ├─ **Sub-step 4b: Add Finished Products**
│   │   ├─ Name, category, selling price
│   │   └─ **Initial stock quantity** ⭐
│   │
│   └─ Template library for quick start
│       ├─ Common ingredients (flour, sugar, etc.)
│       └─ Common products (bread, croissants, etc.)
│
├─ 5. Recipes/Processes Setup
│   └─ Based on bakery type
│
└─ 6-9. Optional features + Finalization
```

## Key Changes & Rationale

### 1. Combined "Review & Complete Product List" (Step 4 in AI path)

**Before:** Separate steps that were confusing
- Step 3: Review products (no stock)
- Step 5: Add ingredients (with stock)

**After:** One comprehensive step with 3 sub-steps
- 4a: Review AI suggestions
- 4b: Categorize (ingredients vs products)
- 4c: Set initial stock ⭐

**Benefits:**
- ✅ Single workflow for product setup
- ✅ Clear progression: identify → categorize → stock
- ✅ No confusion about "where do I add stock?"
- ✅ Captures initial stock for EVERYTHING
- ✅ Aligns with JTBD: get inventory into system quickly

### 2. AI Path Skips Redundant "Inventory Setup" Step

**Rationale:**
- All inventory already added in step 4
- No need for separate "add ingredients" step
- Reduces total steps (better UX)
- Prevents duplicate data entry

**Exception:**
- Users can still add NEW items later via dashboard
- Step 4 is comprehensive but not limiting

### 3. Manual Path Also Captures Initial Stock

**Why:**
- Consistency between AI and Manual paths
- Both paths MUST get initial stock
- Makes inventory setup atomic and complete

### 4. Sub-step 4b: Categorization Step

**Purpose:**
- System needs to know: ingredient vs finished product
- Ingredients → can be used in recipes
- Finished products → can be sold, tracked for inventory
- AI suggests, user confirms (or manual entry)

**UI Concept:**
```
┌─────────────────────────────────────────────────┐
│ Categorize Your Products                       │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌──────────────┐         ┌──────────────┐    │
│  │ Ingredients  │         │  Finished    │    │
│  │ (For Recipes)│         │  Products    │    │
│  │              │         │  (To Sell)   │    │
│  ├──────────────┤         ├──────────────┤    │
│  │ Flour        │  ←───   │ Baguette     │    │
│  │ Sugar        │    │    │ Croissant    │    │
│  │ Butter       │    │    │ Cake         │    │
│  │              │    │    │              │    │
│  └──────────────┘    │    └──────────────┘    │
│                      │                          │
│   Drag & drop to categorize                    │
│                                                 │
│  [< Previous]      [Skip for now]    [Next >] │
└─────────────────────────────────────────────────┘
```

### 5. Sub-step 4c: Initial Stock Entry

**UI Concept:**
```
┌─────────────────────────────────────────────────┐
│ Set Initial Stock Levels                       │
├─────────────────────────────────────────────────┤
│ 💡 Enter current quantities for accurate       │
│    tracking                                     │
│                                                 │
│ ┌─────────────────────────────────────────────┐│
│ │ Ingredients                                 ││
│ ├─────────────────────────────────────────────┤│
│ │ Flour (kg)        [____50____] kg          ││
│ │ Sugar (kg)        [____25____] kg          ││
│ │ Butter (kg)       [____10____] kg          ││
│ │ Eggs (units)      [____200___] units       ││
│ └─────────────────────────────────────────────┘│
│                                                 │
│ ┌─────────────────────────────────────────────┐│
│ │ Finished Products                           ││
│ ├─────────────────────────────────────────────┤│
│ │ Baguette (units)  [____30____] units       ││
│ │ Croissant (units) [____45____] units       ││
│ │ Cake (units)      [____12____] units       ││
│ └─────────────────────────────────────────────┘│
│                                                 │
│ Batch Actions:                                  │
│ [ Set all to 0 ]  [ Leave empty for now ]     │
│                                                 │
│  [< Previous]              [Complete Setup >]  │
└─────────────────────────────────────────────────┘
```

**Features:**
- Quick entry with keyboard navigation
- Smart defaults (AI can suggest typical quantities)
- Option to skip and add later (but encouraged to do now)
- Validation: warn if leaving many items at 0
- Unit conversion helper
- Batch operations for efficiency

## Updated Step Dependencies

```mermaid
graph TD
    A[Bakery Type] --> B[Data Source]
    B --> C{AI or Manual?}

    C -->|AI| D[Upload Sales Data]
    D --> E[AI Analysis]
    E --> F[Review & Complete Products]
    F --> F1[Review AI Suggestions]
    F1 --> F2[Categorize Items]
    F2 --> F3[Set Initial Stock]
    F3 --> G[Suppliers Quick Setup]
    G --> H[Recipes/Processes]

    C -->|Manual| I[Suppliers Setup]
    I --> J[Inventory Setup Combined]
    J --> J1[Add Ingredients + Stock]
    J1 --> J2[Add Products + Stock]
    J2 --> H

    H --> K[Optional Features]
    K --> L[ML Training]
    L --> M[Review Summary]
    M --> N[Completion]
```

## Implementation Checklist

### Phase 6.5: Flow Reorganization (1 week)

**Day 1-2: Enhanced Review Step**
- [ ] Split ReviewSuggestionsStep into 3 sub-steps
- [ ] Create ProductCategorizationUI component
- [ ] Create InitialStockEntryUI component
- [ ] Add drag-and-drop for categorization
- [ ] Add validation for stock entry

**Day 3-4: Backend Updates**
- [ ] Update product model to include `type` field (ingredient/finished_product)
- [ ] Add `initial_stock` capture in inventory endpoints
- [ ] Update AI analysis to suggest categorization
- [ ] Create endpoint for batch stock updates

**Day 5: Integration & Testing**
- [ ] Update UnifiedOnboardingWizard step flow
- [ ] Skip "Inventory Setup" in AI path
- [ ] Ensure Manual path includes stock entry
- [ ] End-to-end testing of both paths

## Success Metrics

### User Experience
- ✅ 90%+ of users complete initial stock entry
- ✅ Reduced confusion (fewer support tickets about "where to add stock")
- ✅ Faster onboarding (fewer steps in AI path)
- ✅ Higher data quality (complete inventory from start)

### System Functionality
- ✅ All inventory items have initial stock
- ✅ Production planning works from day 1
- ✅ Low stock alerts functional immediately
- ✅ Accurate cost calculations from start

## Migration Path

For existing implementations:
1. Add `type` field to existing inventory items (default: 'ingredient')
2. Backfill initial_stock from current stock where available
3. Prompt existing users to set stock levels on first login
4. Grandfather existing incomplete setups (warn but don't block)

## Conclusion

This reorganization:
- ✅ Eliminates confusion between product review and inventory setup
- ✅ Ensures initial stock is captured for ALL items
- ✅ Aligns with JTBD: users can start operating immediately
- ✅ Reduces total steps in AI path (better UX)
- ✅ Maintains consistency between AI and Manual paths
- ✅ Makes categorization (ingredient vs product) explicit and clear
- ✅ Provides better foundation for production planning and inventory management

**Next Step:** Implement Phase 6.5 to realize this reorganization.