docs/api/user-profile/USER_PREFERENCES_API.md

User Preferences API Documentation

Overview

The User Preferences API allows users to customize their experience in the SwiftOps platform, including favorite apps in the navigation bar, UI theme, language, notification settings, and dashboard layout.

Key Features:

• Role-based default preferences
• Maximum 6 favorite apps (database constraint)
• Automatic preference creation on first access
• Full CRUD operations with audit logging
• Context-aware app availability based on user role

---

Table of Contents

1. Authentication
2. Endpoints
3. Data Models
4. Role-Based Defaults
5. Frontend Integration Guide
6. Common Use Cases
7. Error Handling
8. Best Practices

---

Authentication

All endpoints require authentication via JWT token in the Authorization header:

Authorization: Bearer <access_token>

---

Endpoints

1. Get Current User's Preferences

Endpoint: GET /api/v1/auth/me/preferences

Description: Retrieves the current user's preferences. If no preferences exist yet, they are automatically created with role-based defaults.

Response: Returns full preference object including:

• Favorite apps array (max 6 items)
• UI theme (light/dark/auto)
• Language preference
• Notification settings (email, push, SMS)
• Dashboard widget configuration
• Table/list preferences (view type, pagination, sorting)
• Map preferences (zoom level, center coordinates)
• Additional custom settings

Use Cases:

• Load user preferences on application startup
• Populate settings page
• Configure UI based on user theme preference
• Display favorite apps in navigation bar

---

2. Update User Preferences

Endpoint: PUT /api/v1/auth/me/preferences

Description: Updates one or more preference fields. Only send fields you want to update - all fields are optional.

Request Body Fields:

• favorite_apps - Array of app codes (max 6, validated against role)
• theme - One of: light, dark, auto
• language - Language code (e.g., en, sw)
• email_notifications - Boolean
• push_notifications - Boolean
• sms_notifications - Boolean
• dashboard_widgets - Array of widget codes
• default_tickets_view - One of: list, kanban, calendar
• tickets_per_page - Integer between 10-100
• default_sort_field - String (field name for default sorting)
• default_sort_order - One of: asc, desc
• default_map_zoom - Integer (map zoom level)
• default_map_center_lat - Float (latitude)
• default_map_center_lng - Float (longitude)
• additional_settings - Object (free-form custom settings)

Validation Rules:

• Maximum 6 favorite apps
• Favorite apps must be from the role's available apps list
• Theme must be one of the valid options
• Tickets per page must be between 10-100

Response: Returns updated preference object

Use Cases:

• Save settings from user preferences page
• Update theme when user toggles dark mode
• Reorder favorite apps in navigation
• Change language preference
• Toggle notification preferences

---

3. Get Available Apps for Role

Endpoint: GET /api/v1/auth/me/preferences/available-apps

Description: Returns the list of apps available for the user to favorite based on their role, along with current favorites and defaults.

Response Fields:

• role - User's current role
• current_favorites - Array of currently favorited app codes
• available_apps - Array of all apps user can choose from
• default_favorites - Array of role's default favorite apps
• max_favorites - Maximum number allowed (always 6)

Use Cases:

• Populate app picker in settings UI
• Show which apps can be added/removed
• Display role-appropriate app options
• Validate favorite apps client-side before submission

---

Data Models

UserPreferencesResponse

Full preference object returned by GET and PUT endpoints:

Core Fields:

• id - UUID of preference record
• user_id - UUID of user who owns these preferences

App & Navigation:

• favorite_apps - Array of app codes (e.g., ["dashboard", "users", "tickets"])

UI Preferences:

• theme - "light", "dark", or "auto"
• language - Language code (default: "en")

Notifications:

• email_notifications - Boolean (default: true)
• push_notifications - Boolean (default: true)
• sms_notifications - Boolean (default: false)

Dashboard:

• dashboard_widgets - Array of widget codes (e.g., ["recent_tickets", "team_performance"])

Table/List Preferences:

• default_tickets_view - View type (default: "list")
• tickets_per_page - Pagination size (default: 25)
• default_sort_field - Default sort field (default: "created_at")
• default_sort_order - Sort direction (default: "desc")

Map Preferences:

• default_map_zoom - Zoom level (default: 12)
• default_map_center_lat - Latitude (nullable)
• default_map_center_lng - Longitude (nullable)

Flexible Storage:

• additional_settings - Object for custom settings

---

Role-Based Defaults

Each role gets context-appropriate default preferences:

Platform Admin

