bakery-ia/WIZARD_ARCHITECTURE_DESIGN.md

# Unified Add Wizard: Architecture & Component Design

## 🏗️ Component Hierarchy

```
UnifiedAddWizard (Main Orchestrator)
│
├── 📱 WizardContainer (Mobile-responsive wrapper)
│   │
│   ├── WizardHeader (Progress, close button)
│   │
│   ├── WizardContent (Scrollable main area)
│   │   │
│   │   ├── Step 0: ItemTypeSelector ⭐ (What do you want to add?)
│   │   │   └── 9 visual cards with icons
│   │   │
│   │   ├── Step 1+: Specific Wizards (Conditionally rendered)
│   │       │
│   │       ├── InventoryWizard
│   │       │   ├── Step 1: Type Selection (Ingredient vs Finished Product)
│   │       │   ├── Step 2: Core Details Form
│   │       │   └── Step 3: Initial Lot(s) Entry
│   │       │
│   │       ├── SupplierWizard (reuse existing)
│   │       │   ├── Step 1: Supplier Information
│   │       │   ├── Step 2: Ingredients & Pricing
│   │       │   └── Step 3: Review & Submit
│   │       │
│   │       ├── RecipeWizard (reuse existing)
│   │       │   ├── Step 1: Recipe Details
│   │       │   ├── Step 2: Ingredients Selection
│   │       │   ├── Step 3: Quality Templates
│   │       │   └── Step 4: Review
│   │       │
│   │       ├── EquipmentWizard
│   │       │   ├── Step 1: Equipment Type & Details
│   │       │   └── Step 2: Maintenance Schedule
│   │       │
│   │       ├── QualityTemplateWizard
│   │       │   ├── Step 1: Template Info
│   │       │   └── Step 2: Quality Checkpoints
│   │       │
│   │       ├── CustomerOrderWizard
│   │       │   ├── Step 1: Customer Selection/Creation
│   │       │   ├── Step 2: Order Items
│   │       │   └── Step 3: Delivery & Payment
│   │       │
│   │       ├── CustomerWizard
│   │       │   ├── Step 1: Customer Details
│   │       │   └── Step 2: Preferences & Terms
│   │       │
│   │       ├── TeamMemberWizard
│   │       │   ├── Step 1: Personal Details
│   │       │   └── Step 2: Role & Permissions
│   │       │
│   │       └── SalesEntryWizard ⭐⭐⭐ (CRITICAL)
│   │           ├── Step 1: Entry Method (Manual vs Upload)
│   │           ├── Step 2a: Manual Entry Form (if manual)
│   │           ├── Step 2b: File Upload & Mapping (if upload)
│   │           └── Step 3: Review & Confirm
│   │
│   └── WizardFooter (Actions: Back, Next, Submit)
│
└── WizardState (Context/hook for state management)
    ├── currentStep
    ├── selectedItemType
    ├── formData
    ├── validationErrors
    └── draftSaving
```

---

## 🎨 UI/UX Design Specifications

### Mobile-First Responsive Behavior

| Breakpoint | Behavior | Layout |
|------------|----------|--------|
| < 640px (Mobile) | Full-screen modal | Vertical stack, bottom buttons |
| 640-1024px (Tablet) | Centered modal (90% width) | Side-by-side where space allows |
| > 1024px (Desktop) | Drawer-style slide-in | Two-column layouts for forms |

### Touch Target Sizes (Mobile Optimization)

- **Minimum touch target:** 44px × 44px
- **Card buttons:** 100% width on mobile, min 120px height
- **Action buttons:** Full width on mobile, auto on desktop
- **Input fields:** min-height 48px (easy to tap)

### Visual Design System (Based on Existing Codebase)

#### Colors (from frontend/src/styles/colors.js)
```javascript
Primary: #d97706 (Amber-600) - Main actions, headers
Secondary: #16a34a (Green-600) - Success states
Accent: #0ea5e9 (Sky-500) - Info, links
Danger: #dc2626 (Red-600) - Errors, delete
Background: #ffffff (Light), #1f2937 (Dark)
Surface: #f3f4f6 (Light), #374151 (Dark)
Text: #111827 (Light), #f9fafb (Dark)
```

#### Typography
- **Headers (H1):** 24px (mobile), 32px (desktop), font-bold
- **Step titles (H2):** 20px (mobile), 24px (desktop), font-semibold
- **Body:** 16px, font-normal
- **Helper text:** 14px, text-gray-600

