# Comprehensive Architecture Analysis: UnifiedOnboardingWizard

## Executive Summary

The UnifiedOnboardingWizard is a 14-step onboarding flow that has evolved to integrate multiple concerns (file upload, inventory management, product categorization, stock entry, ML training) into a single, monolithic UploadSalesDataStep component. While the overall wizard architecture is sound, there is significant technical debt in the step implementations, particularly in UploadSalesDataStep which mixes file upload, inventory management, and state management responsibilities.

---

## 1. CURRENT ARCHITECTURE OVERVIEW

### 1.1 Wizard Structure

**Location**: `/frontend/src/components/domain/onboarding/`

The wizard consists of:
- **UnifiedOnboardingWizard.tsx** - Main wizard orchestrator (533 lines)
- **WizardContext.tsx** - State management (277 lines)
- **OnboardingWizard.tsx** - Deprecated (567 lines - SHOULD BE DELETED)
- **14 individual step components** (ranging from 736 to 74,627 lines)

### 1.2 Visible Steps Flow

The wizard displays 14 steps in this order:

```
Phase 1: Discovery
├─ 1. bakery-type-selection (BakeryTypeSelectionStep)
└─ 2. setup (RegisterTenantStep)

Phase 2a: AI-Assisted Inventory Path
├─ 3. smart-inventory-setup (UploadSalesDataStep) ⚠️ MEGA-COMPONENT
├─ 4. product-categorization (ProductCategorizationStep)
├─ 5. initial-stock-entry (InitialStockEntryStep)
└─ (Auto-completes: suppliers-setup)

Phase 2b: Setup Operations
├─ 6. suppliers-setup (SuppliersSetupStep)
├─ 7. recipes-setup (RecipesSetupStep - conditional)
├─ 8. production-processes (ProductionProcessesStep - conditional)

Phase 3: Advanced Features
├─ 9. quality-setup (QualitySetupStep)
└─ 10. team-setup (TeamSetupStep)

Phase 4: ML & Finalization
├─ 11. ml-training (MLTrainingStep)
├─ 12. setup-review (ReviewSetupStep)
└─ 13. completion (CompletionStep)
```

**Note**: Step numbering is complex because:
- Steps 1-13 are in UnifiedOnboardingWizard
- SetupWizard (deprecated) has separate steps (setup-welcome, suppliers-setup, etc.)
- Conditional visibility based on bakeryType
- Auto-completion logic for suppliers-setup

---

## 2. DETAILED ARCHITECTURAL ISSUES

### 2.1 ISSUE #1: UploadSalesDataStep is a Mega-Component (74,627 lines)

**Severity**: CRITICAL

**Current Responsibilities**:
1. File upload & validation (lines 1-169)
2. Automatic file analysis with AI (lines 141-169)
3. AI-based product classification (lines 171-247)
4. Inventory item form management (lines 249-433)
5. Stock lot management (lines 335-435)
6. Batch operations (lines 437-589)
7. Sales data import (lines 548-569)
8. UI rendering for two distinct phases:
   - File upload phase (lines 1408-1575)
   - Inventory list/editing phase (lines 612-1405)
9. Modal integration (BatchAddIngredientsModal)

**Problems**:
- Violates Single Responsibility Principle
- Hard to test (>1500 lines in single component)
- Multiple state variables (23 useState calls)
- Tightly couples file upload with inventory management
- Complex conditional rendering logic
- Difficult to reuse any sub-functionality

**Code Indicators**:
```typescript
// Line 22-114: THREE separate form interfaces and states
interface ProgressState { ... }
interface InventoryItemForm { ... }
// Plus: [selectedFile, isValidating, validationResult, inventoryItems, ...]
// TOTAL: 23+ state variables
const [selectedFile, setSelectedFile] = useState<File | null>(null);
const [isValidating, setIsValidating] = useState(false);
const [validationResult, setValidationResult] = useState<ImportValidationResponse | null>(null);
// ... 20 more state declarations
```

### 2.2 ISSUE #2: Separated File Upload & Inventory Concerns

**Severity**: HIGH

The UploadSalesDataStep handles TWO distinct user journeys:

**Journey 1: File Upload & Auto-Classification**
```
User uploads CSV
  ↓
Validate file (validateFileMutation)
  ↓
Classify products (classifyBatchMutation)
  ↓
Generate AI suggestions
  ↓
Show inventory list for review
```

**Journey 2: Manual Inventory Entry**
```
After AI suggestions generated
  ↓
Edit/add inventory items manually
  ↓
Add stock lots per item
  ↓
Create all ingredients via API (createIngredient)
  ↓
Create all stock lots (addStockMutation)
  ↓
Import sales data
```

**Problem**: Both journeys are in ONE component with complex conditional rendering:
```typescript
// Line 613: Conditional branch for entire second phase
if (showInventoryStep) {
  // 800+ lines of inventory management UI
  return (<div className="space-y-6"> ... </div>);
}

// Line 1408: Final 167 lines for file upload UI
return (<div className="space-y-6"> ... </div>);
```

### 2.3 ISSUE #3: State Management Fragmentation

**Severity**: MEDIUM

**Local Component State (UploadSalesDataStep)**:
- File selection: `selectedFile`, `isValidating`, `validationResult`
- Inventory: `inventoryItems`, `showInventoryStep`, `error`, `progressState`
- Form data: `formData`, `editingId`, `isAdding`, `formErrors`
- Stock lots: `addingStockForId`, `stockFormData`, `stockErrors`, `ingredientStocks`

**Wizard Context State** (WizardContext.tsx):
- `bakeryType`, `dataSource`, `uploadedFileName`, `uploadedFileSize`
- `aiSuggestions`, `aiAnalysisComplete`, `categorizedProducts`, `productsWithStock`
- Various completion flags: `categorizationCompleted`, `stockEntryCompleted`, etc.

**Backend Progress State** (API):
- `useUserProgress()` fetches current step, completed steps, completion percentage
- `useMarkStepCompleted()` updates backend after step completion

**Problem**: No clear separation of concerns
- Wizard context is "source of truth" but individual steps also have local state
- UI state (isAdding, editingId) mixed with data state (inventoryItems)
- No clear data flow: Step data → Wizard context → Backend
- Difficult to understand which data persists across sessions

### 2.4 ISSUE #4: Circular State Dependencies

**Severity**: MEDIUM

**UploadSalesDataStep → Wizard Context**:
```typescript
// Line 320: Updates wizard context on completion
wizardContext.updateAISuggestions(data.aiSuggestions);
wizardContext.setAIAnalysisComplete(true);
// Line 325:
wizardContext.updateCategorizedProducts(data.categorizedProducts);
```

**ProductCategorizationStep → Wizard Context**:
```typescript
// Receives products from wizard context
// Updates categorizedProducts in wizard context
onUpdate?.({ categorizedProducts: updatedProducts });
```

**InitialStockEntryStep → Wizard Context**:
```typescript
// Receives products from categorization
// Updates productsWithStock in wizard context
onUpdate?.({ productsWithStock: updatedProducts });
```

**Problem**: Steps update wizard context via `onUpdate()` AND `onComplete()`
- Data flows both ways (child → parent AND parent → child)
- Difficult to trace data transformations
- No clear contract between parent and child

### 2.5 ISSUE #5: Tight Coupling Between Wizard & Setup Components

**Severity**: HIGH

**UnifiedOnboardingWizard mixes:**
- 8 onboarding-specific steps from `/onboarding/steps/`
- 5 setup-specific steps from `/setup-wizard/steps/`

**Import at line 22-28**:
```typescript
import {
  SuppliersSetupStep,
  RecipesSetupStep,
  QualitySetupStep,
  TeamSetupStep,
  ReviewSetupStep,
} from '../setup-wizard/steps';
```

**Problem**:
- UnifiedOnboardingWizard shouldn't need setup-wizard imports
- Creates dependency between onboarding and setup domains
- Changes in setup steps affect onboarding flow
- Makes it harder to modify setup flow independently
- Violates layering/module boundaries

### 2.6 ISSUE #6: Auto-Completion Logic Scattered

**Severity**: MEDIUM

