bakery-ia/docs/wizard-flow-specification.md

Bakery Setup Wizard - Complete Flow Specification

Version: 1.0 Date: 2025-11-06 Status: Design Specification Related: jtbd-analysis-inventory-setup.md

---

📋 Table of Contents

1. Executive Summary
2. Design Principles
3. Wizard Architecture
4. Complete Step Sequence
5. Step Specifications (Detailed)
6. Progress Tracking & Navigation
7. Validation & Error Handling
8. Smart Features
9. Technical Implementation Notes
10. Success Metrics

---

Executive Summary

Problem Statement

After completing the initial onboarding wizard (Register Bakery → Upload Sales Data → ML Training → Completion), users are dropped onto a dashboard with no guidance on how to set up the foundational data needed for daily operations. This creates:

• High abandonment rates (users don't complete setup)
• Data quality issues (incomplete or incorrect entries)
• Delayed time-to-value (can't use the system effectively)

Solution Overview

Guided Bakery Setup Journey: A continuation of the onboarding wizard that walks users through setting up suppliers, inventory, recipes, quality standards, and team in a logical, dependency-aware sequence.

Key Innovations

1. Continuous Journey: Extends onboarding wizard (Step 5+) instead of separate flow
2. Dependency Awareness: Enforces order (suppliers before inventory before recipes)
3. Progressive Disclosure: Shows complex options only when needed
4. Flexible Pacing: Save progress, skip optional steps, resume later
5. Contextual Guidance: Every step explains why it matters and what comes next
6. Celebration Moments: Recognizes milestones to maintain motivation

---

Design Principles

1. Guide, Don't Block

Principle: Provide clear direction while allowing flexibility

• ✅ Suggest optimal path but allow users to skip optional steps
• ✅ Show what's incomplete without preventing progress
• ❌ Don't force users into rigid workflows
• ❌ Don't hide advanced options from experienced users

2. Explain, Don't Assume

Principle: Use plain language and provide context

• ✅ Explain why each step matters to bakery operations
• ✅ Use bakery terminology, not software jargon
• ✅ Provide examples and common values
• ❌ Don't assume users understand database concepts
• ❌ Don't use technical terms without explanation

3. Validate Early, Fail Friendly

Principle: Catch errors before they happen, provide helpful guidance

• ✅ Real-time validation as users type
• ✅ Helpful error messages with suggestions
• ✅ Prevent invalid states (dependencies, cross-field validation)
• ❌ Don't wait until submit to show errors
• ❌ Don't show technical error messages

4. Progress Over Perfection

Principle: Help users make progress, even if data isn't perfect

• ✅ Allow "good enough" data to move forward
• ✅ Clearly mark what's required vs. optional
• ✅ Allow editing later without redoing the entire wizard
• ❌ Don't demand perfection that prevents progress
• ❌ Don't make optional fields feel required

5. Show Value Early

Principle: Unlock features as users progress

• ✅ Show what becomes possible after each step
• ✅ Preview features before they're available
• ✅ Celebrate completion milestones
• ❌ Don't wait until the end to show value
• ❌ Don't make setup feel like busywork

---

Wizard Architecture

Overall Flow Structure

┌─────────────────────────────────────────────────────────────┐
│  EXISTING ONBOARDING WIZARD (Steps 1-4)                     │
│  ────────────────────────────────────────────────────────   │
│  1. Register Tenant (setup)                                 │
│  2. Configure Inventory (smart-inventory-setup)             │
│  3. Train AI (ml-training)                                  │
│  4. Completion                                              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  NEW: BAKERY SETUP WIZARD (Steps 5-11)                      │
│  ────────────────────────────────────────────────────────   │
│  PHASE 1: ORIENTATION & PLANNING                            │
│  5. Welcome & Setup Overview (setup-welcome)                │
│                                                              │
│  PHASE 2: CORE DEPENDENCIES (Critical Path)                 │
│  6. Add Suppliers (suppliers-setup)                         │
│  7. Set Up Inventory Items (inventory-items-setup)          │
│                                                              │
│  PHASE 3: OPERATIONAL DATA (Required for Production)        │
│  8. Create Recipes (recipes-setup)                          │
│  9. Define Quality Standards (quality-setup)                │
│                                                              │
│  PHASE 4: TEAM & FINALIZATION (Optional but Recommended)    │
│  10. Add Team Members (team-setup) [OPTIONAL]               │
│  11. Review & Launch (setup-completion)                     │
└─────────────────────────────────────────────────────────────┘

Integration Point

• Trigger: When user completes existing Step 4 (Completion)
• Transition: Instead of navigating to dashboard, show "One more thing..." modal
• Modal Content: "Great start! Now let's set up your daily operations. This will take about 10-15 minutes and unlock powerful features like recipe costing, inventory tracking, and quality monitoring."
• User Choice:
  • "Set Up Now" (recommended) → Enter wizard at Step 5
  • "I'll Do This Later" → Go to dashboard with persistent "Complete Setup" banner

Step Categories

Category	Steps	Required?	Can Skip?	Estimated Time
Orientation	Step 5 (Welcome)	No	Yes	2 min
Critical Path	Steps 6-7 (Suppliers, Inventory)	Yes	No	5-8 min
Production Setup	Steps 8-9 (Recipes, Quality)	Yes	No	5-10 min
Team Setup	Step 10 (Team)	No	Yes	2-5 min
Completion	Step 11 (Review)	No	Yes	1-2 min

Total Estimated Time: 15-27 minutes (depending on data complexity)

---

Complete Step Sequence

PHASE 1: ORIENTATION & PLANNING

Step 5: Welcome & Setup Overview (setup-welcome)

Purpose: Orient user to what's ahead, reduce anxiety, set expectations

User Job: "Help me understand what I need to set up and why"

Content:

• Welcome message: "You've trained your AI. Now let's set up your daily operations."
• Visual roadmap showing all steps ahead
• Time estimate: "This takes about 15-20 minutes"
• What you'll need: "Have ready: supplier info, ingredient list, common recipes"
• What you'll gain: Feature preview cards showing value

UI Components:

┌──────────────────────────────────────────────────────┐
│  🎉 Excellent! Your AI is Ready                      │
│                                                       │
│  Now let's set up your bakery's daily operations     │
│  so the system can help you manage:                  │
│                                                       │
│  ✓ Inventory tracking & reorder alerts              │
│  ✓ Recipe costing & profitability analysis          │
│  ✓ Quality standards & production monitoring         │
│  ✓ Team coordination & task assignment              │
│                                                       │
│  ⏱️ Takes about 15-20 minutes                        │
│                                                       │
│  📋 What You'll Set Up:                              │
│  ────────────────────────────────────────────────    │
│  [CARD] Suppliers        | 2-3 min  | Required      │
│  [CARD] Inventory Items  | 5-8 min  | Required      │
│  [CARD] Recipes          | 5-10 min | Required      │
│  [CARD] Quality Checks   | 3-5 min  | Required      │
│  [CARD] Team Members     | 2-5 min  | Optional      │
│                                                       │
│  💡 You can save progress and resume anytime         │
│                                                       │
│  [Skip for Now]           [Let's Get Started! →]    │
└──────────────────────────────────────────────────────┘

Validation: None (informational step)

Navigation:

• Next: Step 6 (Suppliers Setup)
• Skip: Go to dashboard with "Resume Setup" banner

Backend: Mark setup-welcome as completed

---

PHASE 2: CORE DEPENDENCIES (Critical Path)

Step 6: Add Suppliers (suppliers-setup)

Purpose: Set up supplier relationships as foundation for inventory

User Job: "Add my suppliers so I can track where ingredients come from and manage orders"

Why This Step:

"Suppliers are the source of your ingredients. Setting them up now lets you track costs, manage orders, and analyze supplier performance."

What Users Need to Add: Minimum 1 supplier (recommended 2-3)

Form Type: Wizard-Enhanced List Entry

UI Flow:

┌──────────────────────────────────────────────────────┐
│  Step 2 of 7: Add Your Suppliers                     │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  💼 Suppliers                                         │
│  Your ingredient and material providers              │
│                                                       │
│  [==========>------------------] 29% Complete        │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  Why This Matters                            │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Tracking suppliers helps you:               │   │
│  │  • Compare ingredient costs                  │   │
│  │  • Manage purchase orders                    │   │
│  │  • Analyze delivery performance              │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  📝 Your Suppliers (1 required, 2-3 ideal)   │   │
│  │                                               │   │
│  │  [+ Add Your First Supplier]                 │   │
│  │                                               │   │
│  │  Empty state illustration                     │   │
│  │  "Add at least one supplier to continue"     │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  💡 Tip: Start with your most frequently used        │
│     supplier. You can add more later.                │
│                                                       │
│  [← Back]                        [Skip] [Continue →] │
│  (disabled until 1 supplier added)                   │
└──────────────────────────────────────────────────────┘

When "Add Supplier" clicked → Opens inline wizard modal:

┌──────────────────────────────────────────────────────┐
│  ✕ Add Supplier                                       │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  Basic Information                                   │
│  ────────────────────────────────────────────────    │
│  Supplier Name *                                     │
│  [_____________________________________________]      │
│   e.g., "Molinos del Norte", "Ingredientes García"   │
│                                                       │
│  Supplier Type *                                     │
│  [▼ Select type___________________________]          │
│      ├─ Ingredients (flour, sugar, yeast...)         │
│      ├─ Packaging (boxes, bags, labels...)           │
│      └─ Equipment (mixers, ovens...)                 │
│                                                       │
│  Contact Information (Optional)                      │
│  ────────────────────────────────────────────────    │
│  ▼ Show optional fields                              │
│                                                       │
│  [Add Another Supplier]         [Cancel] [Add →]     │
└──────────────────────────────────────────────────────┘

Fields:

Field	Type	Required	Validation	Help Text
name	text	Yes	Min 2 chars	"The business name of your supplier"
supplier_type	select	Yes	Must select	"Ingredients, Packaging, or Equipment"
contact_name	text	No	-	"Main contact person at this supplier"
email	email	No	Valid email	"For sending purchase orders"
phone	tel	No	Valid phone	"For quick inquiries"
payment_terms	select	No	-	"Net 30, Net 60, Prepaid, COD..."
status	select	No	Default: Active	"Active, Inactive, Preferred"

After Adding Suppliers:

┌──────────────────────────────────────────────────────┐
│  📝 Your Suppliers (2 added) ✓                       │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 💼 Molinos del Norte                       │ [⋮]  │
│  │    Type: Ingredients  │  Status: Active    │     │
│  │    Contact: Juan García                    │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 📦 Empaques Premium                        │ [⋮]  │
│  │    Type: Packaging  │  Status: Active      │     │
│  │    Contact: María López                    │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [+ Add Another Supplier]                            │
│                                                       │
│  ✅ Great! You've added 2 suppliers                  │
│                                                       │
│  [← Back]                  [Continue to Inventory →] │
└──────────────────────────────────────────────────────┘

Validation:

• Minimum: 1 supplier required to continue
• Real-time: Check for duplicate names
• Business Rule: At least one "Ingredients" type supplier recommended (show warning if none)

Navigation:

• Continue: Only enabled when ≥1 supplier added
• Skip: Allowed, but shows warning: "You'll need suppliers later for purchase orders"

Backend:

• Save each supplier via POST /api/v1/suppliers/
• Mark step suppliers-setup as completed
• Store count in step data: {suppliers_added: 2}

Smart Features:

• Template Suppliers: "Use common supplier template" button → Pre-fills with typical Spanish bakery suppliers
• Bulk Import: "Import from spreadsheet" (CSV with name, type, contact)

---

Step 7: Set Up Inventory Items (inventory-items-setup)

Purpose: Add the ingredients and materials used in bakery operations

User Job: "Add my ingredients so the system can track inventory levels and costs"

Why This Step:

"Inventory items are the building blocks of your recipes. Once set up, the system will track quantities, alert you when stock is low, and help you calculate recipe costs."

What Users Need to Add: Minimum 3 inventory items (recommended 10-15 for starter set)

Dependency: Requires ≥1 supplier from Step 6

Form Type: Wizard-Enhanced List Entry with Bulk Options

UI Flow:

┌──────────────────────────────────────────────────────┐
│  Step 3 of 7: Set Up Inventory Items                 │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  📦 Inventory Items                                   │
│  Ingredients and materials you use                   │
│                                                       │
│  [====================>--------] 57% Complete        │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  Why This Matters                            │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Inventory tracking enables:                 │   │
│  │  • Low stock alerts (never run out!)        │   │
│  │  • Automatic reorder suggestions             │   │
│  │  • Accurate recipe costing                   │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  📝 Your Inventory (3 min required, 10 ideal)│   │
│  │                                               │   │
│  │  [+ Add Item] [📥 Import Spreadsheet]        │   │
│  │  [📋 Use Starter Template]                   │   │
│  │                                               │   │
│  │  (Empty state)                                │   │
│  │  "Add your most common ingredients first"    │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  💡 Quick Start: Use our starter template with       │
│     common bakery ingredients (flour, sugar, eggs,   │
│     butter...). You can customize them after.        │
│                                                       │
│  [← Back to Suppliers]         [Skip] [Continue →]   │
│  (disabled until 3 items added)                      │
└──────────────────────────────────────────────────────┘

Starter Template Feature:

When user clicks "Use Starter Template":

┌──────────────────────────────────────────────────────┐
│  ✕ Add Starter Ingredients                           │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  We'll add common bakery ingredients to get you      │
│  started. You can edit or remove any items.          │
│                                                       │
│  ☑️ Flour (White Bread Flour) - kg                   │
│  ☑️ Flour (Whole Wheat) - kg                         │
│  ☑️ Sugar (White Granulated) - kg                    │
│  ☑️ Butter (Unsalted) - kg                           │
│  ☑️ Eggs (Large) - units                             │
│  ☑️ Milk (Whole) - liters                            │
│  ☑️ Yeast (Active Dry) - kg                          │
│  ☑️ Salt (Fine) - kg                                 │
│  ☑️ Water - liters                                   │
│  ☑️ Chocolate Chips - kg                             │
│                                                       │
│  Assign Supplier (Optional):                         │
│  [▼ Molinos del Norte________________]               │
│      (will be set as supplier for flour & sugar)     │
│                                                       │
│  [Cancel]               [Add Selected Items (10) →]  │
└──────────────────────────────────────────────────────┘

Manual Add Item Modal:

┌──────────────────────────────────────────────────────┐
│  ✕ Add Inventory Item                  [Step 1 of 2] │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ▼ Basic Information                                 │
│  ────────────────────────────────────────────────    │
│  Item Name *                                         │
│  [_____________________________________________]      │
│   e.g., "Harina de trigo 000", "Azúcar blanca"       │
│                                                       │
│  Category *                                          │
│  [▼ Select category_______________________]          │
│      ├─ Flour & Grains                               │
│      ├─ Dairy & Eggs                                 │
│      ├─ Sweeteners                                   │
│      ├─ Fats & Oils                                  │
│      ├─ Leavening Agents                             │
│      ├─ Flavorings & Additives                       │
│      └─ Packaging Materials                          │
│                                                       │
│  Unit of Measure *                                   │
│  [▼ Kilograms________________________]               │
│      ├─ Kilograms (kg)                               │
│      ├─ Grams (g)                                    │
│      ├─ Liters (L)                                   │
│      ├─ Milliliters (ml)                             │
│      └─ Units (pieces)                               │
│                                                       │
│  ▼ Supplier & Pricing (Optional - can add later)    │
│  ────────────────────────────────────────────────    │
│  ▶ Show optional fields                              │
│                                                       │
│  [Cancel]           [Continue to Stock Levels →]     │
└──────────────────────────────────────────────────────┘

Step 2 of Add Item (Stock & Reorder Levels):

┌──────────────────────────────────────────────────────┐
│  ✕ Add Inventory Item                  [Step 2 of 2] │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ✓ Harina de trigo 000 │ Flour & Grains │ kg        │
│                                                       │
│  ▼ Stock Levels & Alerts                             │
│  ────────────────────────────────────────────────    │
│  Current Stock (Optional)                            │
│  [________] kg                                        │
│   How much do you have right now?                    │
│                                                       │
│  Low Stock Alert At                                  │
│  [________] kg        (Recommended: 10-20 kg)        │
│   You'll get notified when stock falls below this    │
│                                                       │
│  Reorder Point                                       │
│  [________] kg        (Recommended: 5 kg)            │
│   System will suggest reordering at this level       │
│                                                       │
│  ▼ Advanced Options (Optional)                       │
│  ────────────────────────────────────────────────    │
│  ▶ Pricing, Shelf Life, SKU/Barcode                 │
│                                                       │
│  💡 Don't worry if you don't know exact numbers.     │
│     You can adjust these anytime based on usage.     │
│                                                       │
│  [← Back]          [Add Another Item] [Save & Done]  │
└──────────────────────────────────────────────────────┘

Fields (Complete List):

Step 1 - Required:

Field	Type	Required	Validation	Help Text
name	text	Yes	Min 2 chars, unique	"The name you use for this item"
category	select	Yes	Must select	"Helps organize your inventory"
unit_of_measure	select	Yes	Must select	"How this item is measured"

Step 2 - Stock Levels:

Field	Type	Required	Validation	Help Text
current_quantity	number	No	≥0	"Current stock on hand"
low_stock_threshold	number	No	≥0	"Alert me when below this level"
reorder_point	number	No	≥0, ≤ low_stock	"Suggest reorder at this level"

Advanced - Optional:

Field	Type	Required	Validation	Help Text
supplier_id	select	No	Must exist	"Primary supplier for this item"
standard_cost	currency	No	≥0	"Typical cost per unit"
sku	text	No	Unique	"Stock keeping unit code"
barcode	text	No	Valid barcode	"For scanning"
shelf_life_days	number	No	>0	"Days until expires"

After Adding Items:

┌──────────────────────────────────────────────────────┐
│  📝 Your Inventory Items (12 added) ✓                │
│                                                       │
│  Filter by: [All▼] [Search: _______________] [⚙️]    │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 🌾 Harina de trigo 000                     │ [⋮]  │
│  │    Flour & Grains  │  50 kg  │  Low: 20 kg │     │
│  │    Supplier: Molinos del Norte             │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 🥚 Eggs (Large)                            │ [⋮]  │
│  │    Dairy & Eggs  │  200 units  │  Low: 50  │     │
│  │    No supplier set                         │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [... 10 more items ...]                             │
│                                                       │
│  [+ Add Item] [Import] [Use Template]                │
│                                                       │
│  ✅ Excellent! You've set up 12 inventory items      │
│                                                       │
│  [← Back to Suppliers]        [Continue to Recipes →]│
└──────────────────────────────────────────────────────┘

Validation:

• Minimum: 3 items required to continue
• Real-time: Check for duplicate names within category
• Business Rules:
  • Warn if no flour items (common for bakeries)
  • Warn if reorder_point > low_stock_threshold
  • Suggest supplier if none set for "Ingredients" type items

Navigation:

• Continue: Enabled when ≥3 items added
• Skip: Allowed with warning: "Recipes require ingredients. Sure you want to skip?"

Backend:

• Save each item via POST /api/v1/inventory/ingredients/
• For starter template: Bulk create via POST /api/v1/inventory/ingredients/bulk/
• Mark step inventory-items-setup as completed
• Store count: {inventory_items_added: 12, used_template: true}

Smart Features:

• Smart Categories: Auto-suggest category based on item name (ML)
• Unit Conversion: "Convert between units" helper
• Supplier Recommendation: Based on item category, suggest relevant suppliers from Step 6
• Bulk Edit: "Edit multiple items" for updating low stock thresholds

Progress Indicator Within Step:

┌──────────────────────────────────────┐
│  Progress: 12 items added            │
│  ▰▰▰▱▱ Minimum met (3+)  ✓           │
│  ▰▰▰▰▰ Recommended (10+) ✓           │
└──────────────────────────────────────┘

---

PHASE 3: OPERATIONAL DATA (Required for Production)

Step 8: Create Recipes (recipes-setup)

Purpose: Define production recipes using inventory items

User Job: "Add my recipes so the system can calculate costs, track production, and manage ingredient usage"

Why This Step:

"Recipes connect your inventory to production. The system will calculate exact costs per item, track ingredient consumption, and help you optimize your menu profitability."

What Users Need to Add: Minimum 1 recipe (recommended 3-5 core products)

Dependency: Requires ≥3 inventory items from Step 7

Form Type: Multi-Step Recipe Builder

UI Flow:

┌──────────────────────────────────────────────────────┐
│  Step 4 of 7: Create Your Recipes                    │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  👨‍🍳 Recipes                                           │
│  Your bakery's production formulas                   │
│                                                       │
│  [=============================>---] 71% Complete    │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  Why This Matters                            │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Recipes unlock powerful features:           │   │
│  │  • Automatic ingredient cost calculation     │   │
│  │  • Production planning & scheduling          │   │
│  │  • Inventory consumption tracking            │   │
│  │  • Profitability analysis per product        │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  📝 Your Recipes (1 min required, 3-5 ideal) │   │
│  │                                               │   │
│  │  [+ Create Recipe] [📋 Use Recipe Template]  │   │
│  │                                               │   │
│  │  (Empty state)                                │   │
│  │  "Create recipes for your core products"     │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  💡 Quick Start: Use recipe templates for common     │
│     baked goods. Adjust quantities to match yours.   │
│                                                       │
│  [← Back to Inventory]            [Skip] [Continue →]│
│  (disabled until 1 recipe added)                     │
└──────────────────────────────────────────────────────┘

Recipe Template Gallery:

┌──────────────────────────────────────────────────────┐
│  ✕ Choose Recipe Template                            │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  Select a template to customize, or create from      │
│  scratch:                                            │
│                                                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │  🥖      │  │  🍞      │  │  🥐      │          │
│  │ Baguette │  │  White   │  │ Croissant│          │
│  │ Francesa │  │  Bread   │  │          │          │
│  └──────────┘  └──────────┘  └──────────┘          │
│                                                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │  🍰      │  │  🧁      │  │  ➕      │          │
│  │  Cake    │  │ Muffins  │  │  Create  │          │
│  │  Sponge  │  │ Blueberry│  │  Blank   │          │
│  └──────────┘  └──────────┘  └──────────┘          │
│                                                       │
│  [Cancel]                                            │
└──────────────────────────────────────────────────────┘

Create Recipe - Step 1 (Basic Info):

┌──────────────────────────────────────────────────────┐
│  ✕ Create Recipe                       [Step 1 of 3] │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  Recipe Information                                  │
│  ────────────────────────────────────────────────    │
│  Recipe Name *                                       │
│  [_____________________________________________]      │
│   e.g., "Baguette Francesa", "Pan de Molde"          │
│                                                       │
│  Category *                                          │
│  [▼ Select category_______________________]          │
│      ├─ Bread                                        │
│      ├─ Pastry                                       │
│      ├─ Cake                                         │
│      ├─ Cookie                                       │
│      └─ Specialty                                    │
│                                                       │
│  Batch Yield *                                       │
│  [_____] units                                        │
│   How many items does this recipe make?              │
│                                                       │
│  Preparation Time (Optional)                         │
│  [_____] minutes                                      │
│                                                       │
│  Description (Optional)                              │
│  [_____________________________________________]      │
│  [_____________________________________________]      │
│   Brief description or notes about this recipe       │
│                                                       │
│  [Cancel]                    [Continue to Ingredients →]│
└──────────────────────────────────────────────────────┘

Create Recipe - Step 2 (Add Ingredients):

┌──────────────────────────────────────────────────────┐
│  ✕ Create Recipe                       [Step 2 of 3] │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ✓ Baguette Francesa │ Bread │ Yield: 10 units      │
│                                                       │
│  Recipe Ingredients (1 minimum)                      │
│  ────────────────────────────────────────────────    │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │  Ingredient #1                             │ [🗑️]  │
│  │  ──────────────────────────────────────    │     │
│  │  Ingredient *                              │     │
│  │  [▼ Harina de trigo 000______________]     │     │
│  │                                             │     │
│  │  Quantity *        Unit *                  │     │
│  │  [_____] kg   [▼ Kilograms_______]         │     │
│  │                                             │     │
│  │  ☐ Optional ingredient (e.g., optional     │     │
│  │     decoration or variation)               │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [+ Add Another Ingredient]                          │
│                                                       │
│  💡 Tip: Add ingredients in the order you use them   │
│     during production for easier reference.          │
│                                                       │
│  Estimated Cost: Calculating...                      │
│  (Cost per unit will be calculated automatically     │
│   based on ingredient prices)                        │
│                                                       │
│  [← Back]         [Skip to Review] [Add Instructions →]│
└──────────────────────────────────────────────────────┘

After Adding Ingredient:

│  ┌────────────────────────────────────────────┐     │
│  │  ✓ Ingredient #1                           │ [⋮]  │
│  │  ──────────────────────────────────────    │     │
│  │  🌾 Harina de trigo 000                    │     │
│  │  1.5 kg  │  €0.75/kg  │  Cost: €1.13       │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │  Ingredient #2                             │ [🗑️]  │
│  │  [Empty - Click to add]                    │     │
│  └────────────────────────────────────────────┘     │

Create Recipe - Step 3 (Instructions - Optional):

┌──────────────────────────────────────────────────────┐
│  ✕ Create Recipe                       [Step 3 of 3] │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ✓ Baguette Francesa │ 4 ingredients │ €2.45/batch  │
│                                                       │
│  Production Instructions (Optional)                  │
│  ────────────────────────────────────────────────    │
│  Add step-by-step instructions to help your team     │
│  produce this recipe consistently.                   │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │  Step 1: Mixing                            │ [⋮]  │
│  │  [________________________________]         │     │
│  │  Duration: [___] min  │  Temp: [___]°C     │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [+ Add Step]                                        │
│                                                       │
│  💡 You can skip this for now and add instructions   │
│     later. The recipe will still work for costing.   │
│                                                       │
│  ▼ Advanced Options (Optional)                       │
│  ────────────────────────────────────────────────    │
│  ▶ Add process stages, equipment, yield notes        │
│                                                       │
│  [← Back to Ingredients]    [Skip] [Create Recipe →] │
└──────────────────────────────────────────────────────┘

Fields (Complete List):

Step 1 - Recipe Info:

Field	Type	Required	Validation	Help Text
name	text	Yes	Min 2 chars, unique	"The name of this recipe/product"
category	select	Yes	Must select	"Type of baked good"
yield_quantity	number	Yes	>0	"Number of units this recipe makes"
yield_unit	select	No	Default: "units"	"What does this recipe produce?"
prep_time_minutes	number	No	>0	"Preparation time"
description	textarea	No	Max 500 chars	"Notes about this recipe"

Step 2 - Ingredients (List):

Field	Type	Required	Validation	Help Text
ingredient_id	select	Yes	Must exist in inventory	"Select from your inventory"
quantity	number	Yes	>0	"Amount needed for this recipe"
unit	select	Yes	Must match ingredient unit or convertible	"Measurement unit"
is_optional	boolean	No	Default: false	"Optional or decoration ingredient"
ingredient_order	number	Auto	Auto-assigned	"Order in list"

Step 3 - Instructions (Optional):

Field	Type	Required	Validation	Help Text
process_stages	list	No	-	"Mixing, Proofing, Baking, etc."
equipment_needed	list	No	-	"Required equipment"

After Creating Recipes:

┌──────────────────────────────────────────────────────┐
│  📝 Your Recipes (3 created) ✓                       │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 🥖 Baguette Francesa                       │ [⋮]  │
│  │    Bread  │  Yield: 10 units               │     │
│  │    Cost: €2.45/batch (€0.25/unit)          │     │
│  │    Ingredients: 4                          │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 🍞 Pan de Molde                            │ [⋮]  │
│  │    Bread  │  Yield: 2 loaves               │     │
│  │    Cost: €3.20/batch (€1.60/loaf)          │     │
│  │    Ingredients: 7                          │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [+ Create Recipe] [Use Template]                    │
│                                                       │
│  ✅ Awesome! You've created 3 recipes                │
│     Total recipe value: €8.15                        │
│                                                       │
│  [← Back to Inventory]       [Continue to Quality →] │
└──────────────────────────────────────────────────────┘

Validation:

• Minimum: 1 recipe required
• Real-time:
  • Check ingredient availability (must be in inventory from Step 7)
  • Calculate cost as ingredients are added
  • Warn if unit mismatch (e.g., selecting grams when ingredient is in kg)
• Business Rules:
  • Must have ≥1 non-optional ingredient
  • Show warning if recipe uses >50% of current inventory stock

Navigation:

• Continue: Enabled when ≥1 recipe created
• Skip: Allowed with strong warning: "Recipes are essential for production planning. Skip anyway?"

Backend:

• Save recipe via POST /api/v1/recipes/
• For each ingredient: Save via recipe ingredients endpoint
• Mark step recipes-setup as completed
• Store count: {recipes_added: 3, total_cost_value: 8.15}

Smart Features:

• Auto-Cost Calculation: Real-time cost per batch and per unit
• Unit Converter: "Convert quantity" button for different units
• Duplicate Recipe: "Copy and modify" for variations
• Ingredient Substitutions: "Add substitution" for alternative ingredients

---

Step 9: Define Quality Standards (quality-setup)

Purpose: Set up quality checks for production monitoring

User Job: "Define quality standards so my team knows what checks to perform and the system can track quality metrics"

Why This Step:

"Quality checks ensure consistent output and help you identify issues early. Define what 'good' looks like for each stage of production."

What Users Need to Add: Minimum 2 quality checks (recommended 5-8 across stages)

Form Type: Wizard-Enhanced List with Stage Selection

UI Flow:

┌──────────────────────────────────────────────────────┐
│  Step 5 of 7: Define Quality Standards               │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ✅ Quality Checks                                    │
│  Standards for consistent production                 │
│                                                       │
│  [===================================>] 86% Complete │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  Why This Matters                            │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Quality tracking helps you:                 │   │
│  │  • Maintain consistent product standards     │   │
│  │  • Train new team members                    │   │
│  │  • Identify production issues early          │   │
│  │  • Track quality metrics over time           │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  📝 Quality Checks (2 min required, 5 ideal) │   │
│  │                                               │   │
│  │  [+ Add Quality Check] [Use Template Set]    │   │
│  │                                               │   │
│  │  (Empty state)                                │   │
│  │  "Define checks for key production stages"   │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  💡 Quick Start: Use our template set of common      │
│     quality checks for bakeries. Customize after.    │
│                                                       │
│  [← Back to Recipes]              [Skip] [Continue →]│
│  (disabled until 2 checks added)                     │
└──────────────────────────────────────────────────────┘

Quality Template Set:

┌──────────────────────────────────────────────────────┐
│  ✕ Add Quality Check Template Set                    │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  We'll add common quality checks for each production │
│  stage. You can edit or remove any check.            │
│                                                       │
│  Mixing Stage:                                       │
│  ☑️ Dough temperature (18-24°C)                      │
│  ☑️ Dough consistency (smooth, elastic)              │
│                                                       │
│  Proofing Stage:                                     │
│  ☑️ Dough volume (doubled in size)                   │
│  ☑️ Proofing time (60-90 min)                        │
│                                                       │
│  Baking Stage:                                       │
│  ☑️ Internal temperature (95-98°C for bread)         │
│  ☑️ Crust color (golden brown)                       │
│                                                       │
│  Cooling Stage:                                      │
│  ☑️ Cooling time (30-45 min before packaging)        │
│                                                       │
│  Final Product:                                      │
│  ☑️ Weight (within 5% of target)                     │
│  ☑️ Visual inspection (no defects)                   │
│                                                       │
│  [Deselect All] [Cancel]      [Add Selected (9) →]   │
└──────────────────────────────────────────────────────┘

Manual Add Quality Check:

┌──────────────────────────────────────────────────────┐
│  ✕ Add Quality Check                                 │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  Check Information                                   │
│  ────────────────────────────────────────────────    │
│  Check Name *                                        │
│  [_____________________________________________]      │
│   e.g., "Dough temperature", "Crust color"            │
│                                                       │
│  Description                                         │
│  [_____________________________________________]      │
│   What to check and why                              │
│                                                       │
│  Production Stage *                                  │
│  [☑️ Mixing] [☑️ Proofing] [☑️ Baking] [☑️ Cooling]  │
│   (Select all stages where this check applies)       │
│                                                       │
│  Check Type *                                        │
│  [▼ Select type_______________________]              │
│      ├─ Visual Inspection                            │
│      ├─ Temperature Measurement                      │
│      ├─ Weight Measurement                           │
│      ├─ Time Tracking                                │
│      ├─ Yes/No Check                                 │
│      └─ Numeric Range                                │
│                                                       │
│  ▼ Pass Criteria (appears based on check type)      │
│  ────────────────────────────────────────────────    │
│  [For Temperature: Min/Max range fields]             │
│  [For Visual: Description of acceptable appearance]  │
│  [For Weight: Target weight ± tolerance]             │
│                                                       │
│  Priority                                            │
│  ( ) Critical  ( ) Important  (•) Standard           │
│                                                       │
│  [Cancel]             [Add Another] [Save & Done →]  │
└──────────────────────────────────────────────────────┘

Fields:

Field	Type	Required	Validation	Help Text
name	text	Yes	Min 3 chars	"Short name for this check"
description	textarea	No	Max 500 chars	"What to check and why it matters"
production_stages	multi-select	Yes	≥1 stage	"When to perform this check"
check_type	select	Yes	Must select	"How to measure this quality aspect"
pass_criteria	varies	Conditional	Depends on type	"What defines a pass"
priority	select	No	Default: Standard	"Critical, Important, or Standard"

After Adding Quality Checks:

┌──────────────────────────────────────────────────────┐
│  📝 Your Quality Checks (7 added) ✓                  │
│                                                       │
│  Group by: [Stage ▼]                                 │
│                                                       │
│  🔧 Mixing (2 checks)                                │
│  ┌────────────────────────────────────────────┐     │
│  │ 🌡️ Dough Temperature                        │ [⋮]  │
│  │    Range: 18-24°C  │  Priority: Critical    │     │
│  └────────────────────────────────────────────┘     │
│  ┌────────────────────────────────────────────┐     │
│  │ ✋ Dough Consistency                        │ [⋮]  │
│  │    Visual check  │  Priority: Important     │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  🍞 Baking (3 checks)                                │
│  [... more checks ...]                               │
│                                                       │
│  [+ Add Check] [Use Template]                        │
│                                                       │
│  ✅ Great! You've defined 7 quality standards        │
│                                                       │
│  [← Back to Recipes]            [Continue to Team →] │
└──────────────────────────────────────────────────────┘

Validation:

• Minimum: 2 checks required
• Business Rules:
  • Recommend at least one "Critical" check
  • Warn if no checks for "Baking" stage (common oversight)

Navigation:

• Continue: Enabled when ≥2 checks added
• Skip: Allowed (quality is important but not blocking for basic operations)

Backend:

• Save via POST /api/v1/quality-templates/
• Mark step quality-setup as completed
• Store count: {quality_checks_added: 7, critical_checks: 2}

---

PHASE 4: TEAM & FINALIZATION (Optional but Recommended)

Step 10: Add Team Members (team-setup)

Purpose: Set up user accounts for bakery staff

User Job: "Add my team so they can access the system and we can coordinate work"

Why This Step:

"Adding team members allows you to assign tasks, track who does what, and give everyone the tools they need to work efficiently."

What Users Need to Add: Optional (0-10 team members)

Form Type: Simple List Entry (Invite-Based)

UI Flow:

┌──────────────────────────────────────────────────────┐
│  Step 6 of 7: Add Team Members (Optional)            │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  👥 Team                                              │
│  Your bakery staff                                   │
│                                                       │
│  [========================================] 93% Complete│
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  Why This Matters                            │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Team access enables:                        │   │
│  │  • Task assignment & coordination            │   │
│  │  • Production tracking by person             │   │
│  │  • Quality check accountability              │   │
│  │  • Permission-based access control           │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  📝 Team Members (Optional)                  │   │
│  │                                               │   │
│  │  [+ Invite Team Member]                      │   │
│  │                                               │   │
│  │  (Empty state)                                │   │
│  │  "Invite your staff to collaborate"          │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  💡 You can add team members later from Settings.    │
│     Skip this step if you're the only user for now.  │
│                                                       │
│  [← Back to Quality]      [Skip This Step] [Continue →]│
│  (always enabled - this step is optional)            │
└──────────────────────────────────────────────────────┘

Invite Team Member Modal:

┌──────────────────────────────────────────────────────┐
│  ✕ Invite Team Member                                │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  Member Information                                  │
│  ────────────────────────────────────────────────    │
│  Name *                                              │
│  [_____________________________________________]      │
│                                                       │
│  Email *                                             │
│  [_____________________________________________]      │
│   They'll receive an invitation to join             │
│                                                       │
│  Role *                                              │
│  [▼ Select role_______________________]              │
│      ├─ Baker (can view & record production)         │
│      ├─ Manager (can edit recipes & inventory)       │
│      └─ Admin (full access)                          │
│                                                       │
│  [Cancel]              [Send Invitation →]           │
└──────────────────────────────────────────────────────┘

After Adding Team:

│  📝 Team Members (3 invited) ✓                       │
│                                                       │
│  ┌────────────────────────────────────────────┐     │
│  │ 👤 María García                            │ [⋮]  │
│  │    maria@bakery.com  │  Role: Manager      │     │
│  │    Status: Invitation sent                 │     │
│  └────────────────────────────────────────────┘     │
│                                                       │
│  [... more team members ...]                         │

Validation: None (optional step)

Navigation:

• Continue: Always enabled
• Skip: Always allowed

Backend:

• Send invitation via POST /api/v1/team/invitations/
• Mark step team-setup as completed
• Store count: {team_invitations_sent: 3}

---

Step 11: Review & Launch (setup-completion)

Purpose: Celebrate completion and show what's now possible

User Job: "Verify I've set everything up correctly and start using the system"

Why This Step:

"You're ready to go! Let's review what you've set up and show you what's now available."

UI Flow:

┌──────────────────────────────────────────────────────┐
│  Step 7 of 7: You're All Set! 🎉                     │
│  ════════════════════════════════════════════════════ │
│                                                       │
│  ✅ Setup Complete                                    │
│  Your bakery system is ready                         │
│                                                       │
│  [=========================================>] 100%    │
│                                                       │
│  ┌──────────────────────────────────────────────┐   │
│  │  🎊 Congratulations!                         │   │
│  │  ─────────────────────────────────────────── │   │
│  │  Your bakery management system is fully      │   │
│  │  configured and ready to help you run your   │   │
│  │  operations more efficiently.                │   │
│  └──────────────────────────────────────────────┘   │
│                                                       │
│  📊 Setup Summary                                    │
│  ────────────────────────────────────────────────    │
│  ✅ 2 Suppliers added                                │
│  ✅ 12 Inventory items set up                        │
│  ✅ 3 Recipes created (Total value: €8.15)           │
│  ✅ 7 Quality checks defined                         │
│  ✅ 3 Team members invited                           │
│                                                       │
│  🎯 What You Can Do Now                              │
│  ────────────────────────────────────────────────    │
│  ┌──────────────────────────────────────────┐       │
│  │ 📦 Track Inventory                       │ [→]   │
│  │    Real-time stock levels & alerts       │       │
│  └──────────────────────────────────────────┘       │
│  ┌──────────────────────────────────────────┐       │
│  │ 👨‍🍳 Create Production Orders              │ [→]   │
│  │    Plan daily baking with your recipes   │       │
│  └──────────────────────────────────────────┘       │
│  ┌──────────────────────────────────────────┐       │
│  │ 💰 Analyze Costs & Profitability         │ [→]   │
│  │    See exact costs per recipe            │       │
│  └──────────────────────────────────────────┘       │
│  ┌──────────────────────────────────────────┐       │
│  │ 📈 View AI Forecasts                     │ [→]   │
│  │    Demand predictions for your products  │       │
│  └──────────────────────────────────────────┘       │
│                                                       │
│  💡 Quick Start Guide                                │
│  ────────────────────────────────────────────────    │
│  [📘 View Tutorial] [❓ Watch Demo Video]            │
│                                                       │
│  [← Back to Team]            [Go to Dashboard →]     │
└──────────────────────────────────────────────────────┘

Validation: None (review step)

Navigation:

• Continue: Go to dashboard (system fully operational)

Backend:

• Mark step setup-completion as completed
• Set overall onboarding status to "completed"
• Trigger: Send welcome email with quick start guide

---

Progress Tracking & Navigation

Overall Progress Indicator

Visual Design (appears at top of every step):

[====================>----------] 57% Complete
Step 3 of 7: Set Up Inventory Items

Progress Calculation:

// Weight steps by estimated complexity/time
const STEP_WEIGHTS = {
  'setup-welcome': 5,        // 2 min (light)
  'suppliers-setup': 10,     // 5 min (moderate)
  'inventory-items-setup': 20, // 10 min (heavy)
  'recipes-setup': 20,       // 10 min (heavy)
  'quality-setup': 15,       // 7 min (moderate)
  'team-setup': 10,          // 5 min (optional)
  'setup-completion': 5      // 2 min (light)
};

const totalWeight = Object.values(STEP_WEIGHTS).reduce((a, b) => a + b);

function calculateProgress(currentStepIndex: number, completedSteps: string[]): number {
  let completedWeight = 0;

  // Add weight of fully completed steps
  completedSteps.forEach(stepId => {
    completedWeight += STEP_WEIGHTS[stepId] || 0;
  });

  // Add 50% of current step weight (user is midway through)
  const currentStepId = STEPS[currentStepIndex].id;
  completedWeight += (STEP_WEIGHTS[currentStepId] || 0) * 0.5;

  return Math.round((completedWeight / totalWeight) * 100);
}

Step Navigation States

Continue Button States:

Step	Enable Condition	Button Text	Behavior
Welcome	Always	"Let's Get Started →"	Navigate to Step 6
Suppliers	≥1 supplier added	"Continue to Inventory →"	Navigate to Step 7
Inventory	≥3 items added	"Continue to Recipes →"	Navigate to Step 8
Recipes	≥1 recipe created	"Continue to Quality →"	Navigate to Step 9
Quality	≥2 checks added	"Continue to Team →"	Navigate to Step 10
Team	Always (optional)	"Continue to Review →"	Navigate to Step 11
Completion	Always	"Go to Dashboard →"	Exit wizard → Dashboard

Back Button Behavior:

• Always visible (except on Step 5)
• Goes to previous step WITHOUT losing data (data is saved on each step completion)
• Disabled during save operations

Skip Button:

• Visible on Steps 5, 9, 10, 11 (optional/skippable steps)
• Shows confirmation dialog: "Are you sure you want to skip [Step Name]? You can set this up later from Settings."
• On confirm: Marks step as "skipped" (not "completed") and advances

Mobile Navigation Patterns

Small Screens (<640px):

• Progress bar: Full width, height: 8px
• Step title: Larger font (18px)
• Buttons: Stacked vertically
• Step indicators: Horizontal scroll

[========>------] 43%

📦 Inventory Items
Step 3 of 7

[Main content...]

[← Back       ]
[Skip This Step]
[Continue →    ]

Desktop (≥640px):

• Progress bar: Full width, height: 12px
• Buttons: Horizontal layout
• Step indicators: All visible

Save Progress & Resume Later

Auto-Save Behavior:

• Each entity added is immediately saved to backend
• Step is marked "completed" when user clicks Continue
• If user closes browser mid-step, data is preserved but step not marked complete

Resume Behavior:

function determineResumeStep(userProgress: UserProgress): number {
  // Find first incomplete step
  for (let i = 0; i < SETUP_STEPS.length; i++) {
    const step = SETUP_STEPS[i];
    const stepProgress = userProgress.steps.find(s => s.step_name === step.id);

    if (!stepProgress?.completed && stepProgress?.status !== 'skipped') {
      return i; // Resume here
    }
  }

  // All steps complete → go to last step (completion)
  return SETUP_STEPS.length - 1;
}

Resume Entry Point:

• Dashboard shows "Complete Setup" banner if wizard not finished
• Banner shows: "You're 57% done! Continue setting up →"
• Click banner → Resume at first incomplete step

Exit Points & Persistence

User Can Exit At Any Time:

1. Click browser back button
2. Click dashboard link in sidebar
3. Close browser tab

On Exit (Not Completed):

• All data entered so far is saved
• Progress tracked in backend (user_progress table)
• Dashboard shows persistent banner: "Complete your setup to unlock all features"

Re-Entry:

• User clicks "Complete Setup" from dashboard
• System loads user progress and resumes at correct step
• Previously entered data is loaded (suppliers, inventory, recipes, etc.)

---

Validation & Error Handling

Real-Time Validation Strategy

Field-Level Validation:

• Trigger: onChange (debounced 300ms for text inputs)
• Display: Inline error message below field
• State: Field border turns red, error icon appears

Example:

// Supplier name field
const [nameError, setNameError] = useState<string | null>(null);

const validateName = debounce((value: string) => {
  if (value.length < 2) {
    setNameError("Supplier name must be at least 2 characters");
    return false;
  }

  // Check for duplicates (async)
  checkDuplicateSupplier(value).then(isDuplicate => {
    if (isDuplicate) {
      setNameError("A supplier with this name already exists");
    } else {
      setNameError(null);
    }
  });

  return true;
}, 300);

Cross-Field Validation:

• Trigger: When dependent field changes
• Example: reorder_point must be ≤ low_stock_threshold

function validateInventoryItem(item: InventoryItemForm): ValidationErrors {
  const errors: ValidationErrors = {};

  if (item.reorder_point && item.low_stock_threshold) {
    if (item.reorder_point > item.low_stock_threshold) {
      errors.reorder_point = "Reorder point must be less than or equal to low stock threshold";
    }
  }

  return errors;
}

Step-Level Validation:

• Trigger: When user clicks "Continue"
• Validates all requirements for current step
• If validation fails: Show error summary, scroll to first error

Error Message Patterns

Tone: Helpful, not judgmental

Error Type	Bad Message	Good Message
Required field	"This field is required"	"Please enter a supplier name to continue"
Format error	"Invalid email"	"Please enter a valid email address (e.g., name@bakery.com)"
Duplicate	"Duplicate entry"	"You already have a supplier named 'Molinos'. Try a different name."
Dependency	"Dependency not met"	"Please add at least 3 inventory items before creating recipes"

Visual Pattern:

┌────────────────────────────────────────┐
│  ⚠️ Please fix these issues:           │
│  ────────────────────────────────────  │
│  • Supplier name is required           │
│  • Email format is invalid             │
│                                        │
│  [Fix Issues]                          │
└────────────────────────────────────────┘

Preventing Invalid States

Dependency Enforcement:

1. Suppliers before Inventory: Can't assign supplier to inventory item if no suppliers exist

   • Solution: Show "Add supplier" link inline in inventory form

2. Inventory before Recipes: Can't select ingredients if no inventory items exist

   • Solution: Wizard step order enforces this naturally

3. No Empty Steps: Can't mark step complete if minimum requirements not met

   • Solution: Disable "Continue" button until requirements met

Business Rule Validation:

// Inventory item validation
function validateInventorySetup(items: InventoryItem[]): ValidationWarning[] {
  const warnings: ValidationWarning[] = [];

  // Warn if no flour (common for bakeries)
  const hasFlour = items.some(item =>
    item.category === 'flour_grains' ||
    item.name.toLowerCase().includes('flour')
  );

  if (!hasFlour) {
    warnings.push({
      severity: 'warning',
      message: "Most bakeries use flour. Did you mean to skip it?",
      action: "Add flour items",
      onAction: () => openAddItemModal({ category: 'flour_grains' })
    });
  }

  return warnings;
}

Error Recovery Strategies

Network Errors:

• Retry failed requests automatically (max 3 attempts)
• Show toast: "Connection lost. Retrying..."
• If all retries fail: Show error with "Try Again" button

Validation Errors:

• Highlight all invalid fields
• Show summary of errors at top of form
• Scroll to first error
• Provide "Fix for me" suggestions where possible

Example Recovery UI:

┌────────────────────────────────────────┐
│  ❌ Couldn't save supplier             │
│                                        │
│  Network connection lost. Your data   │
│  is safe - we'll try again.           │
│                                        │
│  [Try Again] [Continue Offline]       │
└────────────────────────────────────────┘

---

Smart Features

1. Intelligent Templates

Starter Template for Inventory:

• Pre-populated with 25 common bakery ingredients
• Categorized (Flour & Grains, Dairy, Sweeteners, etc.)
• Suggested units and typical low stock thresholds
• User can select which to import

Recipe Templates:

• Library of 15+ common recipes (baguette, white bread, croissant, muffins, etc.)
• User selects template → System maps template ingredients to user's inventory
• If ingredient missing: Prompt to add it or substitute

Quality Check Templates:

• Pre-configured checks for each production stage
• Based on industry best practices
• User can enable/disable individual checks

2. Auto-Suggestions & Smart Defaults

Category Auto-Detection (ML-powered):

function suggestCategory(itemName: string): string {
  // ML model trained on bakery inventory data
  const prediction = categoryModel.predict(itemName);

  // Examples:
  // "harina" → "flour_grains"
  // "azúcar" → "sweeteners"
  // "leche" → "dairy_eggs"

  return prediction.category;
}

Supplier Recommendations:

• When adding inventory item, suggest supplier based on item category
• "Flour items usually come from: [Molinos del Norte ▼]"

Unit Conversion Helper:

Adding: Harina de trigo (1000g)
💡 Tip: 1000g = 1kg. Switch to kilograms? [Yes] [No]

Cost Estimation:

• If user doesn't know ingredient cost, suggest typical market price
• "Average cost for flour in Spain: €0.60-0.80/kg"

3. Bulk Import & Export

CSV/Excel Import:

• Upload spreadsheet → Map columns → Import in bulk
• Template downloadable: "Download sample spreadsheet"
• Validation before import: "Found 12 items, 2 have errors. Fix them?"

Supported Entities:

• Suppliers (name, type, contact, email, phone)
• Inventory Items (name, category, unit, supplier, cost, stock levels)
• Recipes (name, category, yield + separate ingredient list)

4. Contextual Help System

Help Tooltips:

• (?) icon next to complex fields
• Hover/click to see explanation

Low Stock Threshold (?)
────────────────────────
When inventory falls below this level,
you'll receive an alert to reorder.

Recommended: 2-3 weeks of typical usage

Example: If you use 50kg flour per week,
set threshold to 100-150kg

Video Tutorials:

• Embedded 30-60 second videos for complex steps
• "Watch how to create a recipe (45 sec)"

Inline Examples:

• Every field shows example value
• "e.g., Molinos del Norte" for supplier name
• "e.g., 1.5" for recipe ingredient quantity

5. Progress Celebrations & Motivation

Milestone Animations:

• When reaching 25%, 50%, 75% completion: Brief confetti animation
• "Great progress! You're halfway there! 🎉"

Step Completion Feedback:

• After each step: Success message with positive reinforcement
• "✅ Excellent! You've added 3 recipes. Your bakery is taking shape!"

Comparison to Others (Optional):

• "Most bakeries add 10-15 inventory items. You've added 12 - right on track!"

6. Intelligent Validation Warnings (Non-Blocking)

Soft Warnings (shown but don't prevent progress):

⚠️ Heads up!
You haven't set a cost for "Harina de trigo".
Recipe costing won't be accurate until you add it.

[Add Cost Now] [I'll Do It Later]

Proactive Suggestions:

💡 Suggestion
You've added "Baguette" recipe. Want to add a
"Whole Wheat Baguette" variation? We can copy
the recipe and you just adjust the flour.

[Create Variation] [No Thanks]

---

Technical Implementation Notes

Component Architecture

Proposed Structure:

frontend/src/components/domain/setup-wizard/
├── SetupWizard.tsx                    # Main wizard component (similar to OnboardingWizard)
├── steps/
│   ├── WelcomeStep.tsx
│   ├── SuppliersSetupStep.tsx
│   ├── InventorySetupStep.tsx
│   ├── RecipesSetupStep.tsx
│   ├── QualitySetupStep.tsx
│   ├── TeamSetupStep.tsx
│   └── CompletionStep.tsx
├── components/
│   ├── StepProgress.tsx               # Progress bar & indicators
│   ├── StepNavigation.tsx             # Back/Skip/Continue buttons
│   ├── AddEntityModal.tsx             # Generic modal for adding items
│   ├── TemplateSelector.tsx           # Template gallery
│   └── EntityList.tsx                 # List view for added items
└── hooks/
    ├── useSetupProgress.ts
    ├── useStepValidation.ts
    └── useAutoSave.ts

Reusing Existing Patterns

From OnboardingWizard:

• Step configuration structure (StepConfig interface)
• Progress tracking (useUserProgress hook)
• Step completion (useMarkStepCompleted mutation)
• Step navigation logic
• Mobile/desktop responsive design
• Progress percentage calculation

From AddModal:

• Field configuration (AddModalField interface)
• Section-based organization
• ListFieldRenderer for managing collections
• Validation infrastructure
• Loading states & success animations

Integration Strategy:

// Extend existing StepConfig to support setup wizard steps
interface SetupStepConfig extends StepConfig {
  id: string;
  title: string;
  description: string;
  component: React.ComponentType<SetupStepProps>;
  minRequired?: number;           // Minimum items to proceed
  isOptional?: boolean;           // Can be skipped
  estimatedMinutes?: number;      // For progress calculation
  dependencies?: string[];        // Step IDs that must be complete first
}

Backend API Requirements

New Endpoints Needed:

// Setup-specific progress tracking
GET  /api/v1/onboarding/progress/:userId?type=setup
POST /api/v1/onboarding/steps/:stepName/complete

// Bulk operations
POST /api/v1/inventory/ingredients/bulk           // Bulk create from template
POST /api/v1/quality-templates/bulk               // Bulk create checks
POST /api/v1/inventory/ingredients/import         // CSV import

// Templates
GET  /api/v1/templates/inventory-starter          // Get starter inventory
GET  /api/v1/templates/recipes/:category          // Get recipe templates
GET  /api/v1/templates/quality-checks             // Get quality check templates

// Smart suggestions
POST /api/v1/ml/suggest-category                  // ML category suggestion
GET  /api/v1/market-data/average-prices           // Average ingredient prices

Existing Endpoints to Use:

// Already available
POST /api/v1/suppliers/
POST /api/v1/inventory/ingredients/
POST /api/v1/recipes/
POST /api/v1/quality-templates/
POST /api/v1/team/invitations/

State Management

Setup Wizard State:

interface SetupWizardState {
  currentStepIndex: number;
  completedSteps: string[];
  skippedSteps: string[];
  stepData: {
    [stepId: string]: {
      itemsAdded: number;
      totalValue?: number;
      completedAt?: string;
      // Step-specific data
    };
  };
  isInitialized: boolean;
  progressPercentage: number;
}

Persisted State (in backend):

-- user_progress table (already exists)
user_id: UUID
current_step: VARCHAR  -- e.g., "inventory-items-setup"
completion_percentage: INTEGER
steps: JSONB           -- Array of step progress objects
completed_at: TIMESTAMP (nullable)

-- step progress object structure
{
  "step_name": "suppliers-setup",
  "completed": true,
  "skipped": false,
  "completed_at": "2025-11-06T10:30:00Z",
  "data": {
    "suppliers_added": 2,
    "used_template": false
  }
}

Performance Considerations

Lazy Loading:

• Load step components on-demand (React.lazy)
• Preload next step component in background

Optimistic Updates:

• Show success immediately, sync in background
• If sync fails, rollback with notification

Caching:

• Cache supplier/inventory lists in React Query
• Invalidate on mutations

Debouncing:

• Search/filter operations: 300ms debounce
• Validation: 300ms debounce for text inputs
• Auto-save draft: 1000ms debounce

Accessibility (a11y)

Keyboard Navigation:

• Tab order: Top to bottom, left to right
• Enter: Submit form/Continue
• Esc: Close modal
• Arrow keys: Navigate step indicators

Screen Reader Support:

<div role="progressbar" aria-valuenow={57} aria-valuemin={0} aria-valuemax={100}>
  Step 3 of 7: Set Up Inventory Items (57% complete)
</div>

<button
  aria-label="Continue to Recipes step"
  disabled={!canContinue}
  aria-disabled={!canContinue}
>
  Continue →
</button>

Focus Management:

• When step changes: Focus on step title
• When modal opens: Focus on first input
• When error: Focus on first invalid field

Internationalization (i18n)

Translation Keys:

{
  "setup_wizard": {
    "steps": {
      "welcome": {
        "title": "Welcome & Setup Overview",
        "description": "Let's set up your bakery operations",
        ...
      },
      "suppliers": {
        "title": "Add Suppliers",
        "description": "Your ingredient and material providers",
        "min_required": "Add at least {{count}} supplier to continue",
        ...
      }
    },
    "navigation": {
      "back": "Back",
      "skip": "Skip This Step",
      "continue": "Continue",
      ...
    }
  }
}

---

Success Metrics

Leading Indicators (During Wizard)

Completion Rate:

• Metric: % of users who complete all 7 steps
• Target: ≥80% completion rate
• Measurement: (users_completed / users_started) * 100

Drop-Off Points:

• Metric: Where users abandon the wizard
• Target: No single step has >15% drop-off
• Measurement: Track step entry vs. step completion

Time to Complete:

• Metric: Average time from Step 5 to Step 11
• Target: 15-25 minutes (matches estimate)
• Measurement: completion_timestamp - start_timestamp

Data Quality Score:

• Metric: % of records with complete, valid data
• Target: ≥90% of entities have all required + recommended fields
• Calculation:

function calculateDataQuality(entity: any): number {
  const requiredFields = entity.requiredFields.filter(f => !!entity[f]);
  const optionalFields = entity.optionalFields.filter(f => !!entity[f]);

  return (requiredFields.length + (optionalFields.length * 0.5)) /
         (entity.requiredFields.length + entity.optionalFields.length);
}

Template Usage Rate:

• Metric: % of users who use starter templates
• Target: ≥60% use at least one template
• Hypothesis: Templates speed up setup and improve data quality

Lagging Indicators (Post-Wizard)

Feature Adoption Rate:

• Metric: % of completed users actively using core features within 7 days
• Features: Inventory tracking, recipe costing, production planning, quality checks
• Target: ≥70% use ≥2 features weekly

System Reliance:

• Metric: Daily active usage frequency
• Target: ≥5 days per week for production-focused users
• Measurement: DAU/MAU ratio

User Satisfaction (NPS):

• Metric: Net Promoter Score for setup experience
• Survey: "How likely are you to recommend this setup process?" (0-10)
• Target: NPS ≥40

Time to First Value:

• Metric: Days from registration to first meaningful action (e.g., create production order, record sale)
• Target: ≤3 days (with wizard) vs. 7-10 days (without)

Support Ticket Reduction:

• Metric: "How do I..." support tickets related to setup
• Target: 50% reduction vs. previous un-guided experience

Business Impact (Long-term)

Operational Efficiency:

• Metric: Waste reduction (% decrease in spoilage/overstock)
• Target: 15-20% reduction in first 3 months
• Attribution: Users with complete setup vs. incomplete

Cost Visibility:

• Metric: % of users who can accurately report per-recipe costs
• Target: 100% of users with recipes can see cost breakdowns
• Value: Enables pricing decisions, profitability analysis

Quality Consistency:

• Metric: Quality check compliance rate
• Target: ≥80% of production runs have quality checks recorded
• Attribution: Users who defined quality standards in wizard

A/B Testing Opportunities

Test Variations:

1. Template vs. Manual Entry

   • A: Show templates prominently (current design)
   • B: Manual entry default, templates as optional
   • Hypothesis: Templates increase completion rate & speed

2. Step Granularity

   • A: 7 steps (current design)
   • B: 4 steps (combine some steps)
   • Hypothesis: Fewer steps reduce cognitive load, increase completion

3. Progress Celebration

   • A: Milestone animations + messages (current design)
   • B: No celebrations, just progress bar
   • Hypothesis: Celebrations increase motivation & completion

4. Skip vs. No-Skip for Optional Steps

   • A: Allow skipping Team & Quality steps
   • B: Encourage completion ("3 more minutes to 100%")
   • Hypothesis: Encouraging completion increases feature adoption

Tracking Implementation

Analytics Events:

// Track key events
analytics.track('setup_wizard_started', {
  user_id, timestamp
});

analytics.track('setup_step_completed', {
  user_id, step_id, items_added, duration_seconds, used_template
});

analytics.track('setup_step_skipped', {
  user_id, step_id, reason
});

analytics.track('setup_wizard_completed', {
  user_id, total_duration, suppliers_count, inventory_count, recipes_count,
  quality_checks_count, team_count, used_templates_count
});

analytics.track('setup_wizard_abandoned', {
  user_id, last_step_id, completion_percentage, duration
});

Dashboard Metrics:

Setup Wizard Performance
─────────────────────────
Completion Rate:      82% ✓ (target: 80%)
Avg. Time:            18 min ✓ (target: 15-25 min)
Drop-off Points:      Step 7 (Inventory): 12% ✓

Data Quality Score:   91% ✓ (target: 90%)

Template Usage:       68% ✓ (target: 60%)
  - Inventory starter: 55%
  - Recipe templates:  42%
  - Quality checks:    71%

Feature Adoption (7 days post-setup):
  - Inventory tracking:   78%
  - Recipe costing:       65%
  - Production planning:  52%
  - Quality monitoring:   48%

---

Implementation Roadmap

Phase 1: Foundation (Week 1-2)

• Create SetupWizard component structure
• Implement step navigation & progress tracking
• Integrate with existing OnboardingWizard
• Build StepProgress and StepNavigation components
• Set up backend endpoints for step completion

Phase 2: Core Steps (Week 3-5)

• Implement Welcome Step (Step 5)
• Implement Suppliers Setup Step (Step 6)
• Implement Inventory Setup Step (Step 7)
• Implement Recipes Setup Step (Step 8)
• Add real-time validation for each step

Phase 3: Advanced Features (Week 6-7)

• Implement Quality Setup Step (Step 9)
• Implement Team Setup Step (Step 10)
• Implement Completion Step (Step 11)
• Add template systems (inventory, recipes, quality)
• Implement bulk import functionality

Phase 4: Polish & Smart Features (Week 8)

• Add contextual help & tooltips
• Implement auto-suggestions (ML category detection)
• Add celebration animations & milestone feedback
• Optimize performance (lazy loading, caching)
• Complete i18n translations

Phase 5: Testing & Iteration (Week 9-10)

• User testing with 10-15 bakery owners
• Fix issues identified in testing
• A/B test setup (template vs. manual entry)
• Set up analytics tracking
• Write documentation & tutorial content

Phase 6: Launch & Monitor (Week 11+)

• Soft launch to 10% of new users
• Monitor metrics & gather feedback
• Iterate based on data
• Full rollout to all users
• Ongoing optimization

---

Appendix: Open Questions & Decisions Needed

Design Decisions

1. Should we allow users to edit data from previous steps within the wizard?

   • Option A: Yes, "Edit" button on each step summary
   • Option B: No, must exit wizard and use normal UI
   • Recommendation: Option A (better UX, keeps users in flow)

2. How do we handle users who want to skip the entire wizard?

   • Option A: Allow full skip, but show persistent "Incomplete Setup" banner
   • Option B: Require minimum critical path (Steps 6-8)
   • Recommendation: Option B (ensures system can function)

3. Should recipe templates include quantities, or just ingredient lists?

   • Option A: Full recipes with quantities (more helpful, but may not match user's scale)
   • Option B: Just ingredient lists (user fills in quantities)
   • Recommendation: Option A with prominent "Adjust quantities to your batch size" notice

4. What happens if a user creates an entity outside the wizard (e.g., manually adds a supplier)?

   • Option A: Wizard counts it toward requirements
   • Option B: Wizard doesn't recognize it, asks user to add via wizard
   • Recommendation: Option A (recognize all entities, wizard is just guided experience)

Technical Questions

1. Should we reuse existing modal components or create wizard-specific ones?

   • Recommendation: Reuse AddModal architecture, extend with wizard-specific features

2. How do we handle wizard state if user switches tenants mid-wizard?

   • Recommendation: Save progress per tenant, allow resuming

3. Should wizard data be saved in a separate table or use main entity tables?

   • Recommendation: Use main entity tables (suppliers, inventory, etc.) + track progress in user_progress

4. How do we handle concurrent edits (user opens wizard, also opens suppliers page)?

   • Recommendation: Real-time sync via websockets or periodic polling

Content & Messaging

1. Tone: Professional vs. Friendly?

   • Recommendation: Friendly but professional ("Let's set up..." not "Time to configure your database!")

2. Spanish vs. English default?

   • Recommendation: Detect from user's browser locale, allow language switch

3. Should we use bakery-specific terminology throughout?

   • Recommendation: Yes (e.g., "recipes" not "production formulas", "ingredients" not "inventory items")

---

Document Status

Version: 1.0 (Initial Draft) Date: 2025-11-06 Status: Ready for Review Next Steps:

1. Review with product team
2. Validate design with UX team
3. Review technical feasibility with engineering
4. Conduct user interviews to validate JTBD assumptions
5. Create detailed wireframes/mockups
6. Begin Phase 1 implementation

Related Documents:

• jtbd-analysis-inventory-setup.md - Jobs To Be Done analysis
• OnboardingWizard.tsx - Existing onboarding implementation
• AddModal.tsx - Existing modal component architecture

Reviewers:

• Product Manager
• UX Designer
• Tech Lead
• Backend Engineer
• QA Lead

Approval: Pending

---

End of Specification