#### Spacing
- **Section gaps:** 24px (mobile), 32px (desktop)
- **Input gaps:** 16px
- **Card padding:** 16px (mobile), 24px (desktop)
- **Modal padding:** 16px (mobile), 32px (desktop)

---

## 🧩 Step 0: Item Type Selector Design

### Visual Layout (Mobile-First)

```
┌─────────────────────────────────────────┐
│  What would you like to add?            │
│  ─────────────────────────────────────  │
│                                          │
│  ┌──────────────┐  ┌──────────────┐    │
│  │  📦 Inventory│  │  🏢 Supplier │    │
│  │  Ingredient  │  │  Relationship│    │
│  │  or Product  │  │              │    │
│  └──────────────┘  └──────────────┘    │
│                                          │
│  ┌──────────────┐  ┌──────────────┐    │
│  │  📝 Recipe   │  │  🔧 Equipment│    │
│  │  Formula     │  │  Asset       │    │
│  └──────────────┘  └──────────────┘    │
│                                          │
│  ┌──────────────┐  ┌──────────────┐    │
│  │  ✅ Quality  │  │  🛒 Customer │    │
│  │  Template    │  │  Order       │    │
│  └──────────────┘  └──────────────┘    │
│                                          │
│  ┌──────────────┐  ┌──────────────┐    │
│  │  👤 Customer │  │  👥 Team     │    │
│  │  Profile     │  │  Member      │    │
│  └──────────────┘  └──────────────┘    │
│                                          │
│  ┌──────────────────────────────────┐   │
│  │  💰 Sales Entry                  │   │
│  │  Manual or Upload               │   │
│  │  ⭐ Most Common                  │   │
│  └──────────────────────────────────┘   │
│                                          │
└─────────────────────────────────────────┘
```

### Card Component Structure

```javascript
<ItemTypeCard>
  <Icon size="large" color="primary" /> {/* Emoji or SVG */}
  <Title>Inventory</Title>
  <Subtitle>Ingredient or Product</Subtitle>
  <Badge>Setup</Badge> {/* Contextual tags: Setup, Daily, Common */}
</ItemTypeCard>
```

### Interaction States
- **Default:** Light background, border
- **Hover (desktop):** Slight elevation, primary border
- **Active/Selected:** Primary background, white text
- **Focus:** Clear focus ring for keyboard nav

---

## 📋 Detailed Wizard Flows

### 1. Inventory Wizard (3 Steps)

#### Step 1: Type Selection
```
What type of inventory are you adding?

○ Ingredient
  Raw materials used in recipes
  Examples: Flour, sugar, eggs, butter

○ Finished Product
  Baked goods ready for sale
  Examples: Baguettes, croissants, cakes
```

#### Step 2: Core Details
**For Ingredient:**
- Name* (text)
- Category (dropdown: Flour, Dairy, Eggs, Fats, etc.)
- Unit of Measurement* (dropdown: kg, L, units)
- Storage Requirements (dropdown: Dry, Refrigerated, Frozen)
- Reorder Point (number, optional)
- Allergen Info (multi-select)

**For Finished Product:**
- Name* (text)
- Category (dropdown: Bread, Pastry, Cake, etc.)
- Recipe (dropdown from existing recipes, optional)
- Shelf Life (number + unit)
- Storage Requirements
- Selling Price (optional, can set later)

#### Step 3: Initial Lot(s)
```
Add starting inventory (optional but recommended)

Lot #1:
- Quantity* (number)
- Batch/Lot Number (text, optional)
- Expiry Date (date picker, if applicable)
- Supplier (dropdown, if known)
- Cost per Unit (number, optional)

[+ Add Another Lot]
```

---

### 2. Supplier Wizard (Reuse Existing + Enhancements)

**Already exists at:** `frontend/src/components/domain/suppliers/SupplierWizard/`

**Enhancements needed:**
- Ensure mobile responsive
- Add clear "Why we need this" helper text
- Allow skipping ingredients initially (can add later)

---

### 3. Recipe Wizard (Reuse Existing + Enhancements)

**Already exists at:** `frontend/src/components/domain/recipes/RecipeWizard/`

**Enhancements needed:**
- Check if ingredients exist; offer to add missing ones inline
- Mobile responsive step indicators
- Clearer quality template selection

---

### 4. Equipment Wizard (2 Steps)

#### Step 1: Equipment Details
- Equipment Type* (dropdown: Oven, Mixer, Proofer, Refrigerator, etc.)
- Brand/Model (text)
- Serial Number (text)
- Purchase Date (date picker)
- Location (text: "Main kitchen", "Prep area")
- Capacity (text: "20L bowl", "5 trays")
- Status (dropdown: Active, Maintenance, Retired)

