ocean-cleanup/EMAIL_OPTIONAL_IMPLEMENTATION.md

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:

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:

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