Favorite Apps: dashboard, organizations, users, activity
Available Apps: Core apps (dashboard, organizations, users, activity) + Management apps (settings, billing, notifications, help)
Dashboard Widgets: Recent tickets, team performance, SLA metrics, organizations overview

Client Admin

Favorite Apps: dashboard, projects, tickets, team
Available Apps: Dashboard, projects, tickets, team, sales orders, customers, contractors, reports, settings, help
Dashboard Widgets: Recent tickets, team performance, SLA metrics, project status

Contractor Admin

Favorite Apps: dashboard, projects, tickets, team
Available Apps: Dashboard, projects, tickets, team, timesheets, payroll, reports, settings, help
Dashboard Widgets: Recent tickets, team performance, payroll summary, project status

Sales Manager

Favorite Apps: dashboard, sales_orders, customers, reports
Available Apps: Dashboard, sales orders, customers, reports, team, maps, settings, help
Dashboard Widgets: Sales pipeline, revenue metrics, team performance, conversion rates

Project Manager

Favorite Apps: dashboard, projects, tickets, team
Available Apps: Dashboard, projects, tickets, team, reports, maps, settings, help
Dashboard Widgets: Project status, team performance, SLA metrics, map view

Dispatcher

Favorite Apps: dashboard, tickets, maps, team
Available Apps: Dashboard, tickets, maps, team, projects, reports, settings, help
Dashboard Widgets: Recent tickets, map view, team availability, SLA metrics

Field Agent

Favorite Apps: tickets, maps, timesheets, profile
Available Apps: Tickets, maps, timesheets, profile, expenses, documents, help
Dashboard Widgets: My tickets, earnings summary, attendance summary

Sales Agent

Favorite Apps: dashboard, sales_orders, customers, maps
Available Apps: Dashboard, sales orders, customers, maps, profile, reports, help
Dashboard Widgets: My sales, customer pipeline, earnings summary

---

Frontend Integration Guide

Application Startup Flow

1. After successful login, fetch user preferences:

   • Call GET /api/v1/auth/me/preferences
   • Store preferences in global state (Redux, Vuex, Context, etc.)
   • If preferences don't exist, backend automatically creates them with role defaults

2. Apply preferences to UI:

   • Set theme based on theme field (light/dark/auto)
   • Configure language/i18n based on language field
   • Render favorite apps in top navigation bar
   • Configure dashboard widgets
   • Set default table views and pagination sizes

3. Cache preferences locally:

   • Store in localStorage/sessionStorage for quick access
   • Sync with backend on changes
   • Handle offline scenarios gracefully

Settings Page Implementation

Favorite Apps Section:

• Display current favorite apps with drag-to-reorder functionality
• Show "Add App" button that opens modal with available apps
• Validate max 6 apps client-side
• Allow removal of favorites
• Show role-appropriate apps only (fetch from /available-apps endpoint)

Theme Selector:

• Radio buttons or dropdown for Light/Dark/Auto
• Apply theme immediately on change (optimistic UI)
• Save to backend in background

Notification Preferences:

• Toggle switches for each notification type
• Group by delivery method (Email, Push, SMS)
• Show current state from backend
• Update backend on toggle

Dashboard Customization:

• Widget picker showing available widgets for role
• Drag-and-drop to reorder widgets
• Toggle widget visibility
• Save layout to dashboard_widgets field

Table Preferences:

• Dropdown for default view (List/Kanban/Calendar)
• Number input for pagination size (10-100)
• Dropdowns for sort field and order

Navigation Bar Integration

Rendering Favorite Apps:

• Fetch favorite_apps array from preferences
• Map app codes to app metadata (icons, names, routes)
• Render in top navigation or app drawer
• Maintain order from array
• Show all available apps in "All Apps" menu or 9-dot launcher

App Code to Route Mapping:

dashboard -> /dashboard
organizations -> /organizations
users -> /users
tickets -> /tickets
projects -> /projects
sales_orders -> /sales-orders
customers -> /customers
maps -> /map
team -> /team
reports -> /reports
timesheets -> /timesheets
payroll -> /payroll
profile -> /profile
expenses -> /expenses
documents -> /documents
settings -> /settings
billing -> /billing
notifications -> /notifications
help -> /help

Theme Management

Auto Theme Implementation:

• When theme: "auto", detect system preference
• Listen for system theme changes
• Update UI dynamically without backend call
• Only light and dark are stored in backend, auto uses system detection

Theme Application:

• Set CSS variables or toggle theme classes
• Persist across page refreshes
• Apply before first paint to avoid flash

Optimistic Updates

For better UX, update UI immediately before backend confirmation:

1. User changes preference in UI
2. Update local state/UI immediately
3. Call PUT endpoint in background
4. On success: Keep UI as is
5. On error: Revert UI to previous state and show error message

---

Common Use Cases

Use Case 1: Customizing Favorite Apps

User Story: As a platform admin, I want to add "Billing" to my favorite apps.

Implementation Steps:

1. User opens Settings → Favorite Apps
2. Frontend calls GET /api/v1/auth/me/preferences/available-apps to get available apps
3. Display current favorites (4 apps) and available apps (8 apps)
4. User clicks "Add App" → Modal shows available apps not already favorited
5. User selects "billing" → Add to favorites array
6. Frontend calls PUT /api/v1/auth/me/preferences with {"favorite_apps": ["dashboard", "organizations", "users", "activity", "billing"]}
7. Backend validates (max 6, role-appropriate) and saves
8. Frontend updates navigation bar with new favorite

Use Case 2: Toggling Dark Mode

User Story: As a user, I want to switch to dark mode.

Implementation Steps:

1. User clicks theme toggle in header/settings
2. Frontend immediately applies dark theme to UI (optimistic update)
3. Frontend calls PUT /api/v1/auth/me/preferences with {"theme": "dark"}
4. Backend saves preference
5. On next login, dark theme is automatically applied

Use Case 3: Reordering Favorite Apps

User Story: As a dispatcher, I want "maps" to be my first favorite app.

Implementation Steps:

1. User drags "maps" to first position in favorites list
2. Frontend updates array order: ["maps", "dashboard", "tickets", "team"]
3. UI updates immediately (optimistic)
4. Frontend calls PUT /api/v1/auth/me/preferences with new array
5. Backend saves new order
6. Navigation bar reflects new order

Use Case 4: Setting Default Map Center

User Story: As a field agent, I want the map to always center on my region.

Implementation Steps:

1. User navigates map to preferred location
2. User clicks "Set as default center" button
3. Frontend captures current map center coordinates
4. Frontend calls PUT /api/v1/auth/me/preferences with {"default_map_center_lat": -1.2921, "default_map_center_lng": 36.8219, "default_map_zoom": 13}
5. Backend saves preferences
6. On next map load, map centers at saved coordinates with saved zoom level

Use Case 5: Customizing Dashboard

User Story: As a sales manager, I want to see "Conversion Rates" widget on my dashboard.

Implementation Steps:

1. User opens Dashboard Settings
2. Frontend shows available widgets for sales_manager role
3. User toggles "conversion_rates" widget on
4. Frontend updates dashboard_widgets array
5. Frontend calls PUT /api/v1/auth/me/preferences with updated widget list
6. Dashboard re-renders with new widget

---

Error Handling

Common Errors

400 Bad Request - Invalid App for Role:

{
  "detail": "Invalid apps for dispatcher: billing, organizations. Available apps: dashboard, tickets, maps, team, projects, reports, settings, help"
}

Action: Show user which apps are invalid and provide picker with valid apps only.

400 Bad Request - Too Many Favorites:

{
  "detail": "Maximum 6 favorite apps allowed"
}

Action: Disable "Add" button when 6 apps are already favorited, show count (e.g., "5/6 favorites").

400 Bad Request - Invalid Theme:

{
  "detail": "Theme must be one of: light, dark, auto"
}

Action: Use dropdown/radio buttons to prevent invalid values client-side.

401 Unauthorized:

{
  "detail": "Could not validate credentials"
}

Action: Token expired or invalid - redirect to login page.

Error Handling Strategy

1. Validate client-side first - Prevent invalid requests before sending
2. Show specific error messages - Extract detail field from error response
3. Revert optimistic updates - Roll back UI changes if API call fails
4. Retry on network errors - Implement exponential backoff for transient failures
5. Log errors - Track preference update failures for debugging

---

Best Practices

Performance

1. Cache preferences locally - Fetch once on login, update on changes
2. Debounce rapid updates - If user changes multiple settings quickly, batch into single API call
3. Use optimistic updates - Update UI immediately, sync with backend asynchronously
4. Lazy load available apps - Only fetch when user opens app picker modal

User Experience

1. Show loading states - Display skeleton or spinner during fetch
2. Provide immediate feedback - Visual confirmation when settings save
3. Persist across sessions - Store preferences in localStorage as backup
4. Handle offline gracefully - Queue preference updates if offline, sync when online
5. Validate before submission - Check constraints client-side (max 6 apps, valid values)

Security