#### Step 2: Maintenance Schedule
- Maintenance Frequency (dropdown: Weekly, Monthly, Quarterly, Annually)
- Last Maintenance Date (date picker)
- Next Maintenance Date (auto-calculated or manual)
- Notes (textarea: warranty info, service provider)

---

### 5. Quality Template Wizard (2 Steps)

#### Step 1: Template Info
- Template Name* (text: "Bread Quality Check", "Hygiene Checklist")
- Scope* (dropdown: Product Quality, Process Hygiene, Equipment, Safety)
- Applies To (multi-select products/recipes, optional)
- Frequency (dropdown: Every batch, Daily, Weekly)

#### Step 2: Quality Checkpoints
```
Define checkpoints for this template

Checkpoint #1:
- Check Name* (text: "Crust color")
- Check Type (dropdown: Visual, Measurement, Pass/Fail)
- Acceptance Criteria (text: "Golden brown, even")
- Critical? (checkbox: failure requires action)

[+ Add Another Checkpoint]
```

---

### 6. Customer Order Wizard (3 Steps)

#### Step 1: Customer Selection
```
Who is this order for?

[Search existing customers... 🔍]

Or create new customer:
- Name*
- Contact (phone or email)
- Type (dropdown: Retail, Wholesale, Event)

[Quick Add Customer]
```

#### Step 2: Order Items
```
What are they ordering?

Item #1:
- Product* (dropdown from inventory finished products)
- Quantity* (number + unit)
- Custom Requirements (text: "No nuts", "Extra chocolate")
- Price (pre-filled from product, editable)

[+ Add Another Item]

Order Summary: Total: $___
```

#### Step 3: Delivery & Payment
- Delivery Date* (date + time picker)
- Delivery Method (dropdown: Pickup, Delivery, Shipping)
- Delivery Address (if delivery)
- Payment Method (dropdown: Cash, Card, Invoice, Paid)
- Special Instructions (textarea)
- Order Status (auto: Pending, or manual: Confirmed, In Progress)

---

### 7. Customer Wizard (2 Steps)

#### Step 1: Customer Details
- Customer Name* (text)
- Customer Type* (dropdown: Retail, Wholesale, Event, Restaurant)
- Contact Person (text, for businesses)
- Phone Number (tel input)
- Email (email input)
- Address (textarea)

#### Step 2: Preferences & Terms
- Payment Terms (dropdown: Immediate, Net 15, Net 30)
- Preferred Delivery Days (multi-select: Mon-Sun)
- Dietary Restrictions/Allergies (multi-select or text)
- Discount Percentage (number, if wholesale)
- Notes (textarea: preferences, history)

---

### 8. Team Member Wizard (2 Steps)

#### Step 1: Personal Details
- Full Name* (text)
- Email* (email input, for system login)
- Phone Number (tel input)
- Position/Title* (dropdown: Baker, Pastry Chef, Manager, Sales, Delivery)
- Employment Type (dropdown: Full-time, Part-time, Contractor)
- Start Date (date picker)

#### Step 2: Role & Permissions
- System Role* (dropdown: Admin, Manager, Staff, View-Only)
- Permissions (checkboxes):
  - [ ] Manage Inventory
  - [ ] View Recipes
  - [ ] Create Orders
  - [ ] View Financial Data
  - [ ] Manage Team
- Schedule/Shift (text or structured input)
- Notes (textarea: certifications, training status)

---

### 9. Sales Entry Wizard ⭐⭐⭐ (CRITICAL - 3 Steps)

#### Step 1: Entry Method Selection
```
How would you like to add sales?

┌─────────────────────────────┐
│  ✏️ Manual Entry            │
│  Enter one or a few sales   │
│  Best for: Daily totals     │
└─────────────────────────────┘

┌─────────────────────────────┐
│  📄 Upload File             │
│  Import from Excel/CSV      │
│  Best for: Bulk historical  │
│  ⭐ Recommended for backlog │
└─────────────────────────────┘
```

---

#### Step 2a: Manual Entry (if Manual selected)
```
Enter sales details

Sale Date*: [Date Picker - defaults to today]
Time: [Time Picker - optional]

Items Sold:

Item #1:
- Product* (dropdown from inventory)
- Quantity* (number)
- Unit Price (pre-filled, editable)
- Subtotal (auto-calculated)

[+ Add Another Item]

Payment:
- Payment Method* (Cash, Card, Mobile Pay, Other)
- Total Amount (auto-summed or manual override)

Notes: (textarea - optional)

[Save & Add Another] [Save & Close]
```

