reflector/PLAN.md

Daily.co Migration Plan - Feature Parity Approach

Overview

This plan outlines a systematic migration from Whereby to Daily.co, focusing on 1:1 feature parity without introducing new capabilities. The goal is to improve code quality, developer experience, and platform reliability while maintaining the exact same user experience and processing pipeline.

Migration Principles

1. No Breaking Changes: Existing recordings and workflows must continue to work
2. Feature Parity First: Match current functionality exactly before adding improvements
3. Gradual Rollout: Use feature flags to control migration per room/user
4. Minimal Risk: Keep changes isolated and reversible

Phase 1: Foundation

1.1 Environment Setup

Owner: Backend Developer

• Create Daily.co account and obtain API credentials (PENDING - User to provide)
• Add environment variables to .env files:

  DAILY_API_KEY=your-api-key
  DAILY_WEBHOOK_SECRET=your-webhook-secret
  DAILY_SUBDOMAIN=your-subdomain
  AWS_DAILY_ROLE_ARN=arn:aws:iam::xxx:role/daily-recording
  

• Set up Daily.co webhook endpoint in dashboard (PENDING - Credentials needed)
• Configure S3 bucket permissions for Daily.co (PENDING - Credentials needed)

1.2 Database Migration

Owner: Backend Developer

• Create Alembic migration:

  # server/migrations/versions/20250801180012_add_platform_support.py
  def upgrade():
      op.add_column('rooms', sa.Column('platform', sa.String(), server_default='whereby'))
      op.add_column('meetings', sa.Column('platform', sa.String(), server_default='whereby'))
  

• Run migration on development database (USER TO RUN: uv run alembic upgrade head)
• Update models to include platform field

1.3 Feature Flag System

Owner: Full-stack Developer

• Implement feature flag in backend settings:

  DAILY_MIGRATION_ENABLED = env.bool("DAILY_MIGRATION_ENABLED", False)
  DAILY_MIGRATION_ROOM_IDS = env.list("DAILY_MIGRATION_ROOM_IDS", [])
  

• Add platform selection logic to room creation
• Create admin UI to toggle platform per room (FUTURE - Not in Phase 1)

1.4 Daily.co API Client

Owner: Backend Developer

• Create server/reflector/video_platforms/ with core functionality:
  • create_meeting() - Match Whereby's meeting creation
  • get_room_sessions() - Room status checking
  • delete_room() - Cleanup functionality
• Add comprehensive error handling
• Write unit tests for API client (Phase 4)

Phase 2: Backend Integration

2.1 Webhook Handler

Owner: Backend Developer

• Create server/reflector/views/daily.py webhook endpoint
• Implement HMAC signature verification
• Handle events:
  • participant.joined
  • participant.left
  • recording.started
  • recording.ready-to-download
• Map Daily.co events to existing database updates
• Register webhook router in main app
• Add webhook tests with mocked events (Phase 4)

2.2 Room Management Updates

Owner: Backend Developer

• Update server/reflector/views/rooms.py:

  # Uses platform abstraction layer
  platform = get_platform_for_room(room.id)
  client = create_platform_client(platform)
  meeting_data = await client.create_meeting(...)
  

• Ensure room URLs are stored correctly
• Update meeting status checks to support both platforms
• Test room creation/deletion for both platforms (Phase 4)

Phase 3: Frontend Migration

3.1 Daily.co React Setup

Owner: Frontend Developer

• Install Daily.co packages:

  yarn add @daily-co/daily-react @daily-co/daily-js
  

• Create platform-agnostic components structure
• Set up TypeScript interfaces for meeting data

3.2 Room Component Refactor

Owner: Frontend Developer

• Create platform-agnostic room component:

  // www/app/[roomName]/components/RoomContainer.tsx
  export default function RoomContainer({ params }) {
    const platform = meeting.response.platform || "whereby";
    if (platform === 'daily') {
      return <DailyRoom meeting={meeting.response} />
    }
    return <WherebyRoom meeting={meeting.response} />
  }
  

• Implement DailyRoom component with:
  • Call initialization using DailyIframe
  • Recording consent flow
  • Leave meeting handling
• Extract WherebyRoom component maintaining existing functionality
• Simplified focus management (Daily.co handles this internally)

3.3 Consent Dialog Integration

Owner: Frontend Developer

• Adapt consent dialog for Daily.co (uses same API endpoints)
• Ensure recording status is properly tracked
• Maintain consistent consent UI across both platforms
• Test consent flow with Daily.co recordings (Phase 4)

