# User Profile Feature Capsule

## Quick Summary

User profile management system that stores user information (email, display name, notification email) with defaults from Auth0 but allows user edits. Profile is automatically created on first login and persists user preferences.

## API Endpoints

### User Endpoints
- `GET /api/user/profile` - Get current user's profile (creates if not exists)
- `PUT /api/user/profile` - Update user profile (display name, notification email)

## Structure

- **api/** - HTTP endpoints, routes, validators
- **domain/** - Business logic, services, types
- **data/** - Repository, database queries
- **migrations/** - Feature-specific schema

## Profile Data Model

### Fields
- `id` - UUID primary key
- `auth0_sub` - Auth0 user ID (unique, indexed)
- `email` - User email (from Auth0)
- `display_name` - Optional user-defined display name
- `notification_email` - Optional alternate email for notifications
- `created_at` - Profile creation timestamp
- `updated_at` - Last update timestamp (auto-updated)

### Default Values
On first login, profile is created with:
- `email` - From Auth0 user token
- `display_name` - From Auth0 user name (optional)
- Other fields - null/empty

## Dependencies

### Internal
- `core/auth` - Authentication plugin (fastify.authenticate)
- `core/logging` - Structured logging
- `core/config` - Database pool

### External
- None (Auth0 integration via core/auth)

### Database
- Tables: `user_profiles`
- Indexes: `idx_user_profiles_auth0_sub` on `auth0_sub`

## Business Rules

### Profile Creation
- Profile created automatically on first API call after login
- Uses Auth0 token data (sub, email, name) as defaults
- `getOrCreate` pattern ensures idempotent profile access

### Profile Updates
- Users can update `display_name` and `notification_email`
- Email field is read-only (managed by Auth0)
- At least one field required for update request
- Validation enforced via Zod schemas

### Data Privacy
- All queries scoped to authenticated user (auth0_sub)
- No cross-user profile access
- Profile data isolated per user

## Security Requirements

1. All endpoints require JWT authentication
2. Users can only access their own profile
3. Prepared statements prevent SQL injection
4. Input validation via Zod schemas
5. Email format validation for notification_email

## Testing

```bash
# Run feature tests (when implemented)
npm test -- features/user-profile
```

## Future Enhancements

- Avatar/profile photo upload
- Additional user preferences (timezone, language, etc.)
- Profile completion progress indicator
- User account deletion/deactivation
- Profile history/audit trail
