⚠️ OUTDATED NOTICE ⚠️

This document is outdated as of July 2025.

Authentication has been consolidated from auth.do.dev into the main do.dev site. The satellite domain pattern described here is no longer in use. Please refer to the current authentication implementation in the dodev app.

Clerk Authentication Architecture for do.dev Stack

Executive Summary

This document outlines the comprehensive plan to migrate from Convex authentication to Clerk.dev's unified authentication system using satellite domains. The new architecture centralizes authentication on auth.do.dev while enabling seamless single sign-on across all do.dev properties.

Architecture Overview

Core Design Principles

Single Authentication Domain: auth.do.dev serves as the central authentication hub
Satellite Domain Pattern: All other applications authenticate through the primary domain
Multi-Tenant Support: Maintains app-specific user data and profiles
Role-Based Access Control: Preserves existing permission system
Zero Data Loss: Complete migration of existing user data

Domain Structure

PRIMARY DOMAIN: auth.do.dev
├── Authentication UI (sign-in, sign-up, profile)
├── OAuth provider management
├── User onboarding flows
├── Admin interfaces
└── Organization management

SATELLITE DOMAINS:
├── do.dev (main application)
├── biturl.do.dev (URL shortener)
├── contacts.do.dev (contact management)
├── sms.do.dev (SMS service)
├── [13+ additional landing pages]
└── [future applications]

Technical Implementation

Authentication Flow

sequenceDiagram
    participant U as User
    participant S as Satellite Domain
    participant A as auth.do.dev
    participant C as Clerk

    U->>S: Visit satellite domain
    S->>C: Check session
    C-->>S: No valid session
    S->>A: Redirect to auth.do.dev/sign-in
    U->>A: Complete authentication
    A->>C: Create session
    C->>A: Session token
    A->>S: Redirect back with session
    S->>C: Validate session
    C-->>S: Valid session + user data
    S->>U: Display authenticated content

User Data Model

interface DoDevUser {
  // Native Clerk fields
  id: string
  email: string
  firstName?: string
  lastName?: string
  imageUrl?: string
  
  // Custom metadata for multi-tenancy
  publicMetadata: {
    appId: "dodev" | "promptnow" | "groktalk" | "nextjs-base" | "customers"
    custId: string // Customer ID for billing
    userId: string // Public user ID (usr_xxx)
    roles: string[] // ["user", "staff", "admin", "super_admin"]
    waitlistPosition?: number
    verified: boolean
    lastLoginAt: number
    authProvider: "email" | "google" | "github"
  }
  
  privateMetadata: {
    organizationId?: string
    billing?: BillingData
    preferences?: UserPreferences
  }
}

Role-Based Access Control

// Hierarchical role system
const ROLE_HIERARCHY = {
  "super_admin": 5,
  "admin": 4,
  "staff": 3,
  "user": 2,
  "waitlist": 1
}

// Unified auth hook for all applications
function useDoDevAuth() {
  const { user } = useUser() // Clerk hook
  
  const appId = user?.publicMetadata?.appId
  const roles = user?.publicMetadata?.roles || []
  
  return {
    user,
    isAuthenticated: !!user,
    appId,
    roles,
    hasRole: (role: string) => roles.includes(role),
    isAdmin: roles.some(r => ["admin", "super_admin"].includes(r)),
    isStaff: roles.some(r => ["staff", "admin", "super_admin"].includes(r)),
    canAccessApp: (targetAppId: string) => 
      appId === targetAppId || roles.includes("super_admin")
  }
}

Environment Configuration

Primary Domain (auth.do.dev)

# Clerk configuration
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_xxx
CLERK_SECRET_KEY=sk_live_xxx
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

# Domain configuration
NEXT_PUBLIC_CLERK_DOMAIN=auth.do.dev

Satellite Domains (all others)

# Same Clerk keys
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_xxx
CLERK_SECRET_KEY=sk_live_xxx

# Satellite configuration
NEXT_PUBLIC_CLERK_IS_SATELLITE=true
NEXT_PUBLIC_CLERK_DOMAIN=do.dev
NEXT_PUBLIC_CLERK_SIGN_IN_URL=https://auth.do.dev/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=https://auth.do.dev/sign-up

Migration Strategy

Phase-Based Approach (8 Weeks)

Phase 1: Infrastructure Setup (Week 1)

Set up Clerk production account
Configure auth.do.dev as primary domain
Set up development environments
Configure OAuth providers
Create DNS infrastructure

Phase 2: Primary Domain Development (Week 2)

Build auth.do.dev Next.js application
Implement Clerk authentication components
Create custom onboarding flows
Build admin interfaces
Implement user management features

Phase 3: Data Migration (Week 3)

Export all users from Convex
Transform data to Clerk format
Batch import to Clerk with validation
Verify data integrity
Test sample user accounts

Phase 4: Satellite Integration (Week 4)

Convert do.dev to satellite
Create shared authentication package
Replace Convex auth hooks
Update role checking logic
Test multi-domain sessions

Phase 5: Landing Pages Migration (Week 5)

Convert 15+ landing page apps
Standardize authentication patterns
Batch test satellite configurations
Validate session sharing

Phase 6: Production Deployment (Week 6)

Deploy to production
Execute data migration
Monitor authentication flows
Complete cutover from Convex

Phase 7: Cleanup & Optimization (Week 7)

Remove legacy Convex auth code
Optimize authentication performance
Clean up infrastructure
Update documentation

Phase 8: Validation (Week 8)

Verify migration success
Measure performance improvements
Validate security enhancements
Document lessons learned

Data Migration Details

User Migration Script

