Variant System Transformation Plan

Current System Analysis

How Variants Currently Work

1. Blocking Generation: When a user creates or updates code, the system generates NUM_VARIANTS (2) variants in parallel using different AI models
2. All-or-Nothing: The WebSocket connection remains open until ALL variants complete generation
3. No Interactivity During Generation: Users must wait for all variants to finish before they can:
   • Select a variant
   • Make updates
   • Start a new generation

Key Components

Backend (backend/routes/generate_code.py)

• Lines 286-348: Creates parallel tasks for all variants
• Line 350: Uses asyncio.gather() to wait for ALL tasks to complete
• Line 447: Only closes WebSocket after all variants are done
• Sends messages with variantIndex to route to correct variant

Frontend

• frontend/src/generateCode.ts: WebSocket client that only triggers onComplete when connection closes
• frontend/src/App.tsx: Sets AppState.CODING during generation, blocking UI
• frontend/src/components/variants/Variants.tsx: Only shows variants when generation is complete

Current Flow

User Request → Generate All Variants → Wait for All → Close WS → Show Results → Allow Interaction

Proposed Non-Blocking System

New Flow

User Request → Start Generation → Show First Complete → User Can Interact → Cancel Others if Needed

Key Changes Needed

1. Backend Changes

WebSocket Protocol Enhancement

• Add new message type: "variantComplete" to signal individual variant completion
• Keep WebSocket open after first variant completes
• Add ability to cancel specific variants mid-generation
• Track variant states: pending, generating, complete, failed, cancelled

Generation Logic

# Instead of:
completions = await asyncio.gather(*tasks, return_exceptions=True)

# Use:
async def process_variants():
    for index, task in enumerate(tasks):
        try:
            completion = await task
            await send_message("variantComplete", index)
            # Allow frontend to interact immediately
        except Exception as e:
            await send_message("variantFailed", index)

2. Frontend Changes

State Management

• Add variant-level state tracking in project-store.ts:
  typescriptCopy

  interface VariantState {
    code: string;
    status: 'pending' | 'generating' | 'complete' | 'failed' | 'cancelled';
    generationTime?: number;
  }
  

UI Updates

• Show variant options as soon as first one completes
• Display loading states for incomplete variants
• Enable "Update" button when at least one variant is ready
• Add visual indicators for variant states

WebSocket Client

• Handle new variantComplete message type
• Don't wait for WebSocket close to enable interactions
• Track which variants are still generating

3. User Experience Improvements

Progressive Loading

• Show first variant immediately when ready
• Display skeleton/loading state for pending variants
• Allow switching between completed variants while others generate

Update Flow

• When user starts update with incomplete variants:
  • Cancel remaining variant generations
  • Start new generation with 2 variants
  • Clear previous incomplete variants

Visual Feedback

• Loading spinner on generating variants
• Success checkmark on completed variants
• Subtle animation when variant completes
• Time elapsed indicator

Implementation Steps

1. Phase 1: Backend Protocol (2-3 days)

   • Modify WebSocket message protocol
   • Implement per-variant completion tracking
   • Add cancellation mechanism

2. Phase 2: Frontend State (2-3 days)

   • Update Zustand store for variant states
   • Modify WebSocket client handling
   • Update commit structure

3. Phase 3: UI Components (2-3 days)

   • Update Variants.tsx for progressive display
   • Add loading states and animations
   • Update Sidebar.tsx for immediate interactions

4. Phase 4: Testing & Polish (2 days)

   • Handle edge cases (all variants fail, etc.)
   • Performance optimization
   • User testing

Benefits

1. Faster Time to First Interaction: Users can work with the first variant immediately
2. Better User Experience: No more waiting for slow models when fast ones are ready
3. Increased Efficiency: Users can evaluate and iterate faster
4. Flexibility: Users can cancel unwanted generations mid-flight

Risks & Mitigation

1. Complexity: More state to manage

   • Mitigation: Careful state design, comprehensive testing

2. Race Conditions: User updates while variants generating

   • Mitigation: Clear cancellation logic, queue management

3. UI Confusion: Users might not understand partial results

   • Mitigation: Clear visual indicators, tooltips

Success Metrics

• Time to first interaction reduced by ~50%
• User satisfaction with generation speed
• Reduced abandonment during generation
• Increased number of iterations per session