bakery-ia/REFACTORING_ROADMAP.md

UnifiedOnboardingWizard Refactoring Roadmap

Quick Executive Summary

Current State: Functional but architecturally problematic Main Issue: UploadSalesDataStep is a 74KB mega-component mixing 8+ different concerns Debt Level: HIGH - Technical debt is impacting maintainability

---

Critical Issues (Must Fix)

1. UploadSalesDataStep is Too Large (CRITICAL)

• File Size: 74,627 bytes (73KB)
• Lines: 1,577 lines
• State Variables: 23 useState hooks
• Methods: Handles file upload, validation, classification, inventory management, stock lots, and more
• Impact: Almost impossible to test, modify, or reuse components

What it should do:

• Single responsibility: Upload and validate file

What it actually does:

1. File upload UI and drag-drop
2. File validation API call
3. AI classification API call
4. Inventory item form management (CRUD)
5. Stock lot management (CRUD)
6. Batch ingredient creation
7. Sales data import
8. Two entirely different UIs (upload phase vs inventory review phase)

Refactoring Approach:

Current:
UploadSalesDataStep (1577 lines, 23 state vars)

Should be:
├─ FileUploadPhase (200 lines)
│  ├─ FileDropZone
│  ├─ FileValidator
│  └─ ProgressIndicator
│
├─ InventoryManagementPhase (500 lines)
│  ├─ InventoryItemList
│  ├─ InventoryItemForm
│  ├─ StockLotManager
│  └─ BatchAddModal
│
├─ InventoryService (classification, validation)
│
└─ UploadSalesDataStepContainer (orchestrator, 150 lines)
   ├─ Phase state machine
   ├─ Data flow coordination
   └─ API integration

2. Tight Coupling Between Onboarding & Setup (CRITICAL)

• UnifiedOnboardingWizard imports from setup-wizard/steps/
• Changes to setup steps affect onboarding flow
• Makes it impossible to modify setup independently

Current Problem:

// UnifiedOnboardingWizard.tsx line 22-28
import {
  SuppliersSetupStep,
  RecipesSetupStep,
  QualitySetupStep,
  TeamSetupStep,
  ReviewSetupStep,
} from '../setup-wizard/steps';  // ← CROSS-DOMAIN IMPORT

Solution:

• Define step interface contract
• Move setup steps to configuration
• Load steps dynamically
• Create step registry pattern

3. Circular State Dependencies (HIGH)

• Steps update wizard context via both onUpdate() and onComplete()
• Data flows both directions
• No clear source of truth

Current Flow:

UploadSalesDataStep.onUpdate() → wizardContext
ProductCategorizationStep.onUpdate() → wizardContext
InitialStockEntryStep.onUpdate() → wizardContext
All steps also call onComplete() with different data

Should Be:

Step.onUpdate() → Local UI state (transient)
Step.onComplete() → Single source of truth (wizardContext + Backend)

---

High Priority Issues (Fix in Next Sprint)

4. Duplicate Visibility Logic

Locations:

• UnifiedOnboardingWizard.tsx (line 59-165): Step conditions
• WizardContext.tsx (line 183-189): getVisibleSteps() logic
• Same rules repeated in two places

Fix: Extract to single configuration file

5. Auto-Completion Logic is Scattered

• user_registered auto-completion: OnboardingWizardContent.useEffect() (line 204)
• suppliers-setup auto-completion: UnifiedOnboardingWizard.handleStepComplete() (line 349)
• No clear policy or pattern

Fix: Centralized auto-completion policy engine

6. State Management Confusion

• UI state mixed with data state in context
• No clear boundary between component state and context state
• Difficult to understand data persistence

Fix:

• UI state (isAdding, editingId, showInventoryStep) → Component local state
• Data state (aiSuggestions, categorizedProducts) → Context
• Session state → Backend API

---

Medium Priority Issues (Fix Over Time)

7. No Inter-Step Communication Contract

Problem: Different components use different interfaces for same data

• InventoryItemForm (line 28-50)
• Product (ProductCategorizationStep line 7-14)
• ProductWithStock (InitialStockEntryStep line 8-15)
• Ingredient (API type)
• Stock (API type)

All represent similar data but with different shapes.

Fix: Create unified type system for inventory throughout flow

8. Complex Data Transformations Without Clear Schema

Data travels through pipeline with implicit transformations:

File → ImportValidationResponse → ProductSuggestionResponse 
→ InventoryItemForm → Ingredient → Stock → categorizedProducts 
→ Product (different type!) → ProductWithStock

Fix: Create explicit transformation functions between steps

---

Files to Delete (Immediate)

