Complete account settings with all configuration options

[frankbria]

Problem

Account settings has incomplete options. Users need full control over their account configuration.

Current Behavior

• Basic settings available
• Missing notification preferences
• Missing default export settings
• Missing writing preferences
• Security settings incomplete

Expected Behavior

• Email notification controls (on/off for each type)
• Default writing style selection
• Default export format and options
• Auto-save frequency configuration
• Editor theme selection (light/dark)
• Two-factor authentication setup
• Password change functionality

Implementation Guidance

1. Review user manual Section: "Configuration & Settings" for all expected options
2. Create settings model to store preferences
3. Build settings UI with all categories
4. Add API endpoints for settings CRUD
5. Apply settings throughout application
6. Reference existing settings patterns in codebase

Files Likely Involved

• frontend/src/components/settings/AccountSettings.tsx - Settings UI
• backend/app/api/routes/settings.py - Settings endpoints
• backend/app/models/settings.py - Settings model
• backend/app/services/settings_service.py - Settings business logic

Acceptance Criteria

• All settings categories implemented
• Notification preferences work
• Default writing style applies to new chapters
• Default export format pre-selected
• Auto-save frequency configurable
• Editor theme changes applied immediately
• Password change functional
• Integration test verifies settings persistence
• E2E test covers settings workflow

Blocked by

None

[traycerai]

Plan

Observations

The codebase uses better-auth for authentication with MongoDB storage. The current user model (file:backend/app/models/user.py) has minimal preferences (theme, email_notifications, marketing_emails). The user manual (file:AUTO_AUTHOR_USER_MANUAL.md lines 414-455) specifies comprehensive settings across four categories: Writing Preferences, Export Settings, Notification Settings, and Security Settings. The backend follows FastAPI patterns with Pydantic schemas, and the frontend uses Next.js with the useAuthFetch hook for API calls. Password change tests exist but are currently skipped pending better-auth integration.

Approach

Extend the existing user preferences model to support all settings categories documented in the user manual. Create new backend endpoints for settings CRUD operations, leveraging existing patterns in file:backend/app/api/endpoints/users.py. Build a comprehensive settings UI component using existing form patterns from file:frontend/src/components/ui/form-components.tsx. Integrate password change functionality with better-auth's API. Apply settings throughout the application (auto-save frequency, editor theme, default export options). Add integration and E2E tests following existing test patterns.

Implementation Steps

1. Backend - Extend Data Models

Update User Preferences Model (file:backend/app/models/user.py and file:backend/app/schemas/user.py):

Expand the UserPreferences class to include all settings categories:

classDiagram
    class UserPreferences {
        +WritingPreferences writing
        +ExportPreferences export
        +NotificationPreferences notifications
        +SecurityPreferences security
    }
    class WritingPreferences {
        +str default_writing_style
        +int auto_save_frequency
        +str voice_input_language
        +str editor_theme
    }
    class ExportPreferences {
        +str default_format
        +str page_size
        +bool include_empty_chapters
        +str filename_format
    }
    class NotificationPreferences {
        +bool email_notifications
        +bool writing_reminders
        +bool progress_updates
        +bool backup_notifications
    }
    class SecurityPreferences {
        +bool two_factor_enabled
        +List~str~ active_sessions
        +str api_key
    }
    UserPreferences --> WritingPreferences
    UserPreferences --> ExportPreferences
    UserPreferences --> NotificationPreferences
    UserPreferences --> SecurityPreferences

Loading

Setting Category	Fields	Default Values
Writing	default_writing_style, auto_save_frequency, voice_input_language, editor_theme	"professional", 3, "en", "dark"
Export	default_format, page_size, include_empty_chapters, filename_format	"pdf", "letter", false, "{title}_{date}"
Notifications	email_notifications, writing_reminders, progress_updates, backup_notifications	true, false, true, true
Security	two_factor_enabled, active_sessions, api_key	false, [], null

2. Backend - Create Settings Endpoints

Create Settings Router (file:backend/app/api/endpoints/settings.py):

Follow the pattern from file:backend/app/api/endpoints/users.py to create:

• GET /api/v1/settings - Retrieve current user's settings
• PATCH /api/v1/settings - Update specific settings (partial update)
• PUT /api/v1/settings/reset - Reset settings to defaults
• GET /api/v1/settings/defaults - Get default settings values

Create Settings Service (file:backend/app/services/settings_service.py):

Implement business logic for:

• Validating setting values (e.g., auto_save_frequency between 3-30 seconds)
• Applying default values for missing settings
• Handling backward compatibility with existing user preferences
• Sanitizing and validating filename formats

Register Router in file:backend/app/api/endpoints/router.py:

• Add settings router to the main API router with prefix /settings

3. Backend - Password Change Integration

Create Password Change Endpoint (file:backend/app/api/endpoints/auth.py or extend file:backend/app/api/endpoints/users.py):

• POST /api/v1/users/change-password - Change user password via better-auth
• Integrate with better-auth's password management API
• Validate current password before allowing change
• Enforce password strength requirements (min 8 chars, uppercase, lowercase, number, special char)
• Invalidate all sessions except current after password change
• Update the skipped tests in file:backend/tests/test_api/test_routes/test_password_change.py

4. Backend - Session Management for Security Settings

Extend Session Endpoints (file:backend/app/api/endpoints/sessions.py):

• GET /api/v1/sessions - List all active sessions for current user
• DELETE /api/v1/sessions/{session_id} - Revoke specific session
• DELETE /api/v1/sessions/all - Revoke all sessions (already exists, verify functionality)

5. Frontend - Settings Type Definitions

Create Settings Types (file:frontend/src/types/settings.ts):

Define TypeScript interfaces matching backend schemas:

• WritingPreferences
• ExportPreferences
• NotificationPreferences
• SecurityPreferences
• UserSettings (composite type)

