Clerk Waitlist Implementation

This document describes the hybrid implementation of Clerk's official waitlist component integrated with our existing custom waitlist system.

Overview

We've implemented a hybrid approach that combines Clerk's polished waitlist UI components with our existing custom role-based system. This provides the best user experience while preserving all our existing functionality and user data.

Architecture

Hybrid System Design

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   New Users     │    │  Existing Users  │    │ OAuth Users     │
│                 │    │                  │    │                 │
│ Clerk Waitlist  │    │ Custom Waitlist  │    │ Direct Access   │
│       ↓         │    │       ↓          │    │       ↓         │
│ Clerk Approval  │    │ Admin Approval   │    │ "user" role     │
│       ↓         │    │       ↓          │    │                 │
│"waitlist-       │    │"waitlist-        │    │                 │
│ approved" role  │    │ approved" role   │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                ↓
                        ┌──────────────────┐
                        │   Onboarding     │
                        │       ↓          │
                        │   "user" role    │
                        └──────────────────┘

User Journey Flows

New Users (Clerk Waitlist)

Visit Homepage → See Clerk <Waitlist /> component
Submit Email → Joins Clerk's waitlist system
Admin Approval → Admin approves via Clerk Dashboard
Webhook Triggers → user.updated event detected
Role Assignment → System grants "waitlist-approved" role
Access Granted → User can sign in and complete onboarding

Existing Users (Custom System)

Existing Flow → Continue using custom waitlist system
Admin Approval → Via existing admin dashboard
Role Assignment → "waitlist-approved" role granted
Access Granted → User proceeds to onboarding

Implementation Details

1. ClerkProvider Configuration

// apps/dodev/components/app-providers.tsx
<ClerkProvider
  publishableKey={process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY}
  signInUrl="/sign-in"
  signUpUrl="/sign-up"
  waitlistUrl="/"  // 👈 Points to homepage for waitlist
  allowedRedirectOrigins={[...]}
>

2. Waitlist Component Integration

Homepage Integration

// apps/dodev/components/hero-section.tsx
{!isAuthenticated && (
  <ClerkWaitlistSection 
    title="Get Early Access"
    description="Join our waitlist to be the first to experience our AI-powered development platform."
    showDecorative={false}
  />
)}

Dedicated Waitlist Page

Route: /waitlist
Features:
- Unauthenticated: Shows Clerk waitlist signup
- Waitlisted: Shows status with progress indicators
- Approved: Welcome message with dashboard access

3. Webhook Integration

The existing Clerk webhook (/api/webhooks/clerk/route.ts) has been enhanced to detect and handle Clerk waitlist approvals:

if (eventType === "user.updated") {
  // Detect Clerk waitlist approval
  const hasBasicAccess = evt.data.email_addresses?.length > 0
  const hasNoCustomRoles = !currentRoles.includes("waitlist-approved") && 
                           !currentRoles.includes("user") &&
                           currentRoles.length <= 1
  
  const wasApprovedFromClerkWaitlist = hasBasicAccess && hasNoCustomRoles && 
    currentRoles.includes("waitlist")
  
  if (wasApprovedFromClerkWaitlist) {
    // Grant waitlist-approved role (matches existing flow)
    const updatedRoles = [...currentRoles.filter(role => role !== "waitlist"), "waitlist-approved"]
    
    await client.users.updateUser(id, {
      publicMetadata: {
        ...public_metadata,
        roles: updatedRoles,
        waitlistApprovedAt: Date.now(),
        approvedBy: "clerk-waitlist",
        source: "clerk-waitlist",
      },
    })
  }
}

User Management

Clerk Dashboard Management

Navigate to: Clerk Dashboard → Waitlist
Approve Users: Click menu (⋯) → "Invite" to approve access
Deny Users: Click menu (⋯) → "Deny" to reject access

Existing Admin Dashboard

Custom waitlist users continue to be managed via existing admin interface
All functionality preserved: Bulk approval, rejection reasons, analytics

Role System Integration

Role Hierarchy (Unchanged)

"waitlist" → "waitlist-approved" → "user" → "staff" → "admin" → "super_admin"

Role Sources

"clerk-waitlist": Users approved via Clerk Dashboard
"admin": Users approved via custom admin dashboard
"organic": Default source for new signups

Configuration Requirements

1. Clerk Dashboard Setup

✅ Waitlist Mode Enabled: User Authentication → Restrictions → Waitlist
✅ Webhook Configured: Points to /api/webhooks/clerk
✅ Events Subscribed: user.created, user.updated, user.deleted

2. Environment Variables

# Required for Clerk integration
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_SECRET_KEY=sk_live_...
CLERK_WEBHOOK_SECRET=whsec_...

# Required for Convex sync
NEXT_PUBLIC_CONVEX_URL=https://...