Authentication Documentation

Overview

This directory contains all authentication-related documentation for the customers.dev project. The project uses Clerk's satellite domain architecture, authenticating through auth.do.dev for centralized authentication.

🔐 Core Authentication System

Current Architecture

• CLERK_SATELLITE_IMPLEMENTATION.md - Complete satellite mode setup guide for customers.dev
• AUTHENTICATION_ARCHITECTURE.md - Overall authentication system design

🚀 Setup & Configuration

Quick Start

1. CLERK_SATELLITE_IMPLEMENTATION.md - Complete satellite domain setup
2. 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

📋 Status

The authentication system uses Clerk in satellite mode, authenticating through do.dev's central auth system. This is currently working and should not be modified without careful consideration.

🔗 Related Documentation

Development

• TypeScript Best Practices
• Roles Documentation

Quick Reference

Environment Variables

# Clerk Configuration (Satellite Mode)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_***
CLERK_SECRET_KEY=sk_test_***

# Satellite configuration
NEXT_PUBLIC_CLERK_IS_SATELLITE=true
NEXT_PUBLIC_CLERK_DOMAIN=localhost:3005  # Development - primary auth domain
# NEXT_PUBLIC_CLERK_DOMAIN=auth.do.dev   # Production - primary auth domain

NEXT_PUBLIC_CLERK_SIGN_IN_URL=http://localhost:3005/sign-in  # Development
# NEXT_PUBLIC_CLERK_SIGN_IN_URL=https://auth.do.dev/sign-in  # Production

NEXT_PUBLIC_CLERK_SIGN_UP_URL=http://localhost:3005/sign-up  # Development
# NEXT_PUBLIC_CLERK_SIGN_UP_URL=https://auth.do.dev/sign-up  # Production

CLERK_SATELLITE_URL=http://localhost:3015  # Development
# CLERK_SATELLITE_URL=https://customers.dev  # Production

# Redirect URLs after auth
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=http://localhost:3015/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=http://localhost:3015/dashboard

# Convex Configuration (single project)
NEXT_PUBLIC_CONVEX_URL=https://impartial-panda-219.convex.cloud
CONVEX_DEPLOY_KEY=dev:impartial-panda-219|***

Key Concepts

• Satellite Mode: customers.dev authenticates through central auth.do.dev
• Shared Authentication: Uses do.dev's Clerk instance for centralized user management
• Single Convex Project: All data stored in one Convex project (no multi-project setup)
• RBAC: Role-based access control implemented via Convex (see ROLES.md)

Important Notes

⚠️ DO NOT BREAK THE SATELLITE AUTH - The satellite authentication to do.dev is already working. Any changes to the authentication system must preserve this functionality.