6. Frontend - Settings API Client

Create Settings API Module (file:frontend/src/lib/api/settings.ts):

Using the useAuthFetch hook pattern from file:frontend/src/hooks/useAuthFetch.ts:

• getSettings() - Fetch current settings
• updateSettings(settings) - Update settings
• resetSettings() - Reset to defaults
• changePassword(currentPassword, newPassword) - Change password

7. Frontend - Settings UI Components

Create Settings Component Structure:

frontend/src/components/settings/
├── AccountSettings.tsx          # Main settings container
├── WritingPreferencesTab.tsx    # Writing settings
├── ExportSettingsTab.tsx        # Export settings
├── NotificationSettingsTab.tsx  # Notification settings
├── SecuritySettingsTab.tsx      # Security settings
└── PasswordChangeDialog.tsx     # Password change modal

AccountSettings Component (file:frontend/src/components/settings/AccountSettings.tsx):

Use shadcn/ui components from file:frontend/src/components/ui/:

• Tabs component for category navigation
• Form components for input fields
• Button components for actions
• Dialog component for password change
• Toast/Sonner for success/error notifications

Follow patterns from file:frontend/src/components/BookMetadataForm.tsx for form handling.

8. Frontend - Writing Preferences Tab

WritingPreferencesTab Component:

Setting	Input Type	Options
Default Writing Style	Select	Professional, Conversational, Academic, Creative, Technical
Auto-Save Frequency	Slider	3-30 seconds
Voice Input Language	Select	English, Spanish, French, German, etc.
Editor Theme	Radio Group	Light, Dark, System

9. Frontend - Export Settings Tab

ExportSettingsTab Component:

Setting	Input Type	Options
Default Export Format	Radio Group	PDF, DOCX
Page Size	Select	Letter, A4
Include Empty Chapters	Switch	Yes/No
Filename Format	Input	Text with variables: {title}, {date}, {author}

10. Frontend - Notification Settings Tab

NotificationSettingsTab Component:

Setting	Input Type	Description
Email Notifications	Switch	Master toggle for all emails
Writing Reminders	Switch	Daily writing reminders
Progress Updates	Switch	Milestone achievements
Backup Notifications	Switch	Local backup alerts

11. Frontend - Security Settings Tab

SecuritySettingsTab Component:

Features:

• Password Change: Button to open PasswordChangeDialog
• Two-Factor Authentication: Toggle with setup wizard (placeholder for future implementation)
• Active Sessions: List of active sessions with device info and revoke buttons
• API Access: Display API key with regenerate option (placeholder for future implementation)

PasswordChangeDialog Component:

• Current password input (password field)
• New password input (password field with strength indicator)
• Confirm new password input (password field)
• Validation: passwords match, meets strength requirements
• Submit button with loading state

12. Frontend - Settings Page/Route

Create Settings Page (file:frontend/src/app/settings/page.tsx or similar):

• Protected route requiring authentication
• Render AccountSettings component
• Handle loading states while fetching settings
• Display error states if settings fail to load

13. Frontend - Apply Settings Throughout Application

Auto-Save Frequency:

• Update editor auto-save logic to use settings.writing.auto_save_frequency
• Modify existing auto-save implementation to be configurable

Editor Theme:

• Apply theme setting to editor component
• Sync with system theme if "system" is selected
• Persist theme changes immediately

Default Export Options:

• Pre-populate export dialog with settings.export.default_format and settings.export.page_size
• Apply settings.export.include_empty_chapters as default checkbox state

Default Writing Style:

• Pre-select writing style in AI draft generation based on settings.writing.default_writing_style

14. Backend - Integration Tests

Create Settings Integration Tests (file:backend/tests/test_api/test_routes/test_settings.py):

Test scenarios:

• Get settings returns default values for new users
• Update settings successfully updates preferences
• Partial updates only modify specified fields
• Invalid setting values are rejected with validation errors
• Reset settings restores defaults
• Settings are persisted across sessions

Update Password Change Tests (file:backend/tests/test_api/test_routes/test_password_change.py):

• Remove pytest.skip decorator
• Update tests to use better-auth instead of Clerk
• Test password strength validation
• Test session invalidation after password change

15. Frontend - Unit Tests

Create Settings Component Tests:

Test files:

• file:frontend/src/components/settings/__tests__/AccountSettings.test.tsx
• file:frontend/src/components/settings/__tests__/WritingPreferencesTab.test.tsx
• file:frontend/src/components/settings/__tests__/SecuritySettingsTab.test.tsx

Test scenarios:

• Settings load and display correctly
• Form inputs update state
• Save button triggers API call
• Success/error notifications display
• Password change validation works
• Theme changes apply immediately

16. Frontend - E2E Tests

Create Settings E2E Test (file:frontend/tests/e2e/settings-workflow.spec.ts):

Test flow:

1. Navigate to settings page
2. Update writing preferences (change auto-save frequency)
3. Update export settings (change default format)
4. Toggle notification settings
5. Change password successfully
6. Verify settings persist after page reload
7. Create new chapter and verify default writing style is applied
8. Export book and verify default format is pre-selected

17. Database Migration

Create Migration Script (file:backend/migrations/add_settings_to_users.py):

• Add default settings to existing users without preferences
• Migrate existing simple preferences to new nested structure
• Ensure backward compatibility during transition

18. Documentation Updates

Update API Documentation:

• Add settings endpoints to OpenAPI/Swagger docs
• Document all setting fields and their valid values
• Include examples for each endpoint

Update User Manual (file:AUTO_AUTHOR_USER_MANUAL.md):

• Verify all documented settings are implemented
• Add screenshots of settings UI (if applicable)
• Update any outdated information

19. Validation & Error Handling

Backend Validation:

• Auto-save frequency: 3-30 seconds
• Writing style: must be one of predefined options
• Page size: "letter" or "a4"
• Filename format: validate template variables