**Auto-completion of suppliers-setup** (line 349-365):
```typescript
// In UnifiedOnboardingWizard.handleStepComplete()
if (currentStep.id === 'smart-inventory-setup' && data?.shouldAutoCompleteSuppliers) {
  try {
    await markStepCompleted.mutateAsync({
      userId: user.id,
      stepName: 'suppliers-setup',
      data: { auto_completed: true, ... }
    });
  } catch (supplierError) {
    console.warn('Could not auto-complete suppliers-setup step');
  }
}
```

**Auto-completion of user_registered** (line 204-232):
```typescript
// In OnboardingWizardContent.useEffect()
useEffect(() => {
  if (userProgress && user?.id && !autoCompletionAttempted && !markStepCompleted.isPending) {
    const userRegisteredStep = userProgress.steps.find(s => s.step_name === 'user_registered');
    if (!userRegisteredStep?.completed) {
      // Auto-complete...
    }
  }
}, [...]);
```

**Problem**:
- Auto-completion logic is buried in step completion handler
- No clear policy for which steps can be auto-completed
- Difficult to add new auto-completion rules
- Inconsistent with manual step completion flow

### 2.7 ISSUE #7: Condition Functions Are Scattered & Duplicated

**Severity**: LOW-MEDIUM

**Step visibility conditions** (line 59-165):
```typescript
const ALL_STEPS: StepConfig[] = [
  {
    id: 'smart-inventory-setup',
    condition: (ctx) => ctx.tenantId !== null,
  },
  {
    id: 'product-categorization',
    condition: (ctx) => ctx.state.aiAnalysisComplete,
  },
  {
    id: 'initial-stock-entry',
    condition: (ctx) => ctx.state.categorizationCompleted,
  },
  {
    id: 'suppliers-setup',
    // Always show - no conditional
  },
  {
    id: 'recipes-setup',
    condition: (ctx) =>
      ctx.state.bakeryType === 'production' || ctx.state.bakeryType === 'mixed',
  },
  // ... more conditions
];
```

**Identical conditions in WizardContext** (line 183-189):
```typescript
getVisibleSteps = (): string[] => {
  // ... same conditions repeated
  if (state.bakeryType === 'production' || state.bakeryType === 'mixed') {
    steps.push('recipes-setup');
  }
  if (state.bakeryType === 'retail' || state.bakeryType === 'mixed') {
    steps.push('production-processes');
  }
};
```

**Problem**:
- Same logic defined in TWO places
- Changes require updates in multiple files
- No single source of truth for visibility rules
- Conditions are business logic, should be defined separately

### 2.8 ISSUE #8: Complex Data Transformations Without Clear Contracts

**Severity**: MEDIUM**

**UploadSalesDataStep → ProductCategorizationStep**:
```typescript
// Line 203-235: UploadSalesDataStep generates InventoryItemForm[]
const items: InventoryItemForm[] = classificationResponse.suggestions.map((suggestion) => ({
  id: `ai-${index}-${Date.now()}`,
  name: suggestion.suggested_name,
  // ... 15 more properties
}));

// Then completes with:
onComplete({
  createdIngredients,
  totalItems: createdIngredients.length,
  validationResult,
  // ... more data
});

// But ProductCategorizationStep expects Product[] (different interface!)
interface Product {
  id: string;
  name: string;
  category?: string;
  confidence?: number;
  type?: 'ingredient' | 'finished_product' | null;
  suggestedType?: 'ingredient' | 'finished_product';
}
```

**Problem**:
- No clear transformation between step outputs and next step inputs
- Multiple data formats for similar data
- Type mismatches not caught until runtime
- No schema/contract for inter-step communication

---

## 3. STEP DEPENDENCIES & DATA FLOW

### 3.1 Dependency Diagram

