User Onboarding Process

This document describes the complete user onboarding flow for the do.dev platform, from waitlist signup to full access.

Overview

The onboarding process uses a role-based system to control user access and progression:

1. Waitlist → User signs up and waits for approval
2. Waitlist-Approved → Admin approves, user can access onboarding
3. User → Onboarding complete, full access granted

Role Definitions

waitlist (Default Role)

• Automatically assigned to all new signups
• No access to the application
• Can only view waitlist status page
• Waiting for admin approval

waitlist-approved

• Assigned by admin when approving waitlist application
• Grants access to onboarding flow only
• Cannot access main application features
• Temporary role during onboarding

user

• Full access to application features
• Assigned after completing onboarding
• Permanent role for active users

Technical Flow

1. User Registration

// auth.ts - afterUserCreatedOrUpdated callback
- New user signs up via email/Google/GitHub
- Automatically assigned "waitlist" role
- Generates unique IDs:
  - userId: usr_[UUID-v7]
  - custId: cus_[unique-id]

2. Waitlist Submission

// waitlist.ts - submitWaitlistInfo
- User submits additional info (GitHub, X username, message)
- Creates waitlistSubmission record with status: "pending"
- User remains in "waitlist" role

3. Admin Approval

// waitlist.ts - approveWaitlistUser
- Admin reviews submission
- On approval:
  - Remove "waitlist" role
  - Add "waitlist-approved" role
  - Update submission status to "approved"
  - Do NOT create organization yet

4. Onboarding Access

// onboarding/layout.tsx
- Checks for "waitlist-approved" role
- Redirects to /waitlist if not approved
- Redirects to /dashboard if already completed ("user" role)

5. Onboarding Steps

Step 1: Welcome Screen

• Displays congratulations message
• Explains next steps
• No data collection

Step 2: Organization Setup

// organizations.ts - createPersonalOrganization or create (team)
- User chooses workspace type:
  - Personal (single user, hidden)
  - Team (multi-user, visible)
- Creates organization with org_[UUID-v7]
- User becomes "owner" of organization

Step 3: Profile Setup

// users.ts - updateUserProfile
- User enters display name
- Optional bio and avatar
- Creates/updates userProfile record

Step 4: Team Invites (Team workspaces only)

// organizations.ts - inviteUserToOrganization
- Owner/admin can invite team members
- Sends invitations via email
- Optional step, can be skipped

6. Onboarding Completion

// users.ts - completeOnboarding
- Validates requirements:
  - Must have organization
  - Must have profile
- Role transition:
  - Remove "waitlist-approved"
  - Add "user"
- Redirects to /dashboard

User Experience Flow

graph TD
    A[Sign Up] --> B[Waitlist Page]
    B --> C{Admin Approval?}
    C -->|No| B
    C -->|Yes| D[Welcome Screen]
    D --> E[Choose Workspace Type]
    E --> F{Personal or Team?}
    F -->|Personal| G[Profile Setup]
    F -->|Team| H[Team Setup]
    H --> G
    G --> I{Team Workspace?}
    I -->|Yes| J[Invite Members]
    I -->|No| K[Complete Onboarding]
    J --> K
    K --> L[Dashboard Access]

Implementation Details

Frontend Routes

• /waitlist - Waitlist status and submission form
• /onboarding - Welcome screen (requires "waitlist-approved")
• /onboarding/organization - Workspace setup
• /onboarding/profile - Profile creation
• /onboarding/invite - Team member invites
• /dashboard - Main app (requires "user" role)

Key Functions

• checkOnboardingStatus() - Determines user's onboarding state
• completeOnboarding() - Transitions from "waitlist-approved" to "user"
• createPersonalOrganization() - Creates single-user workspace
• updateUserProfile() - Saves user profile information

Security Considerations

• Role checks at every step prevent unauthorized access
• Organization creation happens during onboarding, not at approval
• Profile completion is tracked but can be minimal
• Role transitions are atomic and validated

Error Handling

Common Scenarios

1. User tries to access app without approval

   • Redirected to waitlist page
   • Shows current waitlist position

2. User tries to skip onboarding

   • Layout component enforces flow
   • Cannot access dashboard without "user" role

3. Onboarding fails midway

   • User remains in "waitlist-approved" state
   • Can retry onboarding steps
   • Admin can manually intervene if needed

Admin Tools

Monitoring

• View waitlist submissions by status
• Track users in each role state
• Monitor onboarding completion rates

Manual Interventions

• Approve/reject waitlist applications
• Reset user to "waitlist-approved" if needed
• Manually complete onboarding if stuck

Future Enhancements

1. Automated Approval

   • Domain-based auto-approval
   • Invitation codes
   • Referral system

2. Enhanced Onboarding

   • Product tour
   • Sample data setup
   • Integration connections

3. Team Features

   • Bulk invitations
   • SAML/SSO support
   • Advanced permissions