usda-vision/scheduling-remote/REFACTORING_PROPOSAL.md

Scheduling Component Refactoring Proposal

Current State Analysis

The ScheduleExperiment component is approximately 1,140 lines and handles multiple responsibilities:

1. Conductor Management (~150 lines)

   • Fetching conductors
   • Selection state
   • Color mapping
   • Availability fetching

2. Phase/Experiment/Repetition Management (~300 lines)

   • Phase expansion/collapse
   • Experiment loading
   • Repetition creation/selection
   • Soaking/airdrying data fetching

3. Calendar Event Management (~200 lines)

   • Event generation
   • Drag and drop handling
   • Availability events
   • Styling and theming

4. Scheduling Logic (~300 lines)

   • Repetition spawning
   • Staggering calculations
   • Phase timing updates
   • Lock/unlock functionality
   • Database persistence

5. UI Rendering (~200 lines)

   • Conductor panel
   • Phase/Experiment/Repetition tree
   • Calendar component
   • Loading/error states

Proposed Structure

Component Hierarchy

ScheduleExperiment (Main Container - ~150 lines)
├── ConductorPanel (UI Component - ~100 lines)
├── ExperimentPhasePanel (UI Component - ~150 lines)
│   ├── ExperimentItem (UI Component - ~80 lines)
│   │   └── RepetitionItem (UI Component - ~120 lines)
└── SchedulingCalendar (UI Component - ~150 lines)

Custom Hooks

hooks/
├── useConductors.ts (~100 lines)
│   - Conductor fetching
│   - Selection state
│   - Color mapping
│   - Availability fetching
│
├── useExperimentPhases.ts (~150 lines)
│   - Phase/Experiment/Repetition data fetching
│   - Expansion state
│   - Selection state
│   - Soaking/airdrying data
│
├── useScheduling.ts (~200 lines)
│   - Repetition scheduling state
│   - Spawn/stagger logic
│   - Phase timing updates
│   - Lock/unlock functionality
│   - Database persistence
│
└── useCalendarEvents.ts (~150 lines)
    - Calendar event generation
    - Drag and drop handlers
    - Event styling
    - Scroll preservation

File Structure

scheduling-remote/src/components/
├── Scheduling.tsx (Main router - unchanged)
├── ScheduleExperiment/
│   ├── index.tsx (Main container - ~150 lines)
│   ├── ConductorPanel.tsx (~100 lines)
│   ├── ExperimentPhasePanel.tsx (~150 lines)
│   ├── ExperimentItem.tsx (~80 lines)
│   ├── RepetitionItem.tsx (~120 lines)
│   └── SchedulingCalendar.tsx (~150 lines)
└── hooks/
    ├── useConductors.ts (~100 lines)
    ├── useExperimentPhases.ts (~150 lines)
    ├── useScheduling.ts (~200 lines)
    └── useCalendarEvents.ts (~150 lines)

Benefits

1. Maintainability: Each component has a single, clear responsibility
2. Testability: Smaller units are easier to test in isolation
3. Reusability: Components and hooks can be reused elsewhere
4. Readability: Easier to understand and navigate
5. Performance: Better optimization opportunities with smaller components
6. Collaboration: Multiple developers can work on different parts simultaneously

Refactoring Strategy

Phase 1: Extract Custom Hooks (Low Risk)

1. Extract useConductors hook
2. Extract useExperimentPhases hook
3. Extract useScheduling hook
4. Extract useCalendarEvents hook
5. Test each hook independently

Phase 2: Extract UI Components (Medium Risk)

1. Extract ConductorPanel component
2. Extract ExperimentPhasePanel component
3. Extract ExperimentItem component
4. Extract RepetitionItem component
5. Extract SchedulingCalendar component
6. Test component integration

Phase 3: Refactor Main Component (Low Risk)

1. Update ScheduleExperiment to use extracted hooks and components
2. Remove duplicate code
3. Final integration testing

Best Practices Applied

1. Single Responsibility Principle: Each component/hook has one clear purpose
2. Custom Hooks for Logic: Business logic separated from UI
3. Props Drilling vs Context: Use props for direct parent-child, context only if needed
4. Memoization: Preserve existing useMemo/useCallback optimizations
5. Type Safety: Maintain all TypeScript types
6. State Management: Keep related state together in hooks

Migration Path

1. Backward Compatible: All functionality preserved
2. Incremental: Can be done in phases
3. Testable: Each phase can be tested independently
4. Reversible: Changes can be rolled back if needed

Estimated Impact

• Main Component: 1,140 lines → ~150 lines (87% reduction)
• Total Lines: ~1,140 → ~1,200 (slight increase due to imports/exports, but much better organized)
• Complexity: Significantly reduced per file
• Maintainability: Dramatically improved