Consolidated Onboarding & Legacy User Migration (LUM) Process

**AI Analysis** (by Claude)

# Root Cause Analysis

This issue requires building a comprehensive onboarding and legacy user migration system that consolidates multiple user flows. The current system appears to have fragmented onboarding experiences and lacks proper legacy user identification and migration features. The screenshot shows a basic profile completion form that needs to be enhanced with legacy user awareness and migration capabilities.

Key gaps identified:

- No unified onboarding flow across different user entry points

- Missing legacy user identification and badge system

- No consolidated migration dashboard with email campaign features

- Lack of legacy join date preservation and display

# Affected Files

**Core Onboarding Components:**

- `/app/onboarding/` - Main onboarding flow directory

- `/components/onboarding/CompleteProfile.tsx` - Profile completion component (shown in screenshot)

- `/components/onboarding/UserQuestionnaire.tsx` - User questionnaire component

- `/components/auth/InviteFlow.tsx` - User invite handling

**Legacy Migration System:**

- `/app/legacy/migration-status/page.tsx` - Migration dashboard

- `/app/legacy/overdue/page.tsx` - Overdue campaign features

- `/app/username/settings/migration/page.tsx` - Existing migration process

- `/lib/legacy-salon-api.ts` - Legacy API integration

**User Profile & Badge System:**

- `/components/user/UserProfile.tsx` - User profile display

- `/components/badges/LegacyUserBadge.tsx` - Legacy user badge (to be created)

- `/lib/user-migration.ts` - Migration utilities

**Database Schema:**

- `/lib/supabase/types.ts` - Type definitions

- Migration files for user_profiles table updates

# Resolution Approach

## Phase 1: Enhanced Profile Completion (1-2 days)

1. **Update CompleteProfile component:**

- Add legacy user detection logic

- Display appropriate messaging based on user type

- Include "member since" date for legacy users

- Add legacy username claiming flow

2. **Implement user type detection:**

```typescript

// In CompleteProfile.tsx

const isLegacyUser = await checkLegacyUserStatus(email)

const legacyJoinDate = await getLegacyJoinDate(email)

```

## Phase 2: Consolidated Migration Dashboard (2-3 days)

1. **Enhance migration-status page:**

- Integrate email campaign features from overdue page

- Add legacy user identification table

- Implement bulk migration actions

- Add migration progress tracking

2. **Create unified migration API:**

```typescript

// /lib/api/migration.ts

export const migrationService = {

identifyLegacyUsers,

claimLegacyAccount,

sendMigrationReminders,

trackMigrationProgress

}

```

## Phase 3: Legacy User Badge & Profile Enhancement (1-2 days)

1. **Create legacy user badge system:**

- Design and implement LegacyUserBadge component

- Add "Member since [date]" display to profiles

- Update user profile schema to include legacy_join_date

2. **Update user profiles to show legacy status:**

```sql

ALTER TABLE user_profiles

ADD COLUMN legacy_join_date DATE,

ADD COLUMN is_legacy_user BOOLEAN DEFAULT false,

ADD COLUMN legacy_username VARCHAR(50);

```

## Phase 4: Unified Onboarding Flow (2-3 days)

1. **Create consolidated onboarding router:**

- Route users based on invitation type (admin, user, legacy)

- Implement conditional step display

- Add progress tracking across all flows

2. **Integrate with existing migration process:**

- Sync with username/settings/migration functionality

- Ensure data consistency between systems

- Add migration status to user session state

## Phase 5: Email Campaign Integration (1-2 days)

1. **Move overdue features to migration dashboard:**

- Extract email campaign components

- Integrate with main migration status view

- Add campaign scheduling and tracking

2. **Implement legacy user communication:**

- Username claiming reminders

- Migration deadline notifications

- Welcome back messaging for claimed accounts

# Complexity Estimate

**Complex** - This involves multiple interconnected systems and requires:

- Database schema changes for legacy user tracking

- Integration of existing migration APIs with new onboarding flow

- Complex conditional logic for different user types and states

- Email campaign system integration

- Multi-phase rollout to avoid breaking existing functionality

- Careful handling of legacy data migration and preservation

The complexity stems from needing to maintain backward compatibility while building new unified flows, plus the requirement to integrate multiple existing systems (legacy API, current migration, onboarding, email campaigns).

# Dependencies

## Prerequisites:

1. **Legacy API Access** - Ensure stable connection to legacy salon API

2. **Database Migration Strategy** - Plan for zero-downtime schema updates

3. **Email Service Setup** - Verify email campaign infrastructure is ready

4. **User Session Management** - May need to update Zustand stores for migration state

## Potential Blockers:

1. **Legacy Data Quality** - Need to audit legacy user data completeness

2. **Username Conflicts** - Strategy for handling duplicate usernames between systems

3. **Email Deliverability** - Ensure migration emails don't get flagged as spam

4. **Performance** - Large legacy user base may require batch processing

## Technical Decisions Needed:

1. Migration timeline and rollout strategy

2. Fallback handling for failed legacy account claims

3. Data retention policy for unclaimed legacy accounts

4. Testing strategy for migration flows without affecting production data