1. OnboardingWizard.tsx (567 lines, 19.5KB)

   • Status: Deprecated, not used
   • Usage: Only in exports, never imported
   • Risk: LOW - completely safe to delete
   • Action: DELETE and remove from index.ts exports

2. SetupPage.tsx (18 lines, 567 bytes) - OPTIONAL

   • Status: Deprecated by design
   • Usage: Route /app/setup still references it
   • Risk: MEDIUM - needs migration plan
   • Action: Either delete or redirect to /app/onboarding

3. Setup route in routes.config.ts (line 578-593) - OPTIONAL

   • Status: Redundant with /app/onboarding
   • Action: Remove or convert to redirect

---

Refactoring Priority & Timeline

Phase 1: Quick Wins (Week 1)

Time: 2-3 hours Impact: LOW immediate, HIGH long-term

• Delete OnboardingWizard.tsx
• Remove from index.ts exports
• Extract visibility rules to config file
• Add comments documenting current state

Phase 2: State Management Cleanup (Week 2)

Time: 3-4 hours Impact: MEDIUM

• Document which state belongs where (UI vs Context vs Backend)
• Move UI state out of context (isAdding, editingId, etc.)
• Clear data flow direction (parent → child → parent only)

Phase 3: Split UploadSalesDataStep (Sprint)

Time: 6-8 hours Impact: CRITICAL

• Extract FileUploadPhase component
• Extract InventoryManagementPhase component
• Extract classification logic to service
• Create container component to orchestrate
• Add unit tests for each extracted component

Phase 4: Decouple Onboarding from Setup (Sprint)

Time: 4-6 hours Impact: HIGH

• Define step interface contract
• Create step registry/configuration
• Move setup steps to configuration
• Load steps dynamically

Phase 5: Inter-Step Communication (Sprint)

Time: 4-6 hours Impact: MEDIUM

• Define unified inventory type system
• Create transformation functions between steps
• Add type validation at step boundaries
• Document data contracts

---

Current Architecture Summary

Strengths

1. Main Wizard Orchestrator is Well-Designed

   • Clean step navigation
   • Good progress tracking
   • Proper initialization logic
   • Clear completion flow

2. WizardContext is Reasonable

   • Good use of React Context API
   • Most step data stored centrally
   • Safe from localStorage corruption

3. Most Individual Steps are Well-Designed

   • ProductCategorizationStep: Good UI/UX
   • InitialStockEntryStep: Simple and effective
   • BakeryTypeSelectionStep: Beautiful design

Weaknesses

1. UploadSalesDataStep is a Monster

   • Mixes file upload + inventory management
   • Too many state variables
   • Difficult to test
   • Difficult to reuse

2. Module Boundaries are Blurred

   • Onboarding imports from setup-wizard
   • Difficult to modify either independently
   • Violates separation of concerns

3. State Management is Confusing

   • UI state mixed with data state
   • Bidirectional data flow
   • Multiple sources of truth

4. No Clear Contracts Between Steps

   • Data types change between steps
   • Implicit transformations
   • Runtime type errors possible

---

How to Use This Document

1. For Planning: Use Phase 1-5 to plan sprints
2. For Understanding: Read ARCHITECTURE_ANALYSIS.md for detailed breakdown
3. For Implementation: Follow the refactoring approach in each section
4. For Maintenance: Reference this after refactoring to keep architecture clean

---

Success Criteria

After refactoring, the codebase should have:

• UploadSalesDataStep is <300 lines
• No imports between onboarding and setup-wizard domains
• Clear separation of UI state and data state
• All steps follow same interface contract
• Data transformations are explicit and testable
• Unit test coverage >80% for all step components
• All 8 architectural problems resolved
• Deprecated files deleted (OnboardingWizard.tsx)

---

Estimated Effort

Phase	Effort	Impact	Timeline
Phase 1 (Quick Wins)	2-3 hours	LOW	Week 1
Phase 2 (State Management)	3-4 hours	MEDIUM	Week 2
Phase 3 (Split Component)	6-8 hours	CRITICAL	Sprint 2
Phase 4 (Decouple Domains)	4-6 hours	HIGH	Sprint 3
Phase 5 (Data Contracts)	4-6 hours	MEDIUM	Sprint 4
TOTAL	19-27 hours	HIGH	4-5 Weeks

---

Contact & Questions

For detailed architecture information, see: ARCHITECTURE_ANALYSIS.md

Key sections:

• Section 2: Detailed architectural issues with code examples
• Section 3: Step dependencies and data flow diagrams
• Section 6: Problem statements for each issue
• Section 8: Detailed recommendations for each refactoring task