1. Never cache sensitive data - Clear preferences on logout
2. Validate all inputs - Don't trust client-side validation alone
3. Use HTTPS - Ensure all API calls are over secure connection
4. Handle token expiration - Refresh token or redirect to login gracefully

Accessibility

1. Keyboard navigation - Allow keyboard control of app picker and settings
2. Screen reader support - Announce preference changes
3. High contrast mode - Respect system high contrast preferences
4. Focus management - Return focus appropriately after modal closes

State Management

1. Single source of truth - Store preferences in global state manager
2. Sync with backend - Keep local state in sync with server
3. Handle race conditions - Use timestamps or version numbers to resolve conflicts
4. Broadcast changes - Notify all components when preferences update

---

Example Implementation Flows

Complete Settings Page Flow

Initial Load:

1. Component mounts → Check if preferences in state
2. If not in state → Call GET /api/v1/auth/me/preferences
3. Store in state and render current preferences
4. Enable editing

User Makes Change:

1. User modifies setting (e.g., toggles notification)
2. Update local state immediately (optimistic)
3. Debounce API call (500ms wait for more changes)
4. Call PUT /api/v1/auth/me/preferences with changed fields only
5. On success: Keep optimistic update
6. On error: Revert to previous value, show error toast

Adding Favorite App:

1. User clicks "Add Favorite App" button
2. If favorites.length === 6 → Show "Maximum reached" message
3. Else → Call GET /api/v1/auth/me/preferences/available-apps
4. Filter out already favorited apps
5. Show modal with available apps
6. User selects app → Add to favorites array
7. Update UI immediately
8. Call PUT endpoint with new array
9. On success: Close modal
10. On error: Remove app from array, show error

Theme Toggle Implementation

Toggle Component:

1. Read current theme from preferences state
2. Render toggle switch (Light/Dark) or three-way selector (Light/Dark/Auto)
3. On click:
   • Update UI theme immediately
   • Call PUT /api/v1/auth/me/preferences with {"theme": newTheme}
   • Show loading indicator on toggle
   • On success: Remove loading indicator
   • On error: Revert theme, show error

Auto Theme Handling:

1. If theme is "auto", detect system preference:

   const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
   

2. Apply system theme to UI
3. Listen for changes:

   window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', e => {
     if (preferences.theme === 'auto') {
       applyTheme(e.matches ? 'dark' : 'light')
     }
   })
   

---

Testing Recommendations

Unit Tests

• Test preference state management (Redux/Vuex actions)
• Test validation logic (max 6 apps, valid values)
• Test app code to route mapping
• Test theme application logic

Integration Tests

• Test full settings page flow (fetch → edit → save)
• Test favorite app picker flow
• Test theme toggle with API calls
• Test error handling and rollback

E2E Tests

• Test complete user journey: Login → Change preferences → Logout → Login (preferences persisted)
• Test preference changes reflect across multiple tabs
• Test offline handling and sync on reconnect

---

Migration Guide

If your app currently stores preferences differently:

1. Phase 1: Dual Read - Read from old storage, fallback to new API
2. Phase 2: Migrate Data - Background job to copy old preferences to new system
3. Phase 3: Dual Write - Write to both old and new storage
4. Phase 4: Cut Over - Stop reading from old storage, read from API only
5. Phase 5: Cleanup - Remove old preference storage code

---

Support & Troubleshooting

Common Issues

Issue: Preferences not saving
Solution: Check network tab for API errors, verify authentication token is valid

Issue: Default preferences not created
Solution: Preferences are auto-created on first GET request, ensure user is authenticated

Issue: Theme not applying
Solution: Ensure theme CSS classes/variables are correctly wired to preference value

Issue: Favorite apps showing wrong apps for role
Solution: Fetch available apps from API, don't hardcode app lists in frontend

Debug Checklist

• User is authenticated (valid token)
• API endpoint returns 200 status
• Response data structure matches expected format
• Preferences are stored in state manager
• UI components read from state correctly
• Optimistic updates revert on error
• Error messages are displayed to user

---

API Versioning

Current Version: v1

All endpoints are under /api/v1/auth/me/preferences

Breaking changes will be introduced in new API versions (v2, v3, etc.) with deprecation notices.

---

Changelog

Version 1.0 (Current)

• Initial release
• Support for favorite apps, theme, notifications, dashboard widgets
• Role-based defaults and validation
• Maximum 6 favorite apps constraint

---

Additional Resources

• User Management API: See general user profile endpoints
• Authentication API: Token management and session handling
• Role Definitions: Complete list of roles and permissions

---

Last Updated: November 18, 2025
Maintained By: SwiftOps Backend Team