Authentication Documentation

Overview

This directory contains all authentication-related documentation for the do.dev stack. The project uses Clerk's satellite domain architecture for centralized authentication across all applications.

🎯 Quick Start for Satellite Domains

New to Satellite Domains?

• SATELLITE_QUICK_START.md - 5-minute setup guide for satellite domains
• CLERK_SATELLITE_DOMAINS.md - Comprehensive implementation guide
• CLERK_ENV_VARIABLES.md - Complete environment variables reference

🔐 Core Authentication System

Current Architecture

• CLERK_SATELLITE_DOMAINS.md - Primary satellite domains guide
• CLERK_AUTHENTICATION_ARCHITECTURE.md - Complete Clerk integration architecture
• AUTHENTICATION_ARCHITECTURE.md - Overall authentication system design
• CONVEX_MULTI_PROJECT_ARCHITECTURE.md - Auth project in multi-Convex setup

Implementation Guides

• CLERK_SATELLITE_IMPLEMENTATION.md - Detailed satellite mode setup
• CLERK_CONVEX_SYNC_DESIGN.md - User synchronization between Clerk and Convex
• APP_SPECIFIC_AUTH.md - Multi-tenant authentication
• AUTH_SERVICE_IMPLEMENTATION.md - Auth service implementation details

🚀 Setup & Configuration

Quick Start

1. SATELLITE_QUICK_START.md - 5-minute satellite setup
2. CLERK_ENV_VARIABLES.md - Environment variables reference
3. AUTH_ENVIRONMENT_SETUP.md - Detailed environment setup
4. CLERK_SATELLITE_DOMAIN_SETUP.md - Domain configuration
5. EMAIL_SETUP.md - Email authentication setup

OAuth Providers

• GOOGLE_AUTH_SETUP.md - Complete Google OAuth guide
• GOOGLE_AUTH_QUICK_SETUP.md - Quick setup for Google OAuth
• AUTH_OAUTH_SETUP.md - General OAuth configuration

Testing

• AUTH_TESTING_GUIDE.md - Testing authentication flows
• PLAYWRIGHT_GOOGLE_AUTH_SETUP.md - E2E testing with OAuth

🛠️ Troubleshooting & Maintenance

Common Issues

• CLERK_URL_MASKING_STRATEGIES.md - Hiding Clerk parameters

Maintenance

• CLEAR_AUTH_DATA.md - Clearing authentication data

📋 Status

The authentication system migration to Clerk is complete. For historical migration documentation, see the archive.

🔗 Related Documentation

Architecture

• Multi-Project Convex Architecture
• RBAC Implementation

Development

• TypeScript Best Practices
• Roles Documentation

Quick Reference

Environment Variables

# Clerk Configuration
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_CLERK_IS_SATELLITE=true

# Auth Convex Project
NEXT_PUBLIC_CONVEX_DEPLOYMENT_AUTH=https://dependable-pika-747.convex.cloud

Key Concepts

• Satellite Mode: Apps authenticate through central auth.do.dev
• User Sync: Clerk users synchronized to Convex with usr_ prefixed IDs
• Multi-App Support: Single user can access multiple apps with different roles
• RBAC: Role-based access control per application