```
BakeryTypeSelectionStep
  └─> wizardContext.updateBakeryType()
      └─> affects visibility of: recipes-setup, production-processes

RegisterTenantStep
  └─> wizardContext.tenantId (implicit - via tenant store)
      └─> enables: smart-inventory-setup

UploadSalesDataStep [MEGA-COMPONENT]
  ├─> Validates file (validateFileMutation)
  ├─> Classifies products (classifyBatchMutation)
  ├─> Creates inventory (createIngredient) ← INVENTORY CONCERN
  ├─> Creates stock lots (addStockMutation) ← INVENTORY CONCERN
  ├─> Imports sales data (importMutation)
  ├─> wizardContext.updateAISuggestions()
  ├─> wizardContext.setAIAnalysisComplete()
  ├─> markStepCompleted() [auto-completes suppliers-setup] ← ORCHESTRATION
  └─> onComplete() with shouldAutoCompleteSuppliers flag

ProductCategorizationStep
  ├─> Input: wizard context aiSuggestions or initialData.categorizedProducts
  ├─> onUpdate() → wizardContext.updateCategorizedProducts()
  └─> onComplete()
      └─> wizardContext.markStepComplete('categorizationCompleted')

InitialStockEntryStep
  ├─> Input: categorizedProducts (which type: ingredient or finished_product?)
  ├─> onUpdate() → wizardContext.updateProductsWithStock()
  └─> onComplete()
      └─> wizardContext.markStepComplete('stockEntryCompleted')

SuppliersSetupStep (from setup-wizard)
  ├─> May be auto-completed by UploadSalesDataStep
  └─> Creates suppliers

RecipesSetupStep (conditional: production or mixed)
  └─> Depends on suppliers existing

ProductionProcessesStep (conditional: retail or mixed)
  └─> May depend on recipes?

MLTrainingStep
  └─> Input: inventory data from previous steps
      └─> No explicit dependency check

ReviewSetupStep
  └─> Shows summary of configuration

CompletionStep
  └─> Final step, navigates away
```

### 3.2 Data Flow Diagram

```
┌─────────────────────────────────────────────────────────────────┐
│                       UnifiedOnboardingWizard                   │
│                     (Step Orchestrator)                         │
└─────────────────────────────────────────────────────────────────┘
         ↑                                                    ↑
         │ state (VISIBLE_STEPS, currentStepIndex)          │ markStepCompleted()
         │                                                    │
    ┌────┴───────────────────────────────────────────────────┴──┐
    │                     WizardContext                          │
    │  (State: bakeryType, aiSuggestions, categorizedProducts)   │
    │  (State: productsWithStock, various completion flags)      │
    └────┬───────────────────────────────────────────────────┬───┘
         │ onUpdate() / onComplete()                         │
         │ (data flows FROM steps TO context)               │
         │                                                    │
    ┌────┴────────────────────────────────────────────────┬──┘
    │                   Individual Steps                   │
    │                                                      │
    │  BakeryTypeSelectionStep                           │
    │  RegisterTenantStep                                │
    │  UploadSalesDataStep ⚠️ [73KB, 23 state vars]      │
    │    ├─ File validation                              │
    │    ├─ AI classification                            │
    │    ├─ Inventory creation                           │
    │    └─ Stock lot management                         │
    │  ProductCategorizationStep                         │
    │  InitialStockEntryStep                             │
    │  SuppliersSetupStep (from setup-wizard)            │
    │  ...                                                │
    └──────────────────────────────────────────────────────┘
              │                                  │
              │                                  │
         API mutations                  Backend progress
    (validateFile, classifyBatch,      (useUserProgress,
     createIngredient, addStock,        useMarkStepCompleted)
     importSalesData)
```

### 3.3 Data Transformation Pipeline

