103 KiB
103 KiB
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
- Executive Summary
- Design Principles
- Wizard Architecture
- Complete Step Sequence
- Step Specifications (Detailed)
- Progress Tracking & Navigation
- Validation & Error Handling
- Smart Features
- Technical Implementation Notes
- 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
- Continuous Journey: Extends onboarding wizard (Step 5+) instead of separate flow
- Dependency Awareness: Enforces order (suppliers before inventory before recipes)
- Progressive Disclosure: Shows complex options only when needed
- Flexible Pacing: Save progress, skip optional steps, resume later
- Contextual Guidance: Every step explains why it matters and what comes next
- 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 |
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-setupas 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-setupas 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-setupas 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-setupas 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-setupas 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-completionas 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:
- Click browser back button
- Click dashboard link in sidebar
- Close browser tab
On Exit (Not Completed):
- All data entered so far is saved
- Progress tracked in backend (
user_progresstable) - 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_pointmust 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:
-
Suppliers before Inventory: Can't assign supplier to inventory item if no suppliers exist
- Solution: Show "Add supplier" link inline in inventory form
-
Inventory before Recipes: Can't select ingredients if no inventory items exist
- Solution: Wizard step order enforces this naturally
-
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 (
StepConfiginterface) - Progress tracking (
useUserProgresshook) - Step completion (
useMarkStepCompletedmutation) - Step navigation logic
- Mobile/desktop responsive design
- Progress percentage calculation
From AddModal:
- Field configuration (
AddModalFieldinterface) - 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:
-
Template vs. Manual Entry
- A: Show templates prominently (current design)
- B: Manual entry default, templates as optional
- Hypothesis: Templates increase completion rate & speed
-
Step Granularity
- A: 7 steps (current design)
- B: 4 steps (combine some steps)
- Hypothesis: Fewer steps reduce cognitive load, increase completion
-
Progress Celebration
- A: Milestone animations + messages (current design)
- B: No celebrations, just progress bar
- Hypothesis: Celebrations increase motivation & completion
-
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
-
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)
-
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)
-
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
-
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
-
Should we reuse existing modal components or create wizard-specific ones?
- Recommendation: Reuse AddModal architecture, extend with wizard-specific features
-
How do we handle wizard state if user switches tenants mid-wizard?
- Recommendation: Save progress per tenant, allow resuming
-
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
-
How do we handle concurrent edits (user opens wizard, also opens suppliers page)?
- Recommendation: Real-time sync via websockets or periodic polling
Content & Messaging
-
Tone: Professional vs. Friendly?
- Recommendation: Friendly but professional ("Let's set up..." not "Time to configure your database!")
-
Spanish vs. English default?
- Recommendation: Detect from user's browser locale, allow language switch
-
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:
- Review with product team
- Validate design with UX team
- Review technical feasibility with engineering
- Conduct user interviews to validate JTBD assumptions
- Create detailed wireframes/mockups
- Begin Phase 1 implementation
Related Documents:
jtbd-analysis-inventory-setup.md- Jobs To Be Done analysisOnboardingWizard.tsx- Existing onboarding implementationAddModal.tsx- Existing modal component architecture
Reviewers:
- Product Manager
- UX Designer
- Tech Lead
- Backend Engineer
- QA Lead
Approval: Pending
End of Specification