**UX Optimization:**
- Default to today's date
- Remember last payment method used
- Quick "Repeat Last Sale" button for common items
- Show recent sales for reference

---

#### Step 2b: File Upload & Mapping (if Upload selected)

**Sub-step 1: Upload File**
```
Upload your sales data

Supported formats: CSV, Excel (.xlsx, .xls)

[Drag & drop file here or click to browse]

Download Template:
[📥 CSV Template] [📥 Excel Template]

Need help? See formatting guide →
```

**Sub-step 2: Column Mapping**
```
Map your file columns to our fields

Your File Column          →    Our Field
─────────────────────────────────────────
[Date ▼]                  →    Sale Date ✓
[Item ▼]                  →    Product Name ✓
[Quantity ▼]              →    Quantity ✓
[Price ▼]                 →    Unit Price ✓
[Total ▼]                 →    Total Amount ✓
[Payment ▼]               →    Payment Method ✓

Rows detected: 127
Rows with errors: 3 [View Errors →]

[Skip unmapped columns]
```

**Sub-step 3: Data Validation Preview**
```
Review imported data

Showing first 10 of 127 rows:

Date       | Product      | Qty | Price | Total | Status
─────────────────────────────────────────────────────────
2025-11-01 | Baguette     | 15  | $3.50 | $52.50| ✓ Valid
2025-11-01 | Croissant    | 22  | $4.00 | $88.00| ✓ Valid
2025-11-01 | Unknown Item | 5   | $5.00 | $25.00| ⚠️ Product not found
...

⚠️ 3 rows have issues
[View & Fix Errors]

✓ 124 rows ready to import

[Cancel] [Import Valid Rows Only] [Fix All First]
```

**Error Handling:**
- Show specific errors inline ("Product 'Donut' not found. Did you mean 'Doughnut'?")
- Offer to create missing products on the fly
- Suggest date format corrections
- Allow skipping invalid rows or fixing in bulk

---

#### Step 3: Review & Confirm (Both Methods)

**For Manual Entry:**
```
Review your sale

Date: November 9, 2025
Items:
  • Baguette × 15 @ $3.50 = $52.50
  • Croissant × 8 @ $4.00 = $32.00

Total: $84.50
Payment: Cash

[← Edit] [✓ Confirm & Save]
```

**For File Upload:**
```
Import Summary

Successfully imported: 124 sales
Skipped (errors): 3
Total revenue: $4,567.89
Date range: Nov 1 - Nov 9, 2025

[View Imported Sales] [Add More Sales] [Done]
```

---

## 🔄 State Management & Data Flow

### Context Structure

```javascript
const WizardContext = {
  // Navigation
  currentStep: 0,
  totalSteps: 3,
  selectedItemType: null, // 'inventory', 'supplier', etc.

  // Data
  formData: {}, // Step-specific data
  validationErrors: {},

  // Actions
  goToStep: (step) => {},
  nextStep: () => {},
  prevStep: () => {},
  setItemType: (type) => {},
  updateFormData: (data) => {},
  submitWizard: async () => {},

  // Draft saving
  saveDraft: () => {}, // Auto-save to localStorage
  loadDraft: () => {},
  clearDraft: () => {},

  // Utilities
  isStepValid: (step) => boolean,
  canProceed: () => boolean,
}
```

### API Integration Pattern

```javascript
// Use existing React Query hooks
const { mutate: createItem, isLoading } = useCreateItem(itemType);

const handleSubmit = async (formData) => {
  try {
    await createItem(formData);
    showSuccessMessage();
    onClose();
    // Suggest next action
  } catch (error) {
    showErrorMessage(error);
  }
};
```

---

## 🎯 Progressive Disclosure Strategy

### Level 1: Item Type Selection (Cognitive Load: Low)
**Show:** 9 visual cards with clear icons and descriptions
**Hide:** All form complexity

### Level 2: Wizard Steps (Cognitive Load: Medium)
**Show:** Only current step, progress indicator, clear next action
**Hide:** Other steps, advanced options (collapsible)

### Level 3: Within Step (Cognitive Load: Low per section)
**Show:** Required fields first, grouped logically
**Hide:** Optional fields in "Advanced Options" accordion

### Level 4: Help & Context (Available on demand)
**Show:** ? icons for field-specific help tooltips
**Hide:** Lengthy explanations unless requested

---

## 📱 Mobile-Specific Optimizations

### Navigation
- **Bottom sheet on mobile** (easier thumb reach)
- **Swipe gestures** to go back/forward between steps
- **Sticky footer buttons** always visible