```
CSV/JSON File
    ↓
[UploadSalesDataStep] validateFileMutation
    ↓ (ImportValidationResponse)
    ├─ total_records, valid_records, invalid_records
    ├─ product_list: string[]
    └─ ...
    ↓
[UploadSalesDataStep] classifyBatchMutation
    ↓ (ProductSuggestionResponse[])
    ├─ id, suggested_name, product_type
    ├─ category, unit_of_measure
    ├─ confidence_score
    ├─ estimated_shelf_life_days
    ├─ requires_refrigeration, requires_freezing, is_seasonal
    ├─ low_stock_threshold, reorder_point
    └─ sales_data: { total_quantity, average_daily_sales }
    ↓
[UploadSalesDataStep] Transform to InventoryItemForm[]
    ├─ id: string (temporary UI ID)
    ├─ name, product_type, category
    ├─ unit_of_measure
    ├─ stock_quantity (calculated from sales data)
    ├─ cost_per_unit (estimated)
    ├─ estimated_shelf_life_days
    ├─ requires_refrigeration, requires_freezing, is_seasonal
    ├─ low_stock_threshold, reorder_point
    ├─ isSuggested: boolean
    ├─ confidence_score
    └─ sales_data: { total_quantity, average_daily_sales }
    ↓
[UploadSalesDataStep] User review & manual edits
    ├─ Add/edit/delete inventory items
    ├─ Add stock lots (optional)
    └─ ...
    ↓
[UploadSalesDataStep] createIngredient mutations (parallel)
    ↓ (Ingredient[])
    ├─ id (from backend)
    ├─ name, product_type, category
    ├─ unit_of_measure, shelf_life_days
    ├─ requires_refrigeration, requires_freezing, is_seasonal
    ├─ low_stock_threshold, max_stock_level, reorder_point
    └─ average_cost
    ↓
[UploadSalesDataStep] addStockMutation (parallel)
    ↓ (StockResponse[])
    ├─ id (from backend)
    ├─ ingredient_id
    ├─ current_quantity
    ├─ expiration_date
    ├─ supplier_id
    ├─ batch_number
    ├─ production_stage
    └─ quality_status
    ↓
[UploadSalesDataStep] importMutation (sales data)
    ↓
[ProductCategorizationStep] ← BUT RECEIVES: wizard context aiSuggestions
    ↓ (Product[] with type: 'ingredient' | 'finished_product')
    ↓
[InitialStockEntryStep] ← Receives: categorizedProducts
    ↓ (ProductWithStock[] with initialStock)
    ↓
[Backend] Final inventory saved
```

**Problem**: Data transformations are implicit and scattered across files. No clear schema/types for inter-step data passing.

---

## 4. LEGACY & DEPRECATED COMPONENTS

### 4.1 OnboardingWizard.tsx - DEPRECATED

**Location**: `/frontend/src/components/domain/onboarding/OnboardingWizard.tsx`

**Status**: DEPRECATED but still exported in index.ts

**Usage**:
```typescript
// frontend/src/components/domain/onboarding/index.ts
export { OnboardingWizard } from './OnboardingWizard';  ← EXPORTED BUT NOT USED
export { UnifiedOnboardingWizard } from './UnifiedOnboardingWizard';  ← THIS IS USED
```

**Confirmation of non-usage**:
- OnboardingPage.tsx uses only UnifiedOnboardingWizard
- No other imports of OnboardingWizard found in codebase
- Old wizard has simplified step flow (4 steps vs 14)

**Recommendation**: DELETE OnboardingWizard.tsx and remove from index.ts exports

### 4.2 SetupWizard.tsx - STILL IN USE

**Location**: `/frontend/src/components/domain/setup-wizard/SetupWizard.tsx`

**Status**: ACTIVE but DEPRECATED by design

**Usage**:
```typescript
// frontend/src/pages/setup/SetupPage.tsx
const SetupPage: React.FC = () => {
  return <SetupWizard />;
};
```

**Problem**:
- UnifiedOnboardingWizard imports setup-wizard steps directly
- Creates tight coupling between onboarding and setup domains
- SetupWizard is now redundant - setup steps are integrated into UnifiedOnboardingWizard
- Separate SetupPage route still exists (/app/setup)

**Recommendation**: 
1. Remove setup-wizard imports from UnifiedOnboardingWizard
2. Keep SetupWizard.tsx for backwards compatibility OR
3. Transition to new onboarding flow only and deprecate SetupPage

### 4.3 Route Duplication

**Current Routes**:
- `/app/onboarding` → OnboardingPage → UnifiedOnboardingWizard ✓ CORRECT
- `/app/setup` → SetupPage → SetupWizard ✓ LEGACY (now integrated into onboarding)

**Recommendation**:
- Remove /app/setup route OR
- Make it redirect to /app/onboarding for backwards compatibility

---