Frontend Validation:

• Real-time validation feedback
• Prevent submission of invalid values
• Clear error messages for each field

Error Handling:

• Network errors: retry with exponential backoff
• Validation errors: display field-specific messages
• Server errors: show user-friendly error notification

20. Performance Considerations

Optimization Strategies:

• Debounce auto-save frequency changes
• Cache settings in frontend state management
• Only send changed fields in PATCH requests
• Lazy load settings tabs for faster initial render

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses better-auth for authentication with MongoDB storage. The current user model (`file:backend/app/models/user.py`) has minimal preferences (theme, email_notifications, marketing_emails). The user manual (`file:AUTO_AUTHOR_USER_MANUAL.md` lines 414-455) specifies comprehensive settings across four categories: Writing Preferences, Export Settings, Notification Settings, and Security Settings. The backend follows FastAPI patterns with Pydantic schemas, and the frontend uses Next.js with the `useAuthFetch` hook for API calls. Password change tests exist but are currently skipped pending better-auth integration.

## Approach

Extend the existing user preferences model to support all settings categories documented in the user manual. Create new backend endpoints for settings CRUD operations, leveraging existing patterns in `file:backend/app/api/endpoints/users.py`. Build a comprehensive settings UI component using existing form patterns from `file:frontend/src/components/ui/form-components.tsx`. Integrate password change functionality with better-auth's API. Apply settings throughout the application (auto-save frequency, editor theme, default export options). Add integration and E2E tests following existing test patterns.

## Implementation Steps

### 1. Backend - Extend Data Models

**Update User Preferences Model** (`file:backend/app/models/user.py` and `file:backend/app/schemas/user.py`):

Expand the `UserPreferences` class to include all settings categories:

```mermaid
classDiagram
    class UserPreferences {
        +WritingPreferences writing
        +ExportPreferences export
        +NotificationPreferences notifications
        +SecurityPreferences security
    }
    class WritingPreferences {
        +str default_writing_style
        +int auto_save_frequency
        +str voice_input_language
        +str editor_theme
    }
    class ExportPreferences {
        +str default_format
        +str page_size
        +bool include_empty_chapters
        +str filename_format
    }
    class NotificationPreferences {
        +bool email_notifications
        +bool writing_reminders
        +bool progress_updates
        +bool backup_notifications
    }
    class SecurityPreferences {
        +bool two_factor_enabled
        +List~str~ active_sessions
        +str api_key
    }
    UserPreferences --> WritingPreferences
    UserPreferences --> ExportPreferences
    UserPreferences --> NotificationPreferences
    UserPreferences --> SecurityPreferences
```

| Setting Category | Fields | Default Values |
|-----------------|--------|----------------|
| Writing | default_writing_style, auto_save_frequency, voice_input_language, editor_theme | "professional", 3, "en", "dark" |
| Export | default_format, page_size, include_empty_chapters, filename_format | "pdf", "letter", false, "{title}_{date}" |
| Notifications | email_notifications, writing_reminders, progress_updates, backup_notifications | true, false, true, true |
| Security | two_factor_enabled, active_sessions, api_key | false, [], null |

### 2. Backend - Create Settings Endpoints

**Create Settings Router** (`file:backend/app/api/endpoints/settings.py`):

Follow the pattern from `file:backend/app/api/endpoints/users.py` to create:

- `GET /api/v1/settings` - Retrieve current user's settings
- `PATCH /api/v1/settings` - Update specific settings (partial update)
- `PUT /api/v1/settings/reset` - Reset settings to defaults
- `GET /api/v1/settings/defaults` - Get default settings values

**Create Settings Service** (`file:backend/app/services/settings_service.py`):

Implement business logic for:
- Validating setting values (e.g., auto_save_frequency between 3-30 seconds)
- Applying default values for missing settings
- Handling backward compatibility with existing user preferences
- Sanitizing and validating filename formats

**Register Router** in `file:backend/app/api/endpoints/router.py`:
- Add settings router to the main API router with prefix `/settings`

### 3. Backend - Password Change Integration

**Create Password Change Endpoint** (`file:backend/app/api/endpoints/auth.py` or extend `file:backend/app/api/endpoints/users.py`):

- `POST /api/v1/users/change-password` - Change user password via better-auth
- Integrate with better-auth's password management API
- Validate current password before allowing change
- Enforce password strength requirements (min 8 chars, uppercase, lowercase, number, special char)
- Invalidate all sessions except current after password change
- Update the skipped tests in `file:backend/tests/test_api/test_routes/test_password_change.py`

### 4. Backend - Session Management for Security Settings

**Extend Session Endpoints** (`file:backend/app/api/endpoints/sessions.py`):

- `GET /api/v1/sessions` - List all active sessions for current user
- `DELETE /api/v1/sessions/{session_id}` - Revoke specific session
- `DELETE /api/v1/sessions/all` - Revoke all sessions (already exists, verify functionality)

### 5. Frontend - Settings Type Definitions

**Create Settings Types** (`file:frontend/src/types/settings.ts`):

Define TypeScript interfaces matching backend schemas:
- `WritingPreferences`
- `ExportPreferences`
- `NotificationPreferences`
- `SecurityPreferences`
- `UserSettings` (composite type)

### 6. Frontend - Settings API Client

**Create Settings API Module** (`file:frontend/src/lib/api/settings.ts`):

Using the `useAuthFetch` hook pattern from `file:frontend/src/hooks/useAuthFetch.ts`:
- `getSettings()` - Fetch current settings
- `updateSettings(settings)` - Update settings
- `resetSettings()` - Reset to defaults
- `changePassword(currentPassword, newPassword)` - Change password

### 7. Frontend - Settings UI Components

**Create Settings Component Structure**:

```
frontend/src/components/settings/
├── AccountSettings.tsx          # Main settings container
├── WritingPreferencesTab.tsx    # Writing settings
├── ExportSettingsTab.tsx        # Export settings
├── NotificationSettingsTab.tsx  # Notification settings
├── SecuritySettingsTab.tsx      # Security settings
└── PasswordChangeDialog.tsx     # Password change modal
```

**AccountSettings Component** (`file:frontend/src/components/settings/AccountSettings.tsx`):

Use shadcn/ui components from `file:frontend/src/components/ui/`:
- Tabs component for category navigation
- Form components for input fields
- Button components for actions
- Dialog component for password change
- Toast/Sonner for success/error notifications

Follow patterns from `file:frontend/src/components/BookMetadataForm.tsx` for form handling.

### 8. Frontend - Writing Preferences Tab

**WritingPreferencesTab Component**:

| Setting | Input Type | Options |
|---------|-----------|---------|
| Default Writing Style | Select | Professional, Conversational, Academic, Creative, Technical |
| Auto-Save Frequency | Slider | 3-30 seconds |
| Voice Input Language | Select | English, Spanish, French, German, etc. |
| Editor Theme | Radio Group | Light, Dark, System |

### 9. Frontend - Export Settings Tab

**ExportSettingsTab Component**:

| Setting | Input Type | Options |
|---------|-----------|---------|
| Default Export Format | Radio Group | PDF, DOCX |
| Page Size | Select | Letter, A4 |
| Include Empty Chapters | Switch | Yes/No |
| Filename Format | Input | Text with variables: {title}, {date}, {author} |

### 10. Frontend - Notification Settings Tab

**NotificationSettingsTab Component**:

| Setting | Input Type | Description |
|---------|-----------|-------------|
| Email Notifications | Switch | Master toggle for all emails |
| Writing Reminders | Switch | Daily writing reminders |
| Progress Updates | Switch | Milestone achievements |
| Backup Notifications | Switch | Local backup alerts |

### 11. Frontend - Security Settings Tab

**SecuritySettingsTab Component**:

Features:
- **Password Change**: Button to open `PasswordChangeDialog`
- **Two-Factor Authentication**: Toggle with setup wizard (placeholder for future implementation)
- **Active Sessions**: List of active sessions with device info and revoke buttons
- **API Access**: Display API key with regenerate option (placeholder for future implementation)

**PasswordChangeDialog Component**:
- Current password input (password field)
- New password input (password field with strength indicator)
- Confirm new password input (password field)
- Validation: passwords match, meets strength requirements
- Submit button with loading state

### 12. Frontend - Settings Page/Route

**Create Settings Page** (`file:frontend/src/app/settings/page.tsx` or similar):

- Protected route requiring authentication
- Render `AccountSettings` component
- Handle loading states while fetching settings
- Display error states if settings fail to load

### 13. Frontend - Apply Settings Throughout Application

**Auto-Save Frequency**:
- Update editor auto-save logic to use `settings.writing.auto_save_frequency`
- Modify existing auto-save implementation to be configurable

**Editor Theme**:
- Apply theme setting to editor component
- Sync with system theme if "system" is selected
- Persist theme changes immediately

**Default Export Options**:
- Pre-populate export dialog with `settings.export.default_format` and `settings.export.page_size`
- Apply `settings.export.include_empty_chapters` as default checkbox state

**Default Writing Style**:
- Pre-select writing style in AI draft generation based on `settings.writing.default_writing_style`

### 14. Backend - Integration Tests

**Create Settings Integration Tests** (`file:backend/tests/test_api/test_routes/test_settings.py`):

Test scenarios:
- Get settings returns default values for new users
- Update settings successfully updates preferences
- Partial updates only modify specified fields
- Invalid setting values are rejected with validation errors
- Reset settings restores defaults
- Settings are persisted across sessions

**Update Password Change Tests** (`file:backend/tests/test_api/test_routes/test_password_change.py`):
- Remove `pytest.skip` decorator
- Update tests to use better-auth instead of Clerk
- Test password strength validation
- Test session invalidation after password change

### 15. Frontend - Unit Tests

**Create Settings Component Tests**:

Test files:
- `file:frontend/src/components/settings/__tests__/AccountSettings.test.tsx`
- `file:frontend/src/components/settings/__tests__/WritingPreferencesTab.test.tsx`
- `file:frontend/src/components/settings/__tests__/SecuritySettingsTab.test.tsx`

Test scenarios:
- Settings load and display correctly
- Form inputs update state
- Save button triggers API call
- Success/error notifications display
- Password change validation works
- Theme changes apply immediately

### 16. Frontend - E2E Tests

**Create Settings E2E Test** (`file:frontend/tests/e2e/settings-workflow.spec.ts`):

Test flow:
1. Navigate to settings page
2. Update writing preferences (change auto-save frequency)
3. Update export settings (change default format)
4. Toggle notification settings
5. Change password successfully
6. Verify settings persist after page reload
7. Create new chapter and verify default writing style is applied
8. Export book and verify default format is pre-selected

### 17. Database Migration

**Create Migration Script** (`file:backend/migrations/add_settings_to_users.py`):

- Add default settings to existing users without preferences
- Migrate existing simple preferences to new nested structure
- Ensure backward compatibility during transition

### 18. Documentation Updates

**Update API Documentation**:
- Add settings endpoints to OpenAPI/Swagger docs
- Document all setting fields and their valid values
- Include examples for each endpoint

**Update User Manual** (`file:AUTO_AUTHOR_USER_MANUAL.md`):
- Verify all documented settings are implemented
- Add screenshots of settings UI (if applicable)
- Update any outdated information

### 19. Validation & Error Handling

**Backend Validation**:
- Auto-save frequency: 3-30 seconds
- Writing style: must be one of predefined options
- Page size: "letter" or "a4"
- Filename format: validate template variables