### Input Methods
- **Native date/time pickers** on mobile
- **Autocomplete** for product/customer selection
- **Camera integration** for barcode scanning (future enhancement)

### Performance
- **Lazy load** individual wizards (code splitting)
- **Debounced validation** (don't validate on every keystroke)
- **Optimistic UI updates** for better perceived performance

### Offline Support (Future)
- Save drafts to localStorage
- Queue submissions when offline
- Sync when connection restored

---

## ✅ Validation Strategy

### Real-time Validation
- Required field indicators (asterisk)
- Field-level validation on blur
- Clear error messages below fields
- Success indicators (green checkmark) when valid

### Step-level Validation
- "Next" button disabled until step is valid
- Summary of errors at top if user tries to proceed
- Auto-focus first invalid field

### Relationship Validation
- Check if recipe ingredients exist in inventory
- Warn if adding duplicate items
- Suggest existing items that match (fuzzy search)

---

## 🎉 Success States & Next Actions

### After Successful Creation

```
┌─────────────────────────────────────┐
│  ✅ Ingredient Added Successfully!  │
│                                      │
│  "Organic Flour" has been added     │
│  to your inventory.                 │
│                                      │
│  What would you like to do next?    │
│                                      │
│  [+ Add Another Ingredient]         │
│  [📝 Create Recipe Using This]      │
│  [📊 View Inventory]                │
│  [✕ Close]                          │
└─────────────────────────────────────┘
```

### Contextual Next Actions by Item Type

| Item Type | Suggested Next Actions |
|-----------|------------------------|
| Inventory | Add supplier, Create recipe, Add initial lot |
| Supplier | Add ingredients they supply, View suppliers list |
| Recipe | Add ingredients, Create quality template, Close |
| Equipment | Add maintenance schedule, View equipment list |
| Quality Template | Apply to recipes, View templates |
| Customer Order | Add another order, View orders, Create production batch |
| Customer | Create order for this customer, View customers |
| Team Member | Assign permissions, Add another member |
| Sales Entry | Add more sales, View sales report, Close |

---

## 🚀 Implementation Roadmap

### Phase 1: Foundation (Week 1)
- [ ] Create UnifiedAddWizard shell component
- [ ] Implement ItemTypeSelector step
- [ ] Build WizardContainer with mobile responsive layout
- [ ] Set up WizardContext for state management

### Phase 2: P0 Wizards (Week 2-3)
- [ ] Sales Entry Wizard (manual + upload) ⭐
- [ ] Customer Order Wizard
- [ ] Inventory Wizard
- [ ] Enhance existing Recipe & Supplier wizards

### Phase 3: P1 Wizards (Week 4)
- [ ] Customer Wizard
- [ ] Quality Template Wizard
- [ ] Equipment Wizard
- [ ] Team Member Wizard

### Phase 4: Integration & Polish (Week 5)
- [ ] Add "Add" button to dashboard
- [ ] Update individual page buttons
- [ ] Mobile testing & refinements
- [ ] Accessibility audit (WCAG 2.1 AA)
- [ ] Performance optimization

### Phase 5: Advanced Features (Future)
- [ ] Draft auto-saving with recovery
- [ ] Keyboard shortcuts (Cmd+K to open wizard)
- [ ] Barcode scanning for inventory
- [ ] Voice input for manual sales entry
- [ ] Batch operations (add multiple items at once)

---

## 📊 Success Metrics (How We'll Know It Works)

### Quantitative Metrics
- **Task completion rate** > 95%
- **Time to complete** each wizard < 2 min
- **Error rate** < 5%
- **Mobile usage** > 40% of total
- **Adoption rate** > 80% within 2 weeks

### Qualitative Metrics
- Users report feeling "guided" and "confident"
- Reduction in support requests about "how to add X"
- Positive feedback on mobile usability
- Sales data completeness improves (especially for non-POS users)

---

## 🔒 Accessibility Checklist

- [ ] Keyboard navigable (Tab, Enter, Esc)
- [ ] Screen reader compatible (ARIA labels)
- [ ] Color contrast meets WCAG AA (4.5:1)
- [ ] Focus indicators always visible
- [ ] Error messages announced to screen readers
- [ ] Touch targets ≥ 44px (mobile)
- [ ] Form labels properly associated
- [ ] Step progress announced

---

**Document Version:** 1.0
**Date:** 2025-11-09
**Status:** Architecture Complete - Ready for Implementation
**Next Step:** Begin Phase 1 Implementation