## 5. FILES TO DELETE

| File | Status | Reason |
|------|--------|--------|
| `/frontend/src/components/domain/onboarding/OnboardingWizard.tsx` | DELETE | Fully deprecated, non-functional |
| `/frontend/src/pages/setup/SetupPage.tsx` | DELETE or REDIRECT | Setup flow now integrated into onboarding |
| Setup wizard route entry in routes.config.ts | REMOVE | Duplicate with onboarding |

---

## 6. ARCHITECTURAL PROBLEMS SUMMARY

### Problem #1: MEGA-COMPONENT (UploadSalesDataStep)
- **Type**: Single Responsibility Principle Violation
- **Severity**: CRITICAL
- **Impact**: Hard to test, maintain, and extend
- **Solution**: Split into:
  - FileUploadPhase (controlled by parent)
  - InventoryManagementPhase (separate component or reusable)
  - AI classification logic (service)

### Problem #2: State Management Fragmentation
- **Type**: State Distribution Anti-Pattern
- **Severity**: HIGH
- **Impact**: Difficult to trace data flow, understand state transitions
- **Solution**: 
  - Clear separation: UI state (local) vs Data state (context)
  - Define explicit data contracts between steps
  - Consider step output → context mapping layer

### Problem #3: Mixed Concerns in One Component
- **Type**: Separation of Concerns Violation
- **Severity**: HIGH
- **Impact**: Tight coupling, difficult to test individual features
- **Solution**:
  - File upload logic → FileUploadService
  - Inventory form logic → InventoryFormComponent
  - Stock lot logic → StockLotComponent
  - Composition pattern to combine them

### Problem #4: Duplicate Visibility Logic
- **Type**: DRY Principle Violation
- **Severity**: MEDIUM
- **Impact**: Maintenance burden, potential inconsistencies
- **Solution**:
  - Extract visibility rules into dedicated config/service
  - Single source of truth for step conditions

### Problem #5: Circular Data Dependencies
- **Type**: Bidirectional Data Flow Anti-Pattern
- **Severity**: MEDIUM
- **Impact**: Hard to understand data flow direction
- **Solution**:
  - Strict unidirectional data flow (parent → child via props, child → parent via callbacks)
  - Clear input/output contracts for each step

### Problem #6: Tight Coupling: Onboarding ↔ Setup Wizard
- **Type**: Module Boundary Violation
- **Severity**: HIGH
- **Impact**: Difficult to modify either wizard independently
- **Solution**:
  - Remove setup-wizard imports from UnifiedOnboardingWizard
  - Define step interface contract
  - Load steps dynamically by configuration

### Problem #7: Complex Auto-Completion Logic
- **Type**: Business Logic Distribution
- **Severity**: MEDIUM
- **Impact**: Difficult to understand which steps auto-complete
- **Solution**:
  - Centralized auto-completion policy
  - Explicit configuration for which steps can auto-complete
  - Clear rules for completion dependencies

### Problem #8: No Clear Inter-Step Communication Contract
- **Type**: Interface Definition Anti-Pattern
- **Severity**: MEDIUM
- **Impact**: Type mismatches between steps (InventoryItemForm vs Product vs ProductWithStock)
- **Solution**:
  - Define Step Interface Contract
  - Create transformation layer between step outputs
  - Use consistent naming/typing across all steps

---

## 7. STEP RESPONSIBILITIES MATRIX

| Step | Primary Responsibility | State Type | Dependencies | Outputs |
|------|------------------------|-----------|--------------|---------|
| BakeryTypeSelectionStep | Select bakery model | UI | None | bakeryType |
| RegisterTenantStep | Register bakery details | API call | bakeryType | tenantId, tenant object |
| **UploadSalesDataStep** | **File upload + Inventory mgmt + Stock lots** | **API calls + Local forms** | **tenantId** | **Ingredients[] + Stock[] + Sales import result** |
| ProductCategorizationStep | Classify products | Drag-drop state | aiSuggestions | categorizedProducts |
| InitialStockEntryStep | Set initial stock levels | Form state | categorizedProducts | productsWithStock |
| SuppliersSetupStep | Add suppliers | API + Form | tenantId | suppliers (or auto-completed) |
| RecipesSetupStep | Create recipes | API + Complex forms | ingredients + suppliers | recipes |
| ProductionProcessesStep | Define processes | API + Complex forms | bakeryType | processes |
| QualitySetupStep | Set quality standards | API + Forms | tenantId | quality templates |
| TeamSetupStep | Add team members | API + Forms | tenantId | team members |
| MLTrainingStep | Train ML models | API poll + long-running | inventory data | trained models |
| ReviewSetupStep | Show configuration summary | Read-only | All previous data | (none, informational) |
| CompletionStep | Celebrate + redirect | Navigation | None | Navigate to dashboard |