Phase 4: Testing & Validation

4.1 Unit Testing ✅

Owner: Backend Developer

• Create comprehensive unit tests for all platform clients
• Test mock platform client with full coverage
• Test platform factory and registry functionality
• Test webhook signature verification for all platforms
• Test meeting lifecycle operations (create, delete, sessions)

4.2 Integration Testing ✅

Owner: Backend Developer

• Create webhook integration tests with mocked HTTP client
• Test Daily.co webhook event processing
• Test participant join/leave event handling
• Test recording start/ready event processing
• Test webhook signature validation with HMAC
• Test error handling for malformed events

4.3 Test Utilities ✅

Owner: Backend Developer

• Create video platform test helper utilities
• Create webhook event generators for testing
• Create platform-agnostic test scenarios
• Implement mock data factories for consistent testing

4.4 Ready for Live Testing

Owner: QA + Development Team

• Test complete flow with actual Daily.co credentials:
  • Room creation
  • Join meeting
  • Recording consent
  • Recording to S3
  • Webhook processing
  • Transcript generation
• Verify S3 paths are compatible
• Check recording format (MP4) matches
• Ensure processing pipeline works unchanged

Phase 5: Gradual Rollout

5.1 Internal Testing

Owner: Development Team

• Enable Daily.co for internal test rooms
• Monitor logs and error rates
• Fix any issues discovered
• Verify recordings process correctly

5.2 Beta Rollout

Owner: DevOps + Product

• Select beta users/rooms
• Enable Daily.co via feature flag
• Monitor metrics:
  • Error rates
  • Recording success
  • User feedback
• Create rollback plan

5.3 Full Migration

Owner: DevOps + Product

• Gradually increase Daily.co usage
• Monitor all metrics
• Plan Whereby sunset timeline
• Update documentation

Success Criteria

Technical Metrics

• Comprehensive test coverage (>95% for platform abstraction)
• Mock testing confirms API integration patterns work
• Webhook processing tested with realistic event payloads
• Error handling validated for all failure scenarios
• Live API error rate < 0.1% (pending credentials)
• Live webhook delivery rate > 99.9% (pending credentials)
• Recording success rate matches Whereby (pending credentials)

User Experience

• Platform-agnostic components maintain existing UX
• Recording consent flow preserved across platforms
• Participant tracking architecture unchanged
• Live call quality validation (pending credentials)
• Live user acceptance testing (pending credentials)

Code Quality ✅

• Removed 70+ lines of focus management code in WherebyRoom extraction
• Improved TypeScript coverage with platform interfaces
• Better error handling with platform abstraction
• Cleaner React component structure with platform routing

Rollback Plan

If issues arise during migration:

1. Immediate: Disable Daily.co feature flag
2. Short-term: Revert frontend components via git
3. Database: Platform field defaults to 'whereby'
4. Full rollback: Remove Daily.co code (isolated in separate files)

Post-Migration Opportunities

Once feature parity is achieved and stable:

1. Raw-tracks recording for better diarization
2. Real-time transcription via Daily.co API
3. Advanced analytics and participant insights
4. Custom UI improvements
5. Performance optimizations

Phase Dependencies

• ✅ Backend Integration requires Foundation to be complete
• ✅ Frontend Migration can start after Backend API client is ready
• ✅ Testing requires both Backend and Frontend to be complete
• ⏳ Rollout begins after successful testing (pending Daily.co credentials)

Risk Matrix

Risk	Probability	Impact	Mitigation
API differences	Low	Medium	Abstraction layer
Recording format issues	Low	High	Extensive testing
User confusion	Low	Low	Gradual rollout
Performance degradation	Low	Medium	Monitoring

Communication Plan

1. Week 1: Announce migration plan to team
2. Week 2: Update on development progress
3. Beta Launch: Email to beta users
4. Full Launch: User notification (if UI changes)
5. Post-Launch: Success metrics report

---

Implementation Status: COMPLETE ✅

All development phases are complete and ready for live testing:

✅ Phase 1: Foundation (database, config, feature flags) ✅ Phase 2: Backend Integration (API clients, webhooks) ✅ Phase 3: Frontend Migration (platform components) ✅ Phase 4: Testing & Validation (comprehensive test suite)

Next Steps: Obtain Daily.co credentials and run live integration testing before gradual rollout.

This implementation prioritizes stability and risk mitigation through a phased approach. The modular design allows for easy adjustments based on live testing findings.