**Frontend Validation**:
- Real-time validation feedback
- Prevent submission of invalid values
- Clear error messages for each field

**Error Handling**:
- Network errors: retry with exponential backoff
- Validation errors: display field-specific messages
- Server errors: show user-friendly error notification

### 20. Performance Considerations

**Optimization Strategies**:
- Debounce auto-save frequency changes
- Cache settings in frontend state management
- Only send changed fields in PATCH requests
- Lazy load settings tabs for faster initial render

---

Execution Information

Branch: main
Commit: 6841238

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

_{You can configure auto-planning by selecting labels in the issue_enrichment configuration.}

🔗 Similar Issues

Related Issues

• Complete user profile editing functionality #63
• Complete writing style transformation implementation #58
• Implement content enhancement features for existing chapter text #57

👤 Suggested Assignees

• frankbria

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

New Plan

Observations

The codebase uses better-auth for authentication with MongoDB storage. The current user model (file:backend/app/models/user.py) has minimal preferences (theme, email_notifications, marketing_emails). The user manual (file:AUTO_AUTHOR_USER_MANUAL.md lines 414-455) specifies comprehensive settings across four categories: Writing Preferences, Export Settings, Notification Settings, and Security Settings. The backend follows FastAPI patterns with Pydantic schemas, and the frontend uses Next.js with the useAuthFetch hook for API calls. Password change tests exist but are currently skipped pending better-auth integration.

Approach

Extend the existing user preferences model to support all settings categories documented in the user manual. Create new backend endpoints for settings CRUD operations, leveraging existing patterns in file:backend/app/api/endpoints/users.py. Build a comprehensive settings UI component using existing form patterns from file:frontend/src/components/ui/form-components.tsx. Integrate password change functionality with better-auth's API. Apply settings throughout the application (auto-save frequency, editor theme, default export options). Add integration and E2E tests following existing test patterns.

Implementation Steps

1. Backend - Extend Data Models

Update User Preferences Model (file:backend/app/models/user.py and file:backend/app/schemas/user.py):

Expand the UserPreferences class to include all settings categories:

classDiagram
    class UserPreferences {
        +WritingPreferences writing
        +ExportPreferences export
        +NotificationPreferences notifications
        +SecurityPreferences security
    }
    class WritingPreferences {
        +str default_writing_style
        +int auto_save_frequency
        +str voice_input_language
        +str editor_theme
    }
    class ExportPreferences {
        +str default_format
        +str page_size
        +bool include_empty_chapters
        +str filename_format
    }
    class NotificationPreferences {
        +bool email_notifications
        +bool writing_reminders
        +bool progress_updates
        +bool backup_notifications
    }
    class SecurityPreferences {
        +bool two_factor_enabled
        +List~str~ active_sessions
        +str api_key
    }
    UserPreferences --> WritingPreferences
    UserPreferences --> ExportPreferences
    UserPreferences --> NotificationPreferences
    UserPreferences --> SecurityPreferences

Loading

Setting Category	Fields	Default Values
Writing	default_writing_style, auto_save_frequency, voice_input_language, editor_theme	"professional", 3, "en", "dark"
Export	default_format, page_size, include_empty_chapters, filename_format	"pdf", "letter", false, "{title}_{date}"
Notifications	email_notifications, writing_reminders, progress_updates, backup_notifications	true, false, true, true
Security	two_factor_enabled, active_sessions, api_key	false, [], null

2. Backend - Create Settings Endpoints

Create Settings Router (file:backend/app/api/endpoints/settings.py):

Follow the pattern from file:backend/app/api/endpoints/users.py to create:

• GET /api/v1/settings - Retrieve current user's settings
• PATCH /api/v1/settings - Update specific settings (partial update)
• PUT /api/v1/settings/reset - Reset settings to defaults
• GET /api/v1/settings/defaults - Get default settings values

Create Settings Service (file:backend/app/services/settings_service.py):

Implement business logic for:

• Validating setting values (e.g., auto_save_frequency between 3-30 seconds)
• Applying default values for missing settings
• Handling backward compatibility with existing user preferences
• Sanitizing and validating filename formats

Register Router in file:backend/app/api/endpoints/router.py:

• Add settings router to the main API router with prefix /settings

3. Backend - Password Change Integration

Create Password Change Endpoint (file:backend/app/api/endpoints/auth.py or extend file:backend/app/api/endpoints/users.py):

• POST /api/v1/users/change-password - Change user password via better-auth
• Integrate with better-auth's password management API
• Validate current password before allowing change
• Enforce password strength requirements (min 8 chars, uppercase, lowercase, number, special char)
• Invalidate all sessions except current after password change
• Update the skipped tests in file:backend/tests/test_api/test_routes/test_password_change.py

4. Backend - Session Management for Security Settings

Extend Session Endpoints (file:backend/app/api/endpoints/sessions.py):

• GET /api/v1/sessions - List all active sessions for current user
• DELETE /api/v1/sessions/{session_id} - Revoke specific session
• DELETE /api/v1/sessions/all - Revoke all sessions (already exists, verify functionality)

5. Frontend - Settings Type Definitions

Create Settings Types (file:frontend/src/types/settings.ts):

Define TypeScript interfaces matching backend schemas:

• WritingPreferences
• ExportPreferences
• NotificationPreferences
• SecurityPreferences
• UserSettings (composite type)

6. Frontend - Settings API Client

Create Settings API Module (file:frontend/src/lib/api/settings.ts):

Using the useAuthFetch hook pattern from file:frontend/src/hooks/useAuthFetch.ts:

• getSettings() - Fetch current settings
• updateSettings(settings) - Update settings
• resetSettings() - Reset to defaults
• changePassword(currentPassword, newPassword) - Change password

7. Frontend - Settings UI Components

Create Settings Component Structure:

frontend/src/components/settings/
├── AccountSettings.tsx          # Main settings container
├── WritingPreferencesTab.tsx    # Writing settings
├── ExportSettingsTab.tsx        # Export settings
├── NotificationSettingsTab.tsx  # Notification settings
├── SecuritySettingsTab.tsx      # Security settings
└── PasswordChangeDialog.tsx     # Password change modal

AccountSettings Component (file:frontend/src/components/settings/AccountSettings.tsx):

Use shadcn/ui components from file:frontend/src/components/ui/:

• Tabs component for category navigation
• Form components for input fields
• Button components for actions
• Dialog component for password change
• Toast/Sonner for success/error notifications

Follow patterns from file:frontend/src/components/BookMetadataForm.tsx for form handling.

8. Frontend - Writing Preferences Tab

WritingPreferencesTab Component:

Setting	Input Type	Options
Default Writing Style	Select	Professional, Conversational, Academic, Creative, Technical
Auto-Save Frequency	Slider	3-30 seconds
Voice Input Language	Select	English, Spanish, French, German, etc.
Editor Theme	Radio Group	Light, Dark, System

9. Frontend - Export Settings Tab

ExportSettingsTab Component:

Setting	Input Type	Options
Default Export Format	Radio Group	PDF, DOCX
Page Size	Select	Letter, A4
Include Empty Chapters	Switch	Yes/No
Filename Format	Input	Text with variables: {title}, {date}, {author}

10. Frontend - Notification Settings Tab

NotificationSettingsTab Component:

Setting	Input Type	Description
Email Notifications	Switch	Master toggle for all emails
Writing Reminders	Switch	Daily writing reminders
Progress Updates	Switch	Milestone achievements
Backup Notifications	Switch	Local backup alerts

11. Frontend - Security Settings Tab

SecuritySettingsTab Component:

Features:

• Password Change: Button to open PasswordChangeDialog
• Two-Factor Authentication: Toggle with setup wizard (placeholder for future implementation)
• Active Sessions: List of active sessions with device info and revoke buttons
• API Access: Display API key with regenerate option (placeholder for future implementation)

PasswordChangeDialog Component:

• Current password input (password field)
• New password input (password field with strength indicator)
• Confirm new password input (password field)
• Validation: passwords match, meets strength requirements
• Submit button with loading state

12. Frontend - Settings Page/Route

Create Settings Page (file:frontend/src/app/settings/page.tsx or similar):

• Protected route requiring authentication
• Render AccountSettings component
• Handle loading states while fetching settings
• Display error states if settings fail to load

13. Frontend - Apply Settings Throughout Application

Auto-Save Frequency:

• Update editor auto-save logic to use settings.writing.auto_save_frequency
• Modify existing auto-save implementation to be configurable

Editor Theme:

• Apply theme setting to editor component
• Sync with system theme if "system" is selected
• Persist theme changes immediately

Default Export Options:

• Pre-populate export dialog with settings.export.default_format and settings.export.page_size
• Apply settings.export.include_empty_chapters as default checkbox state

Default Writing Style:

• Pre-select writing style in AI draft generation based on settings.writing.default_writing_style

14. Backend - Integration Tests

Create Settings Integration Tests (file:backend/tests/test_api/test_routes/test_settings.py):

Test scenarios:

• Get settings returns default values for new users
• Update settings successfully updates preferences
• Partial updates only modify specified fields
• Invalid setting values are rejected with validation errors
• Reset settings restores defaults
• Settings are persisted across sessions

Update Password Change Tests (file:backend/tests/test_api/test_routes/test_password_change.py):

• Remove pytest.skip decorator
• Update tests to use better-auth instead of Clerk
• Test password strength validation
• Test session invalidation after password change

15. Frontend - Unit Tests

Create Settings Component Tests:

Test files:

• file:frontend/src/components/settings/__tests__/AccountSettings.test.tsx
• file:frontend/src/components/settings/__tests__/WritingPreferencesTab.test.tsx
• file:frontend/src/components/settings/__tests__/SecuritySettingsTab.test.tsx

Test scenarios:

• Settings load and display correctly
• Form inputs update state
• Save button triggers API call
• Success/error notifications display
• Password change validation works
• Theme changes apply immediately

16. Frontend - E2E Tests

Create Settings E2E Test (file:frontend/tests/e2e/settings-workflow.spec.ts):

Test flow:

1. Navigate to settings page
2. Update writing preferences (change auto-save frequency)
3. Update export settings (change default format)
4. Toggle notification settings
5. Change password successfully
6. Verify settings persist after page reload
7. Create new chapter and verify default writing style is applied
8. Export book and verify default format is pre-selected

17. Database Migration

Create Migration Script (file:backend/migrations/add_settings_to_users.py):

• Add default settings to existing users without preferences
• Migrate existing simple preferences to new nested structure
• Ensure backward compatibility during transition

18. Documentation Updates

Update API Documentation:

• Add settings endpoints to OpenAPI/Swagger docs
• Document all setting fields and their valid values
• Include examples for each endpoint

Update User Manual (file:AUTO_AUTHOR_USER_MANUAL.md):

• Verify all documented settings are implemented
• Add screenshots of settings UI (if applicable)
• Update any outdated information

19. Validation & Error Handling

Backend Validation:

• Auto-save frequency: 3-30 seconds
• Writing style: must be one of predefined options
• Page size: "letter" or "a4"
• Filename format: validate template variables

Frontend Validation:

• Real-time validation feedback
• Prevent submission of invalid values
• Clear error messages for each field

Error Handling:

• Network errors: retry with exponential backoff
• Validation errors: display field-specific messages
• Server errors: show user-friendly error notification

20. Performance Considerations

Optimization Strategies:

• Debounce auto-save frequency changes
• Cache settings in frontend state management
• Only send changed fields in PATCH requests
• Lazy load settings tabs for faster initial render

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses better-auth for authentication with MongoDB storage. The current user model (`file:backend/app/models/user.py`) has minimal preferences (theme, email_notifications, marketing_emails). The user manual (`file:AUTO_AUTHOR_USER_MANUAL.md` lines 414-455) specifies comprehensive settings across four categories: Writing Preferences, Export Settings, Notification Settings, and Security Settings. The backend follows FastAPI patterns with Pydantic schemas, and the frontend uses Next.js with the `useAuthFetch` hook for API calls. Password change tests exist but are currently skipped pending better-auth integration.

## Approach

Extend the existing user preferences model to support all settings categories documented in the user manual. Create new backend endpoints for settings CRUD operations, leveraging existing patterns in `file:backend/app/api/endpoints/users.py`. Build a comprehensive settings UI component using existing form patterns from `file:frontend/src/components/ui/form-components.tsx`. Integrate password change functionality with better-auth's API. Apply settings throughout the application (auto-save frequency, editor theme, default export options). Add integration and E2E tests following existing test patterns.

## Implementation Steps

### 1. Backend - Extend Data Models

**Update User Preferences Model** (`file:backend/app/models/user.py` and `file:backend/app/schemas/user.py`):

Expand the `UserPreferences` class to include all settings categories:

```mermaid
classDiagram
    class UserPreferences {
        +WritingPreferences writing
        +ExportPreferences export
        +NotificationPreferences notifications
        +SecurityPreferences security
    }
    class WritingPreferences {
        +str default_writing_style
        +int auto_save_frequency
        +str voice_input_language
        +str editor_theme
    }
    class ExportPreferences {
        +str default_format
        +str page_size
        +bool include_empty_chapters
        +str filename_format
    }
    class NotificationPreferences {
        +bool email_notifications
        +bool writing_reminders
        +bool progress_updates
        +bool backup_notifications
    }
    class SecurityPreferences {
        +bool two_factor_enabled
        +List~str~ active_sessions
        +str api_key
    }
    UserPreferences --> WritingPreferences
    UserPreferences --> ExportPreferences
    UserPreferences --> NotificationPreferences
    UserPreferences --> SecurityPreferences
```

| Setting Category | Fields | Default Values |
|-----------------|--------|----------------|
| Writing | default_writing_style, auto_save_frequency, voice_input_language, editor_theme | "professional", 3, "en", "dark" |
| Export | default_format, page_size, include_empty_chapters, filename_format | "pdf", "letter", false, "{title}_{date}" |
| Notifications | email_notifications, writing_reminders, progress_updates, backup_notifications | true, false, true, true |
| Security | two_factor_enabled, active_sessions, api_key | false, [], null |

### 2. Backend - Create Settings Endpoints

**Create Settings Router** (`file:backend/app/api/endpoints/settings.py`):

Follow the pattern from `file:backend/app/api/endpoints/users.py` to create:

- `GET /api/v1/settings` - Retrieve current user's settings
- `PATCH /api/v1/settings` - Update specific settings (partial update)
- `PUT /api/v1/settings/reset` - Reset settings to defaults
- `GET /api/v1/settings/defaults` - Get default settings values

**Create Settings Service** (`file:backend/app/services/settings_service.py`):

Implement business logic for:
- Validating setting values (e.g., auto_save_frequency between 3-30 seconds)
- Applying default values for missing settings
- Handling backward compatibility with existing user preferences
- Sanitizing and validating filename formats

**Register Router** in `file:backend/app/api/endpoints/router.py`:
- Add settings router to the main API router with prefix `/settings`

### 3. Backend - Password Change Integration

**Create Password Change Endpoint** (`file:backend/app/api/endpoints/auth.py` or extend `file:backend/app/api/endpoints/users.py`):

- `POST /api/v1/users/change-password` - Change user password via better-auth
- Integrate with better-auth's password management API
- Validate current password before allowing change
- Enforce password strength requirements (min 8 chars, uppercase, lowercase, number, special char)
- Invalidate all sessions except current after password change
- Update the skipped tests in `file:backend/tests/test_api/test_routes/test_password_change.py`

### 4. Backend - Session Management for Security Settings

**Extend Session Endpoints** (`file:backend/app/api/endpoints/sessions.py`):

- `GET /api/v1/sessions` - List all active sessions for current user
- `DELETE /api/v1/sessions/{session_id}` - Revoke specific session
- `DELETE /api/v1/sessions/all` - Revoke all sessions (already exists, verify functionality)

### 5. Frontend - Settings Type Definitions

**Create Settings Types** (`file:frontend/src/types/settings.ts`):

Define TypeScript interfaces matching backend schemas:
- `WritingPreferences`
- `ExportPreferences`
- `NotificationPreferences`
- `SecurityPreferences`
- `UserSettings` (composite type)

### 6. Frontend - Settings API Client

**Create Settings API Module** (`file:frontend/src/lib/api/settings.ts`):

Using the `useAuthFetch` hook pattern from `file:frontend/src/hooks/useAuthFetch.ts`:
- `getSettings()` - Fetch current settings
- `updateSettings(settings)` - Update settings
- `resetSettings()` - Reset to defaults
- `changePassword(currentPassword, newPassword)` - Change password

### 7. Frontend - Settings UI Components

**Create Settings Component Structure**:

```
frontend/src/components/settings/
├── AccountSettings.tsx          # Main settings container
├── WritingPreferencesTab.tsx    # Writing settings
├── ExportSettingsTab.tsx        # Export settings
├── NotificationSettingsTab.tsx  # Notification settings
├── SecuritySettingsTab.tsx      # Security settings
└── PasswordChangeDialog.tsx     # Password change modal
```

**AccountSettings Component** (`file:frontend/src/components/settings/AccountSettings.tsx`):