---

## 8. RECOMMENDATIONS FOR REFACTORING

### Immediate Actions (Quick Wins)

1. **Delete OnboardingWizard.tsx**
   - Remove from exports in index.ts
   - Impact: LOW (not used)
   - Time: 5 minutes

2. **Remove setup-wizard imports from UnifiedOnboardingWizard**
   - Load setup steps dynamically
   - Create step registry/configuration
   - Impact: MEDIUM (refactoring pattern needed)
   - Time: 2-3 hours

3. **Extract visibility rules to dedicated config**
   - Move bakeryType conditions to one place
   - Impact: LOW (pure refactoring)
   - Time: 1 hour

### Medium-term Refactoring (1-2 Sprint)

4. **Split UploadSalesDataStep**
   - Extract FileUploadPhase (lines 1408-1575)
   - Extract InventoryManagementPhase (lines 612-1405)
   - Create composition layer
   - Move AI classification to service
   - Impact: HIGH (major refactoring)
   - Time: 6-8 hours

5. **Define Inter-Step Data Contracts**
   - Create interfaces for step input/output
   - Add transformation layer between steps
   - Impact: HIGH (enforces consistency)
   - Time: 4-6 hours

6. **Separate UI State from Data State in WizardContext**
   - Move isAdding, editingId to component state
   - Keep only data state in context
   - Impact: MEDIUM (refactoring)
   - Time: 3-4 hours

### Long-term Architecture (2-3 Months)

7. **Implement Step Interface Contract**
   - Define standard step props/callback signatures
   - Enforce typing at wizard level
   - Impact: HIGH (system-wide improvement)
   - Time: 1-2 sprints

8. **Extract Auto-Completion Policy Engine**
   - Centralized configuration for auto-completion
   - Clear rules for step dependencies
   - Impact: MEDIUM (optional feature)
   - Time: 1 sprint

9. **Consolidate Setup & Onboarding Routes**
   - Make /app/setup redirect to /app/onboarding
   - OR keep SetupPage for post-onboarding scenarios
   - Impact: LOW-MEDIUM (routing refactoring)
   - Time: 2-3 hours

---

## 9. CURRENT STEP-BY-STEP FLOW DIAGRAM