async function migrateUsers() {
  // 1. Export all users from Convex
  const convexUsers = await convex.query(api.users.getAllUsers)
  
  // 2. Transform data to Clerk format
  const clerkUsers = convexUsers.map(transformConvexToClerk)
  
  // 3. Batch import to Clerk (respecting rate limits)
  for (const batch of chunk(clerkUsers, 100)) {
    await importBatchToClerk(batch)
    await delay(1000) // Rate limiting
  }
  
  // 4. Validation - verify all users migrated correctly
  await validateMigration(convexUsers, clerkUsers)
}

function transformConvexToClerk(convexUser) {
  return {
    emailAddress: convexUser.email,
    firstName: convexUser.name?.split(' ')[0],
    lastName: convexUser.name?.split(' ').slice(1).join(' '),
    publicMetadata: {
      appId: convexUser.appId,
      custId: convexUser.custId,
      userId: convexUser.userId,
      roles: convexUser.roles || ["waitlist"],
      waitlistPosition: convexUser.waitlistPosition,
      verified: convexUser.verified || false,
      lastLoginAt: convexUser.lastLoginAt || Date.now(),
      authProvider: convexUser.authProvider || "email"
    },
    privateMetadata: {
      organizationId: convexUser.organizationId
    }
  }
}

DNS Configuration

Production Requirements

For each satellite domain, add CNAME record:

clerk.<satellite-domain> → <clerk-provided-endpoint>

Examples:

clerk.do.dev → clerk.domains.clerk.com
clerk.biturl.do.dev → clerk.domains.clerk.com
clerk.contacts.do.dev → clerk.domains.clerk.com

Security Considerations

Enhanced Security Features

Professional Authentication Service: Clerk provides enterprise-grade security
Automatic Security Updates: Security patches managed by Clerk
Advanced Threat Protection: Built-in protection against common attacks
Compliance Features: SOC 2, GDPR, and other compliance standards
Audit Logging: Comprehensive authentication audit trails

Session Management

Secure Token Handling: Clerk manages JWT tokens securely
Automatic Session Refresh: Seamless token refresh without user interruption
Cross-Domain Sessions: Secure session sharing across all domains
Logout Everywhere: Single logout invalidates all domain sessions

Code Organization

Shared Authentication Package

packages/auth/
├── hooks/
│   ├── useDoDevAuth.ts        # Main auth hook
│   ├── useRoleCheck.ts        # Role-based permissions
│   └── useAppAccess.ts        # App-specific access
├── components/
│   ├── AuthGuard.tsx          # Route protection
│   ├── RoleGuard.tsx          # Role-based components
│   └── AppSelector.tsx        # App switching UI
├── middleware/
│   ├── clerkMiddleware.ts     # Satellite config
│   └── authMiddleware.ts      # Custom auth logic
└── types/
    └── auth.types.ts          # Shared type definitions

Testing Strategy

Authentication Flow Testing

Unit Tests: Individual auth components and hooks
Integration Tests: Multi-domain authentication flows
End-to-End Tests: Complete user journeys across apps
Performance Tests: Authentication flow speed and reliability
Security Tests: Session management and access control

Migration Testing

Data Integrity Tests: Verify complete user data migration
Role Preservation Tests: Ensure all permissions work correctly
Organization Tests: Validate organization functionality
Rollback Tests: Verify ability to restore Convex auth if needed

Monitoring & Observability

Key Metrics

Authentication Success Rate: Target 99.9%+
Session Creation Time: Target <2 seconds
Cross-Domain Session Sharing: 100% success rate
User Experience: Reduced authentication friction
Error Rates: Monitor and alert on authentication failures

Alerting

Failed authentication rates above threshold
Session creation failures
Cross-domain authentication issues
OAuth provider failures
User migration validation errors

Benefits & Expected Outcomes

Immediate Benefits

Simplified Development: Single auth pattern across all applications
Enhanced Security: Professional authentication service
Better UX: Consistent authentication experience
Reduced Maintenance: No custom auth code to maintain
Improved Scalability: Easy addition of new applications

Long-term Strategic Advantages

Multi-tenancy: Seamless support for multiple applications
Organization Support: Native B2B organization management
Advanced Features: 2FA, device management, advanced security
Analytics: Better user analytics and insights
Compliance: Built-in security compliance features

Success Metrics

✅ Zero data loss during migration
✅ Preserved role-based access control
✅ Maintained multi-tenant architecture
✅ Single sign-on across all domains
✅ 70%+ reduction in authentication code
✅ Improved security posture
✅ Enhanced user experience

Risk Mitigation

High-Risk Items

User Data Loss
- Mitigation: Full backups, staged migration, validation
Session Disruption
- Mitigation: Low-traffic window, parallel running period
Role/Permission Issues
- Mitigation: Comprehensive testing, admin overrides

Rollback Plan

Restore Convex authentication configuration
Switch DNS back to original infrastructure
Restore user sessions from backup
Investigate and fix migration issues
Plan corrective actions for next attempt

Future Enhancements

Planned Features

Advanced Security: 2FA, device management, risk assessment
Enhanced Analytics: User behavior tracking, authentication insights
B2B Features: Advanced organization management, SSO integrations
Mobile Authentication: Native mobile app authentication
API Authentication: Service-to-service authentication patterns

Scalability Considerations

Support for 100+ satellite domains
Enterprise-grade user management
Advanced role hierarchy and permissions
Multi-region authentication support
High-availability and disaster recovery

Conclusion

The migration to Clerk's satellite domain architecture provides a modern, secure, and scalable authentication foundation for the entire do.dev ecosystem. This approach maintains all existing functionality while improving security, user experience, and developer productivity.

The phased migration plan minimizes risk and ensures zero data loss while providing a clear path to a more maintainable and feature-rich authentication system.

Document Version: 1.0
Last Updated: January 2025
Next Review: Post-Migration Completion

On this page