Use shadcn/ui components from `file:frontend/src/components/ui/`:
- Tabs component for category navigation
- Form components for input fields
- Button components for actions
- Dialog component for password change
- Toast/Sonner for success/error notifications

Follow patterns from `file:frontend/src/components/BookMetadataForm.tsx` for form handling.

### 8. Frontend - Writing Preferences Tab

**WritingPreferencesTab Component**:

| Setting | Input Type | Options |
|---------|-----------|---------|
| Default Writing Style | Select | Professional, Conversational, Academic, Creative, Technical |
| Auto-Save Frequency | Slider | 3-30 seconds |
| Voice Input Language | Select | English, Spanish, French, German, etc. |
| Editor Theme | Radio Group | Light, Dark, System |

### 9. Frontend - Export Settings Tab

**ExportSettingsTab Component**:

| Setting | Input Type | Options |
|---------|-----------|---------|
| Default Export Format | Radio Group | PDF, DOCX |
| Page Size | Select | Letter, A4 |
| Include Empty Chapters | Switch | Yes/No |
| Filename Format | Input | Text with variables: {title}, {date}, {author} |

### 10. Frontend - Notification Settings Tab

**NotificationSettingsTab Component**:

| Setting | Input Type | Description |
|---------|-----------|-------------|
| Email Notifications | Switch | Master toggle for all emails |
| Writing Reminders | Switch | Daily writing reminders |
| Progress Updates | Switch | Milestone achievements |
| Backup Notifications | Switch | Local backup alerts |

### 11. Frontend - Security Settings Tab

**SecuritySettingsTab Component**:

Features:
- **Password Change**: Button to open `PasswordChangeDialog`
- **Two-Factor Authentication**: Toggle with setup wizard (placeholder for future implementation)
- **Active Sessions**: List of active sessions with device info and revoke buttons
- **API Access**: Display API key with regenerate option (placeholder for future implementation)

**PasswordChangeDialog Component**:
- Current password input (password field)
- New password input (password field with strength indicator)
- Confirm new password input (password field)
- Validation: passwords match, meets strength requirements
- Submit button with loading state

### 12. Frontend - Settings Page/Route

**Create Settings Page** (`file:frontend/src/app/settings/page.tsx` or similar):

- Protected route requiring authentication
- Render `AccountSettings` component
- Handle loading states while fetching settings
- Display error states if settings fail to load

### 13. Frontend - Apply Settings Throughout Application

**Auto-Save Frequency**:
- Update editor auto-save logic to use `settings.writing.auto_save_frequency`
- Modify existing auto-save implementation to be configurable

**Editor Theme**:
- Apply theme setting to editor component
- Sync with system theme if "system" is selected
- Persist theme changes immediately

**Default Export Options**:
- Pre-populate export dialog with `settings.export.default_format` and `settings.export.page_size`
- Apply `settings.export.include_empty_chapters` as default checkbox state

**Default Writing Style**:
- Pre-select writing style in AI draft generation based on `settings.writing.default_writing_style`

### 14. Backend - Integration Tests

**Create Settings Integration Tests** (`file:backend/tests/test_api/test_routes/test_settings.py`):

Test scenarios:
- Get settings returns default values for new users
- Update settings successfully updates preferences
- Partial updates only modify specified fields
- Invalid setting values are rejected with validation errors
- Reset settings restores defaults
- Settings are persisted across sessions

**Update Password Change Tests** (`file:backend/tests/test_api/test_routes/test_password_change.py`):
- Remove `pytest.skip` decorator
- Update tests to use better-auth instead of Clerk
- Test password strength validation
- Test session invalidation after password change

### 15. Frontend - Unit Tests

**Create Settings Component Tests**:

Test files:
- `file:frontend/src/components/settings/__tests__/AccountSettings.test.tsx`
- `file:frontend/src/components/settings/__tests__/WritingPreferencesTab.test.tsx`
- `file:frontend/src/components/settings/__tests__/SecuritySettingsTab.test.tsx`

Test scenarios:
- Settings load and display correctly
- Form inputs update state
- Save button triggers API call
- Success/error notifications display
- Password change validation works
- Theme changes apply immediately

### 16. Frontend - E2E Tests

**Create Settings E2E Test** (`file:frontend/tests/e2e/settings-workflow.spec.ts`):

Test flow:
1. Navigate to settings page
2. Update writing preferences (change auto-save frequency)
3. Update export settings (change default format)
4. Toggle notification settings
5. Change password successfully
6. Verify settings persist after page reload
7. Create new chapter and verify default writing style is applied
8. Export book and verify default format is pre-selected

### 17. Database Migration

**Create Migration Script** (`file:backend/migrations/add_settings_to_users.py`):

- Add default settings to existing users without preferences
- Migrate existing simple preferences to new nested structure
- Ensure backward compatibility during transition

### 18. Documentation Updates

**Update API Documentation**:
- Add settings endpoints to OpenAPI/Swagger docs
- Document all setting fields and their valid values
- Include examples for each endpoint

**Update User Manual** (`file:AUTO_AUTHOR_USER_MANUAL.md`):
- Verify all documented settings are implemented
- Add screenshots of settings UI (if applicable)
- Update any outdated information

### 19. Validation & Error Handling

**Backend Validation**:
- Auto-save frequency: 3-30 seconds
- Writing style: must be one of predefined options
- Page size: "letter" or "a4"
- Filename format: validate template variables

**Frontend Validation**:
- Real-time validation feedback
- Prevent submission of invalid values
- Clear error messages for each field

**Error Handling**:
- Network errors: retry with exponential backoff
- Validation errors: display field-specific messages
- Server errors: show user-friendly error notification

### 20. Performance Considerations

**Optimization Strategies**:
- Debounce auto-save frequency changes
- Cache settings in frontend state management
- Only send changed fields in PATCH requests
- Lazy load settings tabs for faster initial render

---

Execution Information

Branch: main
Commit: 6841238