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)

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

<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

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

// 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