# Email-Optional Authentication Implementation

## Overview

This document outlines the changes needed to make email optional for authentication while maintaining notification functionality.

## Changes Required

### 1. Clerk Configuration (Dashboard)

**In Clerk Dashboard** (https://dashboard.clerk.com):

1. Navigate to **User & Authentication** → **Email, Phone, Username**
2. Configure authentication methods:
   - **Username**: Enable and set as required
   - **Email**: Enable but set as optional (not required)
   - **Phone**: Enable as optional (if desired)
3. Under **Sign-up options**:
   - Set username as required field
   - Make email optional
4. Under **Sign-in options**:
   - Enable "Username" as sign-in identifier
   - Keep email as optional sign-in method

### 2. Database Schema Changes

**File**: `server/prisma/schema.prisma`

Make email field optional:
```prisma
model User {
  email              String?             @unique(map: "email") @db.VarChar(255)
  // ... rest of fields
}
```

**Migration needed**: Yes - run `npx prisma migrate dev --name make-email-optional`

### 3. Backend Service Updates

#### A. User Service (`server/src/services/userService.ts`)

Update user creation to handle missing email:
```typescript
email: clerkUser.emailAddresses[0]?.emailAddress || null,
```

#### B. Notification Service (`server/src/services/notificationService.ts`)

Update `sendEmailNotifications` to:
1. Skip users without email addresses
2. Log when email is skipped
3. Only send in-app notifications for users without email

#### C. Email Service (`server/src/services/emailService.ts`)

Add validation to check if email exists before sending.

### 4. Frontend Updates

No changes needed - Clerk components will automatically adapt to the new configuration.

### 5. Notification Preference Logic

Users without email addresses:
- `notificationEmail` preference is ignored
- Only `notificationInApp` notifications are sent
- UI should show email field as optional in profile settings
- Display message: "Add an email address to receive email notifications"

## Implementation Steps

1. ✅ Update Clerk Dashboard settings
2. ✅ Update database schema
3. ✅ Run database migration
4. ✅ Update backend services
5. ✅ Test authentication flows
6. ✅ Test notification delivery

## Testing Checklist

- [ ] User can sign up with username only (no email)
- [ ] User can sign in with username
- [ ] User without email receives in-app notifications
- [ ] User without email does NOT receive email notifications (no errors)
- [ ] User can add email later in profile settings
- [ ] After adding email, user receives email notifications
- [ ] Existing users with email continue to work normally

## Rollback Plan

If issues occur:
1. Revert Clerk Dashboard settings (make email required)
2. Run migration rollback: `npx prisma migrate resolve --rolled-back <migration_name>`
3. Revert code changes

## Security Considerations

- Username must be unique and validated
- Consider adding email verification when user adds email later
- Rate limiting on username-based sign-ups
- Monitor for abuse (fake accounts without email)

## User Experience

**For users without email:**
- Clear messaging that email is optional
- Explanation of notification limitations
- Easy way to add email later
- In-app notifications work fully

**For users with email:**
- No changes to existing experience
- All notifications work as before