```
┌───────────────────────────────────────────────────────────┐
│ USER FLOW: UnifiedOnboardingWizard (14 Steps)             │
└───────────────────────────────────────────────────────────┘

START: User completes registration
       ↓ Auto-completes user_registered step
       
STEP 1: Bakery Type Selection
       └─> SELECT: production | retail | mixed
           └─> STORES: bakeryType in context
       
STEP 2: Register Tenant
       └─> ENTER: Bakery name, address, phone, city
           └─> API: registerBakery()
           └─> STORES: tenantId, tenant object
       
STEP 3: Upload Sales Data (⚠️ MEGA-COMPONENT)
       ├─> UPLOAD: CSV/JSON file with sales history
       │   └─> API: validateFile()
       │   └─> API: classifyBatch() [AI classification]
       │   └─> DISPLAY: Suggested inventory items
       │
       └─> REVIEW & EDIT: Inventory items
           ├─ ALLOW: Add, edit, delete items
           ├─ ALLOW: Add stock lots per item
           │   └─> FIELDS: Quantity, expiration date, supplier, batch number
           │
           └─> API: createIngredient() [parallel for all items]
               └─> API: addStock() [parallel for all stock lots]
               └─> API: importSalesData() [background import]
               └─> Auto-complete: suppliers-setup step
       
STEP 4: Product Categorization
       ├─> DISPLAY: Suggested AI classifications
       ├─> ALLOW: Drag-drop to categorize as ingredient or finished_product
       └─> STORES: categorizedProducts in context
       
STEP 5: Initial Stock Entry
       ├─> DISPLAY: All products from categorization
       ├─> ALLOW: Enter initial stock quantities
       └─> STORES: productsWithStock in context
       
STEP 6: Suppliers Setup ⭐ (May be auto-completed)
       ├─> IF auto-completed: Display "✓ Auto-setup"
       └─> ELSE: ALLOW: Add suppliers (company, contact, details)
           └─> API: createSupplier()
       
STEP 7: Recipes Setup (CONDITIONAL: production or mixed bakeries)
       ├─> ALLOW: Create recipes with ingredients
       ├─> INPUT: Select ingredients from inventory
       ├─> INPUT: Set quantities, proportions
       └─> API: createRecipe()
       
STEP 8: Production Processes (CONDITIONAL: retail or mixed bakeries)
       ├─> ALLOW: Define production workflows
       └─> API: createProcess()
       
STEP 9: Quality Setup
       ├─> ALLOW: Define quality templates/standards
       └─> API: createQualityTemplate()
       
STEP 10: Team Setup
       ├─> ALLOW: Add team members, assign roles
       └─> API: inviteUser()
       
STEP 11: ML Training
       ├─> INFO: "Training personalized AI model..."
       ├─> DISPLAY: Progress indicator
       ├─> WAIT: For training job completion (API poll)
       └─> DISPLAY: Model accuracy metrics
       
STEP 12: Setup Review
       ├─> DISPLAY: Summary of all configuration
       └─> ALLOW: Review before finalizing
       
STEP 13: Completion
       └─> DISPLAY: "✓ Setup complete!"
           └─> REDIRECT: /app/dashboard

END: User is now in the main application
```

---

## 10. SUMMARY TABLE

| Aspect | Status | Priority | Notes |
|--------|--------|----------|-------|
| Overall Architecture | FUNCTIONAL | - | Works but has technical debt |
| UnifiedOnboardingWizard Main | GOOD | LOW | Well-structured orchestrator |
| WizardContext | ACCEPTABLE | MEDIUM | State management needs clarification |
| UploadSalesDataStep | POOR | CRITICAL | 74KB mega-component needs refactoring |
| OnboardingWizard (old) | DEPRECATED | HIGH | Should be deleted |
| SetupWizard Integration | PROBLEMATIC | HIGH | Tight coupling needs fixing |
| Visibility Rules | DUPLICATE | MEDIUM | DRY principle violation |
| Inter-Step Contracts | UNDEFINED | MEDIUM | No formal interface definition |
| Auto-Completion | AD-HOC | MEDIUM | Needs centralized policy |
| State Management | FRAGMENTED | MEDIUM | Mixing UI and data state |

---

## APPENDIX: FILE STATISTICS

| File | Size | LOC | Complexity | Status |
|------|------|-----|-----------|--------|
| UnifiedOnboardingWizard.tsx | 20.5 KB | 533 | MEDIUM | GOOD |
| WizardContext.tsx | 9.5 KB | 277 | MEDIUM | ACCEPTABLE |
| OnboardingWizard.tsx | 19.5 KB | 567 | MEDIUM | DEPRECATED |
| UploadSalesDataStep.tsx | 74.6 KB | 1577 | HIGH | POOR |
| ProductCategorizationStep.tsx | 14.3 KB | 365 | MEDIUM | ACCEPTABLE |
| InitialStockEntryStep.tsx | 11.2 KB | 286 | LOW | GOOD |
| BakeryTypeSelectionStep.tsx | 11 KB | 277 | MEDIUM | GOOD |
| RegisterTenantStep.tsx | 7.8 KB | ~200 | LOW | GOOD |
| SetupWizard.tsx | ~30 KB | ~800 | MEDIUM | ACTIVE |
| **TOTAL ONBOARDING** | **~169 KB** | **~3665** | - | - |

---
