feat: app management

docs/api/auth/TOKEN_REFRESH_GUIDE.md

@@ -0,0 +1,797 @@
+# Token Refresh & Session Management Guide
+
+## Overview
+
+This guide explains why users get auto-logged out and how to implement robust token refresh logic in your frontend application.
+
+**TL;DR:** Refresh tokens expire after 30 days. You need proactive refresh logic in your frontend to prevent auto-logout.
+
+---
+
+## Table of Contents
+
+1. [Understanding the Problem](#understanding-the-problem)
+2. [How Supabase Tokens Work](#how-supabase-tokens-work)
+3. [Why Users Get Logged Out](#why-users-get-logged-out)
+4. [The Solution](#the-solution)
+5. [Frontend Implementation](#frontend-implementation)
+6. [Backend Behavior](#backend-behavior)
+7. [Testing & Validation](#testing--validation)
+8. [Troubleshooting](#troubleshooting)
+
+---
+
+## Understanding the Problem
+
+### The Error
+
+```
+ERROR: invalid JWT: unable to parse or verify signature, token has invalid claims: token is expired
+```
+
+This error appears when a **refresh token has expired**, not the access token.
+
+### What Happens
+
+1. User logs in → Receives access token (1 hour) + refresh token (30 days)
+2. Access token expires after 1 hour
+3. Frontend tries to refresh using refresh token
+4. **If refresh token is also expired (30+ days old)** → 401 Error → Auto-logout
+
+---
+
+## How Supabase Tokens Work
+
+### Token Types
+
+| Token Type | Lifespan | Purpose | Storage |
+|------------|----------|---------|---------|
+| **Access Token** | 1 hour | Authenticate API requests | Memory/LocalStorage |
+| **Refresh Token** | 30 days | Get new access tokens | LocalStorage (HttpOnly cookies recommended) |
+
+### Token Rotation
+
+Supabase uses **rotating refresh tokens** for security:
+
+- Each time you refresh, you get a **new refresh token**
+- The **old refresh token becomes invalid**
+- This prevents replay attacks
+- If rotation fails (network issues, race conditions), tokens can become invalid
+
+### Storage
+
+After successful login, you receive:
+
+```json
+{
+  "access_token": "eyJhbG...",
+  "refresh_token": "v1.MKh...",
+  "expires_in": 3600,
+  "token_type": "bearer",
+  "user": { ... }
+}
+```
+
+Store in localStorage:
+
+```javascript
+localStorage.setItem('access_token', data.access_token);
+localStorage.setItem('refresh_token', data.refresh_token);
+localStorage.setItem('expires_at', new Date(Date.now() + data.expires_in * 1000).toISOString());
+```
+
+---
+
+## Why Users Get Logged Out
+
+### Scenario 1: Inactivity (Most Common)
+
+- User doesn't use app for 30+ days
+- Refresh token expires
+- Next time they open app → Auto-logout
+
+**Solution:** Display "Your session expired due to inactivity" message
+
+### Scenario 2: Token Rotation Failure
+
+- Network interruption during refresh
+- Race condition (multiple tabs refreshing simultaneously)
+- Old refresh token stored, new one discarded
+
+**Solution:** Implement retry logic and synchronize across tabs
+
+### Scenario 3: No Proactive Refresh
+
+- Frontend waits for 401 error before refreshing
+- User makes request with expired access token
+- Backend returns 401
+- Frontend tries to refresh, but refresh token also expired
+
+**Solution:** Refresh tokens **before** they expire (5 minutes buffer)
+
+### Scenario 4: Multi-Tab/Device Issues
+
+- User opens app in multiple tabs/devices
+- Each tab/device tries to refresh independently
+- Token rotation causes conflicts
+- Tokens become invalid across sessions
+
+**Solution:** Use BroadcastChannel API or shared worker for token sync
+
+---
+
+## The Solution
+
+### Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     FRONTEND                                 │
+│                                                              │
+│  1. Login → Store tokens + Schedule refresh                 │
+│  2. Auto-refresh 5 min before expiry                        │
+│  3. Retry on 401 errors                                     │
+│  4. Sync tokens across tabs                                 │
+│  5. Graceful logout on refresh token expiry                 │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     BACKEND                                  │
+│                                                              │
+│  POST /api/v1/auth/refresh-token                           │
+│  • Validates refresh token with Supabase                   │
+│  • Returns new access + refresh tokens (rotated)           │
+│  • Returns clear error if refresh token expired            │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Key Principles
+
+1. **Proactive Refresh** - Don't wait for 401 errors
+2. **Token Rotation Handling** - Always store new refresh token
+3. **Cross-Tab Sync** - Coordinate token updates across tabs
+4. **Graceful Degradation** - Clear messaging when re-login required
+5. **Retry Logic** - Handle transient failures
+
+---
+
+## Frontend Implementation
+
+### 1. Token Refresh Function
+
+```javascript
+// utils/auth.js
+
+const API_BASE = process.env.REACT_APP_API_URL;
+
+/**
+ * Refresh access token using refresh token
+ * Returns new tokens or null if refresh failed
+ */
+export const refreshTokens = async () => {
+  const refreshToken = localStorage.getItem('refresh_token');
+  
+  if (!refreshToken) {
+    console.warn('No refresh token found');
+    handleLogout();
+    return null;
+  }
+  
+  try {
+    const res = await fetch(`${API_BASE}/auth/refresh-token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refresh_token: refreshToken }),
+    });
+    
+    if (res.ok) {
+      const data = await res.json();
+      
+      // Store new tokens (refresh token is rotated by Supabase)
+      localStorage.setItem('access_token', data.access_token);
+      localStorage.setItem('refresh_token', data.refresh_token);
+      
+      const expiresAt = new Date(Date.now() + data.expires_in * 1000);
+      localStorage.setItem('expires_at', expiresAt.toISOString());
+      
+      console.log('✅ Tokens refreshed successfully');
+      
+      // Broadcast to other tabs
+      broadcastTokenUpdate(data);
+      
+      // Schedule next refresh
+      scheduleTokenRefresh(expiresAt);
+      
+      return data;
+    } else if (res.status === 401) {
+      // Refresh token expired
+      const error = await res.json();
+      console.error('Refresh token expired:', error.detail);
+      
+      // Show user-friendly message
+      showToast('Your session has expired. Please log in again.', 'warning');
+      
+      handleLogout();
+      return null;
+    } else {
+      throw new Error(`Refresh failed: ${res.status}`);
+    }
+  } catch (error) {
+    console.error('Token refresh error:', error);
+    handleLogout();
+    return null;
+  }
+};
+
+/**
+ * Logout user and clear all tokens
+ */
+const handleLogout = () => {
+  localStorage.removeItem('access_token');
+  localStorage.removeItem('refresh_token');
+  localStorage.removeItem('expires_at');
+  
+  // Redirect to login
+  window.location.href = '/login';
+};
+```
+
+### 2. Proactive Token Refresh Scheduler
+
+```javascript
+// utils/auth.js
+
+let refreshTimeout = null;
+
+/**
+ * Schedule automatic token refresh before expiration
+ * @param {Date|string} expiresAt - Token expiration timestamp
+ */
+export const scheduleTokenRefresh = (expiresAt) => {
+  // Clear any existing timeout
+  if (refreshTimeout) {
+    clearTimeout(refreshTimeout);
+  }
+  
+  const now = Date.now();
+  const expiresAtMs = new Date(expiresAt).getTime();
+  const timeUntilExpiry = expiresAtMs - now;
+  
+  // Refresh 5 minutes (300000ms) before expiration
+  const BUFFER_TIME = 5 * 60 * 1000;
+  const refreshTime = timeUntilExpiry - BUFFER_TIME;
+  
+  if (refreshTime > 0) {
+    console.log(`🕐 Token refresh scheduled in ${Math.round(refreshTime / 1000 / 60)} minutes`);
+    
+    refreshTimeout = setTimeout(async () => {
+      console.log('⏰ Auto-refreshing token...');
+      await refreshTokens();
+    }, refreshTime);
+  } else {
+    // Token already expired or expires very soon - refresh immediately
+    console.log('⚠️ Token expired or expiring soon, refreshing now...');
+    refreshTokens();
+  }
+};
+
+/**
+ * Initialize token refresh on app startup
+ */
+export const initializeTokenRefresh = () => {
+  const expiresAt = localStorage.getItem('expires_at');
+  
+  if (expiresAt) {
+    scheduleTokenRefresh(expiresAt);
+  } else {
+    console.warn('No token expiration found');
+  }
+};
+```
+
+### 3. Cross-Tab Token Synchronization
+
+```javascript
+// utils/auth.js
+
+/**
+ * Broadcast token updates to other tabs/windows
+ */
+const broadcastTokenUpdate = (tokenData) => {
+  // Use BroadcastChannel API (modern browsers)
+  if ('BroadcastChannel' in window) {
+    const channel = new BroadcastChannel('auth_channel');
+    channel.postMessage({
+      type: 'TOKEN_UPDATED',
+      data: tokenData
+    });
+  }
+  
+  // Fallback: localStorage events
+  localStorage.setItem('token_update_event', JSON.stringify({
+    timestamp: Date.now(),
+    data: tokenData
+  }));
+};
+
+/**
+ * Listen for token updates from other tabs
+ */
+export const setupTokenSyncListener = () => {
+  // BroadcastChannel listener
+  if ('BroadcastChannel' in window) {
+    const channel = new BroadcastChannel('auth_channel');
+    channel.onmessage = (event) => {
+      if (event.data.type === 'TOKEN_UPDATED') {
+        console.log('📡 Received token update from another tab');
+        scheduleTokenRefresh(localStorage.getItem('expires_at'));
+      }
+    };
+  }
+  
+  // localStorage listener (fallback)
+  window.addEventListener('storage', (event) => {
+    if (event.key === 'token_update_event' && event.newValue) {
+      console.log('📡 Received token update via storage event');
+      scheduleTokenRefresh(localStorage.getItem('expires_at'));
+    }
+  });
+};
+```
+
+### 4. API Interceptor for 401 Errors
+
+```javascript
+// utils/api.js
+
+import axios from 'axios';
+import { refreshTokens } from './auth';
+
+const api = axios.create({
+  baseURL: process.env.REACT_APP_API_URL,
+});
+
+// Request interceptor - Add access token to all requests
+api.interceptors.request.use(
+  (config) => {
+    const accessToken = localStorage.getItem('access_token');
+    if (accessToken) {
+      config.headers.Authorization = `Bearer ${accessToken}`;
+    }
+    return config;
+  },
+  (error) => Promise.reject(error)
+);
+
+// Response interceptor - Auto-retry on 401 with token refresh
+api.interceptors.response.use(
+  (response) => response,
+  async (error) => {
+    const originalRequest = error.config;
+    
+    // If 401 and not already retried
+    if (error.response?.status === 401 && !originalRequest._retry) {
+      originalRequest._retry = true;
+      
+      console.log('🔄 401 error detected, attempting token refresh...');
+      
+      const newTokens = await refreshTokens();
+      
+      if (newTokens) {
+        // Update authorization header with new token
+        originalRequest.headers.Authorization = `Bearer ${newTokens.access_token}`;
+        
+        // Retry original request
+        return api(originalRequest);
+      } else {
+        // Refresh failed - user will be logged out by refreshTokens()
+        return Promise.reject(error);
+      }
+    }
+    
+    return Promise.reject(error);
+  }
+);
+
+export default api;
+```
+
+### 5. Login Flow Integration
+
+```javascript
+// pages/Login.jsx
+
+import { refreshTokens, scheduleTokenRefresh, setupTokenSyncListener } from '../utils/auth';
+
+const handleLogin = async (email, password) => {
+  try {
+    const res = await fetch(`${API_BASE}/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, password }),
+    });
+    
+    if (res.ok) {
+      const data = await res.json();
+      
+      // Store tokens
+      localStorage.setItem('access_token', data.access_token);
+      localStorage.setItem('refresh_token', data.refresh_token);
+      
+      const expiresAt = new Date(Date.now() + data.expires_in * 1000);
+      localStorage.setItem('expires_at', expiresAt.toISOString());
+      
+      // Schedule automatic refresh
+      scheduleTokenRefresh(expiresAt);
+      
+      // Setup cross-tab sync
+      setupTokenSyncListener();
+      
+      // Navigate to dashboard
+      navigate('/dashboard');
+    } else {
+      // Handle error
+      const error = await res.json();
+      showToast(error.detail, 'error');
+    }
+  } catch (error) {
+    console.error('Login error:', error);
+    showToast('Login failed. Please try again.', 'error');
+  }
+};
+```
+
+### 6. App Initialization
+
+```javascript
+// App.jsx or main.jsx
+
+import { initializeTokenRefresh, setupTokenSyncListener } from './utils/auth';
+
+function App() {
+  useEffect(() => {
+    // Check if user is logged in
+    const accessToken = localStorage.getItem('access_token');
+    
+    if (accessToken) {
+      // Initialize automatic token refresh
+      initializeTokenRefresh();
+      
+      // Setup cross-tab synchronization
+      setupTokenSyncListener();
+    }
+  }, []);
+  
+  return <Router>...</Router>;
+}
+```
+
+---
+
+## Backend Behavior
+
+### Endpoint: POST /api/v1/auth/refresh-token
+
+**Request:**
+```json
+{
+  "refresh_token": "v1.MKh..."
+}
+```
+
+**Success Response (200):**
+```json
+{
+  "access_token": "eyJhbG...",
+  "refresh_token": "v1.XYz...",
+  "expires_in": 3600,
+  "token_type": "bearer",
+  "user": {
+    "id": "uuid",
+    "email": "user@example.com",
+    "first_name": "John",
+    "last_name": "Doe",
+    "full_name": "John Doe",
+    "role": "platform_admin",
+    "is_active": true
+  }
+}
+```
+
+**Error Responses:**
+
+| Status Code | Error | Meaning | Frontend Action |
+|-------------|-------|---------|-----------------|
+| 401 | `Refresh token expired. Please log in again.` | Refresh token is expired (30+ days old) | Logout user, redirect to login with message |
+| 401 | `Token refresh failed: <error>` | Network or Supabase error | Retry once, then logout if still fails |
+| 404 | `User account no longer exists` | User deleted from database | Logout user, show account deletion message |
+| 403 | `Account is inactive. Contact support.` | User account deactivated | Logout user, show contact support message |
+
+### Backend Implementation Details
+
+The backend:
+1. Validates refresh token with Supabase
+2. Returns **rotated tokens** (new refresh token on each call)
+3. Verifies user still exists and is active
+4. Provides clear, actionable error messages
+5. Logs all refresh attempts for security monitoring
+
+**Important:** The backend does NOT store tokens in a database. Supabase manages all token storage and validation. The backend simply validates tokens and returns new ones.
+
+---
+
+## Testing & Validation
+
+### Test Case 1: Normal Token Refresh
+
+**Steps:**
+1. Login to application
+2. Wait 55 minutes (or modify expiry for testing)
+3. Make API request
+4. Verify auto-refresh happens
+5. Verify new tokens stored in localStorage
+
+**Expected:** No logout, seamless refresh
+
+### Test Case 2: Expired Refresh Token
+
+**Steps:**
+1. Login to application
+2. Manually expire refresh token (modify timestamp or wait 30 days)
+3. Try to make API request
+4. Verify 401 error from backend
+5. Verify user redirected to login with message
+
+**Expected:** Graceful logout with "Session expired" message
+
+### Test Case 3: Multi-Tab Sync
+
+**Steps:**
+1. Open app in Tab A and Tab B
+2. Login in Tab A
+3. Verify Tab B receives token update
+4. Let token expire in Tab A
+5. Verify Tab B also logs out
+
+**Expected:** Both tabs stay synchronized
+
+### Test Case 4: Network Failure During Refresh
+
+**Steps:**
+1. Login to application
+2. Disable network
+3. Wait for auto-refresh time
+4. Verify retry logic activates
+5. Re-enable network
+6. Verify refresh succeeds
+
+**Expected:** Retry successful, no logout
+
+### Test Case 5: Race Condition (Multiple Refreshes)
+
+**Steps:**
+1. Login to application
+2. Trigger multiple API calls simultaneously when token is about to expire
+3. Verify only one refresh request sent
+4. Verify all pending requests use new token
+
+**Expected:** No duplicate refresh calls, all requests succeed
+
+---
+
+## Troubleshooting
+
+### Issue: Users Still Getting Auto-Logged Out
+
+**Diagnosis Steps:**
+
+1. **Check localStorage:**
+   ```javascript
+   console.log('Access Token:', localStorage.getItem('access_token'));
+   console.log('Refresh Token:', localStorage.getItem('refresh_token'));
+   console.log('Expires At:', localStorage.getItem('expires_at'));
+   ```
+
+2. **Check if refresh is scheduled:**
+   ```javascript
+   // Add to scheduleTokenRefresh function
+   console.log('Refresh scheduled for:', new Date(expiresAt).toLocaleString());
+   ```
+
+3. **Check backend logs:**
+   - Look for `Token refreshed successfully` (success)
+   - Look for `Token refresh error` (failure)
+   - Check error details for root cause
+
+4. **Verify token rotation:**
+   - After refresh, refresh_token should be different
+   - If same token returned, rotation may be disabled
+
+5. **Check Supabase settings:**
+   - Verify JWT expiry settings in Supabase dashboard
+   - Confirm refresh token rotation is enabled
+
+### Common Mistakes
+
+❌ **Mistake 1:** Waiting for 401 before refreshing
+```javascript
+// BAD - Reactive
+api.interceptors.response.use(null, async (error) => {
+  if (error.response.status === 401) {
+    await refreshTokens();
+  }
+});
+```
+
+✅ **Fix:** Proactive refresh before expiry
+```javascript
+// GOOD - Proactive
+scheduleTokenRefresh(expiresAt);
+```
+
+❌ **Mistake 2:** Not storing new refresh token
+```javascript
+// BAD - Old token reused
+localStorage.setItem('access_token', data.access_token);
+// Missing: localStorage.setItem('refresh_token', data.refresh_token);
+```
+
+✅ **Fix:** Always update both tokens
+```javascript
+// GOOD - Both tokens updated
+localStorage.setItem('access_token', data.access_token);
+localStorage.setItem('refresh_token', data.refresh_token);
+```
+
+❌ **Mistake 3:** Not handling 401 on refresh endpoint
+```javascript
+// BAD - Infinite loop
+if (res.status === 401) {
+  await refreshTokens(); // Calls itself
+}
+```
+
+✅ **Fix:** Logout on refresh failure
+```javascript
+// GOOD - Break loop
+if (res.status === 401) {
+  handleLogout();
+}
+```
+
+### Debug Checklist
+
+- [ ] Refresh token is stored in localStorage
+- [ ] scheduleTokenRefresh is called after login
+- [ ] Timeout is set (check browser console)
+- [ ] New tokens stored after refresh
+- [ ] API interceptor configured correctly
+- [ ] 401 errors trigger refresh attempt
+- [ ] Failed refresh triggers logout
+- [ ] Cross-tab sync working (optional but recommended)
+- [ ] Error messages displayed to user
+- [ ] Backend logs show refresh attempts
+
+---
+
+## Best Practices Summary
+
+### DO ✅
+
+- **Refresh proactively** 5 minutes before expiry
+- **Store new refresh token** after each refresh
+- **Schedule next refresh** after successful refresh
+- **Synchronize across tabs** using BroadcastChannel
+- **Handle 401 gracefully** with retry logic
+- **Show clear messages** when re-login required
+- **Log all token operations** for debugging
+- **Test token expiry scenarios** thoroughly
+
+### DON'T ❌
+
+- **Don't wait for 401** to refresh tokens
+- **Don't ignore new refresh token** from response
+- **Don't refresh on every 401** (check if not already refreshing)
+- **Don't store tokens in cookies** unless using HttpOnly
+- **Don't create database table** for tokens (Supabase handles this)
+- **Don't show technical errors** to users
+- **Don't refresh more than once** for same expiry
+- **Don't forget to clear tokens** on logout
+
+---
+
+## Security Considerations
+
+### Token Storage
+
+**LocalStorage (Current Implementation):**
+- ✅ Simple to implement
+- ✅ Persists across page refreshes
+- ❌ Vulnerable to XSS attacks
+- ❌ Accessible to all scripts
+
+**HttpOnly Cookies (Recommended for Production):**
+- ✅ Not accessible to JavaScript (XSS protection)
+- ✅ Automatically sent with requests
+- ✅ Can set secure and sameSite flags
+- ❌ Requires backend cookie handling
+
+**In-Memory Storage (Most Secure):**
+- ✅ Not vulnerable to XSS
+- ✅ Cleared on page refresh
+- ❌ Poor UX (users logged out on refresh)
+- ❌ Doesn't work with multi-tab sync
+
+### Token Rotation
+
+Supabase automatically rotates refresh tokens for security:
+- Each refresh returns a **new refresh token**
+- Old refresh token becomes **invalid**
+- Prevents token replay attacks
+- Reduces impact of stolen tokens
+
+### Monitoring
+
+Log these events for security monitoring:
+- Login attempts (success/failure)
+- Token refresh attempts (success/failure)
+- Logout events (user-initiated vs. auto-logout)
+- Multiple failed refresh attempts (potential attack)
+- Token expiry patterns (identify inactive users)
+
+---
+
+## Migration Guide
+
+If you're currently experiencing auto-logout issues:
+
+### Phase 1: Immediate Fix (Frontend)
+
+1. Add proactive token refresh scheduler
+2. Update token after each refresh
+3. Add 401 error interceptor
+4. Test with short expiry times
+
+### Phase 2: Enhanced UX
+
+1. Add cross-tab synchronization
+2. Show clear expiry messages
+3. Add retry logic for network failures
+4. Implement token refresh progress indicator
+
+### Phase 3: Production Hardening
+
+1. Switch to HttpOnly cookies (optional)
+2. Add security monitoring/logging
+3. Implement token refresh rate limiting
+4. Add user session management dashboard
+
+---
+
+## Additional Resources
+
+- **Supabase Auth Docs:** https://supabase.com/docs/guides/auth
+- **JWT Best Practices:** https://tools.ietf.org/html/rfc8725
+- **Token Refresh Patterns:** https://auth0.com/docs/secure/tokens/refresh-tokens
+- **BroadcastChannel API:** https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel
+
+---
+
+## Support
+
+If you continue experiencing issues:
+
+1. Enable debug logging in frontend
+2. Check backend logs for refresh attempts
+3. Verify Supabase project settings
+4. Test with curl/Postman to isolate frontend vs. backend issues
+5. Check for browser extensions blocking requests
+
+---
+
+**Last Updated:** November 18, 2025  
+**Maintained By:** SwiftOps Backend Team  
+**Related Docs:** AUTH_API_COMPLETE.md, GETTING_STARTED_AUTH.md

docs/api/user-profile/APP_MANAGEMENT_SYSTEM.md

@@ -0,0 +1,648 @@
+# App Management System Documentation
+
+## Overview
+
+The SwiftOps platform uses a centralized **App Management System** that defines all applications, controls role-based access, and manages user favorites. This system ensures consistency between backend permissions and frontend navigation.
+
+**Key Features:**
+- Single source of truth for all apps (`app.config.apps`)
+- Role-based access control (8 roles, 22 apps)
+- Rich app metadata (name, icon, route, category, description)
+- User-customizable favorites (max 6 per user)
+- Category-based organization
+- Permission-based access control
+
+---
+
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [App Definition](#app-definition)
+3. [API Endpoints](#api-endpoints)
+4. [Frontend Integration](#frontend-integration)
+5. [Adding New Apps](#adding-new-apps)
+6. [Role Configuration](#role-configuration)
+7. [Best Practices](#best-practices)
+
+---
+
+## Architecture Overview
+
+### System Components
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   app.config.apps.py                         │
+│  • APPS: Dict of all app definitions (22 apps)              │
+│  • ROLE_APP_ACCESS: Role-to-apps mapping (8 roles)         │
+│  • DEFAULT_FAVORITE_APPS: Initial favorites per role        │
+│  • Helper functions: validate, get, filter                   │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   API Endpoints                              │
+│  • GET  /api/v1/auth/apps                                   │
+│    Returns all apps with access info                        │
+│                                                              │
+│  • GET  /api/v1/auth/me/preferences/available-apps         │
+│    Returns apps user can favorite                           │
+│                                                              │
+│  • PUT  /api/v1/auth/me/preferences                        │
+│    Update favorite apps (validated against role)            │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Frontend                                   │
+│  • Navigation bar (shows favorite apps)                     │
+│  • App launcher/drawer (shows all accessible apps)          │
+│  • Settings page (customize favorites)                      │
+│  • Route protection (based on role access)                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Data Flow
+
+1. **Backend** defines all apps in `app.config.apps.py`
+2. **API** exposes apps with role-based filtering
+3. **Frontend** fetches apps and renders navigation
+4. **User** customizes favorites (stored in `user_preferences` table)
+5. **System** validates favorites against role permissions
+
+---
+
+## App Definition
+
+### AppDefinition Class
+
+Each app is defined with rich metadata:
+
+```python
+class AppDefinition:
+    code: str                    # Unique identifier (e.g., "dashboard")
+    name: str                    # Display name (e.g., "Dashboard")
+    description: str             # Brief description
+    icon: str                    # Icon name from icon library
+    route: str                   # Frontend route (e.g., "/dashboard")
+    category: AppCategory        # Category for grouping
+    requires_permission: str     # Optional specific permission
+    is_active: bool             # Whether app is currently available
+```
+
+### App Categories
+
+Apps are organized into 6 categories:
+
+| Category | Purpose | Example Apps |
+|----------|---------|--------------|
+| **Core** | Essential platform features | Dashboard, Organizations, Users, Activity |
+| **Operations** | Field operations & ticketing | Tickets, Projects, Maps, Contractors |
+| **Sales** | Sales & customer management | Sales Orders, Customers, Reports |
+| **Team** | Team management & scheduling | Team, Timesheets |
+| **Finance** | Financial management | Payroll, Billing, Expenses |
+| **Settings** | Configuration & support | Settings, Profile, Help, Notifications |
+
+### Example App Definition
+
+```python
+"dashboard": AppDefinition(
+    code="dashboard",
+    name="Dashboard",
+    description="Overview of key metrics and activities",
+    icon="dashboard",
+    route="/dashboard",
+    category=AppCategory.CORE
+)
+```
+
+---
+
+## API Endpoints
+
+### 1. Get All Apps
+
+**Endpoint:** `GET /api/v1/auth/apps`
+
+**Description:** Returns all apps in the system with role-based access information.
+
+**Authentication:** Required (Bearer token)
+
+**Response:**
+
+```json
+{
+  "user_role": "platform_admin",
+  "total_apps": 22,
+  "accessible_apps": 8,
+  "apps": [
+    {
+      "code": "dashboard",
+      "name": "Dashboard",
+      "description": "Overview of key metrics and activities",
+      "icon": "dashboard",
+      "route": "/dashboard",
+      "category": "core",
+      "requires_permission": null,
+      "is_active": true,
+      "has_access": true
+    },
+    {
+      "code": "payroll",
+      "name": "Payroll",
+      "description": "Payroll management and processing",
+      "icon": "dollar-sign",
+      "route": "/payroll",
+      "category": "finance",
+      "requires_permission": "view_payroll",
+      "is_active": true,
+      "has_access": false
+    }
+    // ... 20 more apps
+  ],
+  "apps_by_category": {
+    "core": [...],
+    "operations": [...],
+    "sales": [...],
+    "team": [...],
+    "finance": [...],
+    "settings": [...]
+  },
+  "categories": ["core", "operations", "sales", "team", "finance", "settings"]
+}
+```
+
+**Use Cases:**
+- Render main navigation menu
+- Build app launcher/drawer
+- Generate accessible routes for user
+- Show app directory with categories
+
+---
+
+### 2. Get Available Apps for Favorites
+
+**Endpoint:** `GET /api/v1/auth/me/preferences/available-apps`
+
+**Description:** Returns apps user can add to favorites (role-filtered).
+
+**Authentication:** Required (Bearer token)
+
+**Response:**
+
+```json
+{
+  "role": "platform_admin",
+  "current_favorites": ["dashboard", "organizations", "users", "activity"],
+  "available_apps": [
+    {
+      "code": "dashboard",
+      "name": "Dashboard",
+      "description": "Overview of key metrics and activities",
+      "icon": "dashboard",
+      "route": "/dashboard",
+      "category": "core",
+      "requires_permission": null,
+      "is_active": true
+    },
+    // ... 7 more apps user can favorite
+  ],
+  "default_favorites": ["dashboard", "organizations", "users", "activity"],
+  "max_favorites": 6
+}
+```
+
+**Use Cases:**
+- Populate app picker in settings
+- Show which apps can be favorited
+- Validate favorites client-side
+
+---
+
+### 3. Update User Preferences (Including Favorites)
+
+**Endpoint:** `PUT /api/v1/auth/me/preferences`
+
+**Description:** Update user preferences including favorite apps.
+
+**Authentication:** Required (Bearer token)
+
+**Request Body:**
+
+```json
+{
+  "favorite_apps": ["dashboard", "tickets", "maps", "projects", "reports", "help"]
+}
+```
+
+**Validation Rules:**
+- Maximum 6 apps
+- Apps must be in user's available apps list (role-based)
+- Invalid apps return 400 error with details
+
+**Response:** Updated preferences object
+
+**Error Example:**
+
+```json
+{
+  "detail": "Invalid apps for field_agent: dashboard, organizations. Available apps: tickets, maps, timesheets, profile, expenses, documents, help"
+}
+```
+
+---
+
+## Frontend Integration
+
+### 1. Fetch All Apps on Login
+
+```javascript
+// After successful login, fetch all apps
+const fetchApps = async () => {
+  const res = await api.get('/auth/apps');
+  const data = res.data;
+  
+  // Store in state
+  dispatch(setApps({
+    all: data.apps,
+    byCategory: data.apps_by_category,
+    accessible: data.apps.filter(app => app.has_access)
+  }));
+};
+```
+
+### 2. Render Navigation with Favorites
+
+```javascript
+// Navigation Bar Component
+const NavigationBar = () => {
+  const { preferences } = useAuth();
+  const { all: allApps } = useApps();
+  
+  // Get favorite app objects
+  const favoriteApps = preferences.favorite_apps
+    .map(code => allApps.find(app => app.code === code))
+    .filter(app => app && app.has_access);
+  
+  return (
+    <nav>
+      {favoriteApps.map(app => (
+        <NavLink key={app.code} to={app.route}>
+          <Icon name={app.icon} />
+          <span>{app.name}</span>
+        </NavLink>
+      ))}
+      <AppLauncherButton /> {/* Shows all accessible apps */}
+    </nav>
+  );
+};
+```
+
+### 3. App Launcher/Drawer
+
+```javascript
+// App Launcher Component
+const AppLauncher = () => {
+  const { accessible: accessibleApps, byCategory } = useApps();
+  
+  return (
+    <Drawer>
+      <h2>All Apps</h2>
+      {Object.entries(byCategory).map(([category, apps]) => (
+        <AppCategory key={category} name={category}>
+          {apps
+            .filter(app => app.has_access)
+            .map(app => (
+              <AppTile
+                key={app.code}
+                icon={app.icon}
+                name={app.name}
+                description={app.description}
+                onClick={() => navigate(app.route)}
+              />
+            ))}
+        </AppCategory>
+      ))}
+    </Drawer>
+  );
+};
+```
+
+### 4. Favorite Apps Customizer
+
+```javascript
+// Settings Page - Favorite Apps Section
+const FavoriteAppsSettings = () => {
+  const [availableApps, setAvailableApps] = useState([]);
+  const [favorites, setFavorites] = useState([]);
+  
+  useEffect(() => {
+    // Fetch available apps
+    api.get('/auth/me/preferences/available-apps').then(res => {
+      setAvailableApps(res.data.available_apps);
+      setFavorites(res.data.current_favorites);
+    });
+  }, []);
+  
+  const addFavorite = (appCode) => {
+    if (favorites.length >= 6) {
+      toast.error('Maximum 6 favorites allowed');
+      return;
+    }
+    
+    const newFavorites = [...favorites, appCode];
+    updateFavorites(newFavorites);
+  };
+  
+  const removeFavorite = (appCode) => {
+    const newFavorites = favorites.filter(code => code !== appCode);
+    updateFavorites(newFavorites);
+  };
+  
+  const updateFavorites = async (newFavorites) => {
+    try {
+      await api.put('/auth/me/preferences', {
+        favorite_apps: newFavorites
+      });
+      setFavorites(newFavorites);
+      toast.success('Favorites updated');
+    } catch (error) {
+      toast.error(error.response?.data?.detail || 'Update failed');
+    }
+  };
+  
+  return (
+    <div>
+      <h3>Favorite Apps ({favorites.length}/6)</h3>
+      
+      {/* Current Favorites - Draggable to reorder */}
+      <DragDropContext onDragEnd={handleReorder}>
+        <Droppable droppableId="favorites">
+          {availableApps
+            .filter(app => favorites.includes(app.code))
+            .map((app, index) => (
+              <Draggable key={app.code} draggableId={app.code} index={index}>
+                <AppCard
+                  icon={app.icon}
+                  name={app.name}
+                  onRemove={() => removeFavorite(app.code)}
+                />
+              </Draggable>
+            ))}
+        </Droppable>
+      </DragDropContext>
+      
+      {/* Available to Add */}
+      <h4>Add Apps</h4>
+      <div>
+        {availableApps
+          .filter(app => !favorites.includes(app.code))
+          .map(app => (
+            <AppCard
+              key={app.code}
+              icon={app.icon}
+              name={app.name}
+              description={app.description}
+              onAdd={() => addFavorite(app.code)}
+            />
+          ))}
+      </div>
+    </div>
+  );
+};
+```
+
+### 5. Route Protection
+
+```javascript
+// Protected Route Component
+const ProtectedRoute = ({ appCode, children }) => {
+  const { accessible: accessibleApps } = useApps();
+  
+  const hasAccess = accessibleApps.some(app => app.code === appCode);
+  
+  if (!hasAccess) {
+    return <Navigate to="/unauthorized" />;
+  }
+  
+  return children;
+};
+
+// Usage in Router
+<Route path="/payroll" element={
+  <ProtectedRoute appCode="payroll">
+    <PayrollPage />
+  </ProtectedRoute>
+} />
+```
+
+---
+
+## Adding New Apps
+
+### Step 1: Define App in `app.config.apps.py`
+
+```python
+"new_app": AppDefinition(
+    code="new_app",
+    name="New App",
+    description="Description of what this app does",
+    icon="icon-name",  # From your icon library
+    route="/new-app",
+    category=AppCategory.OPERATIONS,  # or SALES, TEAM, etc.
+    requires_permission="view_new_app",  # Optional
+    is_active=True
+)
+```
+
+### Step 2: Add to Role Access
+
+```python
+ROLE_APP_ACCESS = {
+    "platform_admin": [
+        # ... existing apps ...
+        "new_app"  # Add here
+    ],
+    "client_admin": [
+        # ... existing apps ...
+        "new_app"  # Add here if this role should access it
+    ],
+    # ... other roles ...
+}
+```
+
+### Step 3: (Optional) Add to Default Favorites
+
+```python
+DEFAULT_FAVORITE_APPS = {
+    "platform_admin": ["dashboard", "organizations", "users", "new_app"],
+    # ... other roles ...
+}
+```
+
+### Step 4: Frontend Route
+
+Create the frontend page and add route:
+
+```javascript
+<Route path="/new-app" element={
+  <ProtectedRoute appCode="new_app">
+    <NewAppPage />
+  </ProtectedRoute>
+} />
+```
+
+**That's it!** The app will automatically:
+- Appear in `/auth/apps` endpoint
+- Be available for favoriting (if role has access)
+- Show up in app launcher
+- Be protected by route guards
+
+---
+
+## Role Configuration
+
+### Current Roles and App Access
+
+| Role | Accessible Apps | Default Favorites |
+|------|----------------|-------------------|
+| **Platform Admin** | 8 apps: Dashboard, Organizations, Users, Activity, Settings, Billing, Notifications, Help | Dashboard, Organizations, Users, Activity |
+| **Client Admin** | 10 apps: Dashboard, Projects, Tickets, Team, Sales Orders, Customers, Contractors, Reports, Settings, Help | Dashboard, Projects, Tickets, Team |
+| **Contractor Admin** | 9 apps: Dashboard, Projects, Tickets, Team, Timesheets, Payroll, Reports, Settings, Help | Dashboard, Projects, Tickets, Team |
+| **Sales Manager** | 8 apps: Dashboard, Sales Orders, Customers, Reports, Team, Maps, Settings, Help | Dashboard, Sales Orders, Customers, Reports |
+| **Project Manager** | 8 apps: Dashboard, Projects, Tickets, Team, Reports, Maps, Settings, Help | Dashboard, Projects, Tickets, Team |
+| **Dispatcher** | 8 apps: Dashboard, Tickets, Maps, Team, Projects, Reports, Settings, Help | Dashboard, Tickets, Maps, Team |
+| **Field Agent** | 7 apps: Tickets, Maps, Timesheets, Profile, Expenses, Documents, Help | Tickets, Maps, Timesheets, Profile |
+| **Sales Agent** | 7 apps: Dashboard, Sales Orders, Customers, Maps, Profile, Reports, Help | Dashboard, Sales Orders, Customers, Maps |
+
+### Modifying Role Access
+
+To give a role access to a new app:
+
+```python
+ROLE_APP_ACCESS = {
+    "field_agent": [
+        "tickets", "maps", "timesheets",
+        "profile", "expenses", "documents",
+        "help",
+        "reports"  # Add new app here
+    ]
+}
+```
+
+---
+
+## Best Practices
+
+### Backend
+
+1. **Always define apps in `app.config.apps`** - Never hardcode app lists elsewhere
+2. **Use helper functions** - `validate_apps_for_role()`, `get_available_apps_for_role()`
+3. **Validate favorites on update** - Prevent users from favoriting apps they can't access
+4. **Keep categories consistent** - Use predefined `AppCategory` enum
+5. **Add permissions for sensitive apps** - Use `requires_permission` field
+
+### Frontend
+
+1. **Fetch apps once on login** - Cache in state management (Redux/Zuex/Context)
+2. **Filter by `has_access`** - Never show apps user can't access
+3. **Use app metadata** - Don't duplicate names, icons, routes in frontend
+4. **Respect max favorites (6)** - Validate client-side before API call
+5. **Handle reordering** - Allow drag-and-drop for favorites
+6. **Show categories** - Group apps logically in launcher/drawer
+7. **Protect routes** - Use `ProtectedRoute` component with app codes
+
+### UX Guidelines
+
+1. **Navigation Bar** - Show 4-6 favorite apps (most used)
+2. **App Launcher** - Show all accessible apps grouped by category
+3. **Settings Page** - Allow customization with drag-and-drop
+4. **Tooltips** - Show app descriptions on hover
+5. **Empty State** - Show helpful message if user has no favorites
+6. **Max Indicator** - Show "4/6 favorites" counter
+7. **Disabled Apps** - Grey out apps in launcher if `is_active: false`
+
+---
+
+## Migration Guide
+
+If you're migrating from hardcoded app lists:
+
+### Phase 1: Backend Migration
+
+1. Move all app definitions to `app.config.apps.py`
+2. Update imports in `auth.py` endpoints
+3. Replace hardcoded lists with helper functions
+4. Test all preference endpoints
+
+### Phase 2: Frontend Migration
+
+1. Update API calls to use `/auth/apps` endpoint
+2. Replace hardcoded app arrays with API data
+3. Update navigation components to use app metadata
+4. Test favorites customization
+
+### Phase 3: Cleanup
+
+1. Remove old app constants from codebase
+2. Update documentation
+3. Remove unused imports
+4. Add tests for app management
+
+---
+
+## Troubleshooting
+
+### Issue: User can't favorite an app
+
+**Check:**
+1. Is app in `ROLE_APP_ACCESS` for user's role?
+2. Is app `is_active: true`?
+3. Has user reached max 6 favorites?
+4. Is app code spelled correctly (lowercase with underscores)?
+
+### Issue: App shows in launcher but route is 404
+
+**Check:**
+1. Is frontend route defined?
+2. Does route path match `app.route` in definition?
+3. Is route wrapped in `ProtectedRoute`?
+
+### Issue: Wrong apps showing for role
+
+**Check:**
+1. User's role in database (check `users.role` field)
+2. Role exists in `ROLE_APP_ACCESS` dictionary
+3. App codes are spelled correctly
+
+---
+
+## API Reference Summary
+
+| Endpoint | Method | Auth | Purpose |
+|----------|--------|------|---------|
+| `/api/v1/auth/apps` | GET | Required | Get all apps with access info |
+| `/api/v1/auth/me/preferences/available-apps` | GET | Required | Get apps user can favorite |
+| `/api/v1/auth/me/preferences` | GET | Required | Get user preferences |
+| `/api/v1/auth/me/preferences` | PUT | Required | Update user preferences |
+
+---
+
+## Future Enhancements
+
+### Planned Features
+
+1. **App Permissions** - Granular permissions beyond role-based
+2. **Custom Apps** - Allow organizations to add custom apps
+3. **App Marketplace** - Third-party app integrations
+4. **Usage Analytics** - Track which apps users access most
+5. **Dynamic Icons** - Load icons from CDN/database
+6. **App Versioning** - Support multiple versions of same app
+7. **Feature Flags** - Enable/disable apps per organization
+8. **App Bundles** - Predefined app collections for common use cases
+
+---
+
+**Last Updated:** November 18, 2025  
+**Maintained By:** SwiftOps Backend Team  
+**Related Docs:** USER_PREFERENCES_API.md, AUTH_API_COMPLETE.md

src/app/api/v1/auth.py

@@ -15,7 +15,15 @@ from app.schemas.user import (
 )
 from app.schemas.user_preferences import (
     UserPreferencesUpdate, UserPreferencesResponse,
-    DEFAULT_FAVORITE_APPS, AVAILABLE_APPS, DEFAULT_DASHBOARD_WIDGETS
+    DEFAULT_DASHBOARD_WIDGETS
+)
+from app.config.apps import (
+    get_available_apps_for_role,
+    get_available_app_codes_for_role,
+    get_default_favorites_for_role,
+    validate_apps_for_role,
+    get_app_by_code,
+    APPS
 )
 from app.models.user_preference import UserPreference
 from app.models.user import User
@@ -833,9 +841,10 @@ async def get_my_preferences(
     
     # If no preferences exist, create with role-based defaults
     if not preferences:
+        default_favorites = get_default_favorites_for_role(current_user.role)
         preferences = UserPreference(
             user_id=current_user.id,
-            favorite_apps=DEFAULT_FAVORITE_APPS.get(current_user.role, ['dashboard', 'tickets', 'projects', 'maps']),
+            favorite_apps=default_favorites,
             dashboard_widgets=DEFAULT_DASHBOARD_WIDGETS.get(current_user.role, ['recent_tickets', 'team_performance', 'sla_metrics']),
             theme='light',
             language='en'
@@ -843,7 +852,7 @@ async def get_my_preferences(
         db.add(preferences)
         db.commit()
         db.refresh(preferences)
-        logger.info(f"Created default preferences for user: {current_user.email}")
+        logger.info(f"✅ Created default preferences for user: {current_user.email} (role: {current_user.role})")
     
     return UserPreferencesResponse.from_orm(preferences)
 
@@ -868,10 +877,11 @@ async def update_my_preferences(
     ).first()
     
     if not preferences:
-        # Create new preferences record
+        # Create new preferences record with role-based defaults
+        default_favorites = get_default_favorites_for_role(current_user.role)
         preferences = UserPreference(
             user_id=current_user.id,
-            favorite_apps=DEFAULT_FAVORITE_APPS.get(current_user.role, []),
+            favorite_apps=default_favorites,
             dashboard_widgets=DEFAULT_DASHBOARD_WIDGETS.get(current_user.role, [])
         )
         db.add(preferences)
@@ -893,10 +903,10 @@ async def update_my_preferences(
             )
         
         # Validate against role-specific available apps
-        available_apps = AVAILABLE_APPS.get(current_user.role, [])
-        invalid_apps = [app for app in update_data['favorite_apps'] if app not in available_apps]
+        is_valid, invalid_apps = validate_apps_for_role(update_data['favorite_apps'], current_user.role)
         
-        if invalid_apps:
+        if not is_valid:
+            available_apps = get_available_app_codes_for_role(current_user.role)
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
                 detail=f"Invalid apps for {current_user.role}: {', '.join(invalid_apps)}. "
@@ -938,15 +948,23 @@ async def update_my_preferences(
 
 
 @router.get("/me/preferences/available-apps", response_model=dict)
-async def get_available_apps(
+async def get_available_apps_for_user(
     current_user: User = Depends(get_current_active_user),
     db: Session = Depends(get_db)
 ):
     """
     Get list of apps available for user to favorite based on their role
     
-    Returns currently favorited apps, all available apps for the role,
-    and role-based default favorites.
+    **Returns:**
+    - Current favorite app codes
+    - All available apps with full metadata (name, icon, route, etc.)
+    - Default favorites for the role
+    - Maximum favorites allowed (6)
+    
+    **Use Cases:**
+    - Populate app picker in settings UI
+    - Show which apps can be added/removed from favorites
+    - Display role-appropriate app options with icons and descriptions
     """
     # Get current preferences
     preferences = db.query(UserPreference).filter(
@@ -954,12 +972,77 @@ async def get_available_apps(
         UserPreference.deleted_at == None
     ).first()
     
-    current_favorites = preferences.favorite_apps if preferences else DEFAULT_FAVORITE_APPS.get(current_user.role, [])
+    # Get current favorites or defaults
+    current_favorites = preferences.favorite_apps if preferences else get_default_favorites_for_role(current_user.role)
+    
+    # Get available apps with full metadata
+    available_app_objects = get_available_apps_for_role(current_user.role)
+    available_apps_detail = [app.to_dict() for app in available_app_objects]
+    
+    # Get default favorites
+    default_favorites = get_default_favorites_for_role(current_user.role)
     
     return {
         "role": current_user.role,
         "current_favorites": current_favorites,
-        "available_apps": AVAILABLE_APPS.get(current_user.role, []),
-        "default_favorites": DEFAULT_FAVORITE_APPS.get(current_user.role, []),
+        "available_apps": available_apps_detail,  # Full app metadata
+        "default_favorites": default_favorites,
         "max_favorites": 6
     }
+
+
+@router.get("/apps", response_model=dict)
+async def get_all_apps_for_user(
+    current_user: User = Depends(get_current_active_user)
+):
+    """
+    Get ALL apps in the system with role-based access information
+    
+    **Returns:**
+    - All apps with full metadata (name, description, icon, route, category)
+    - User's role and which apps they can access
+    - Categorized app groupings (Core, Operations, Sales, Team, Finance, Settings)
+    
+    **Use Cases:**
+    - Render main navigation menu with all accessible apps
+    - Show app launcher/drawer with categories
+    - Display app directory or marketplace
+    - Generate sitemap for user's accessible routes
+    
+    **Frontend Integration:**
+    - Filter apps by `has_access: true` to show only accessible apps
+    - Group apps by `category` for organized navigation
+    - Use `icon` and `route` to render navigation items
+    - Show disabled state for apps where `has_access: false`
+    """
+    from app.config.apps import get_all_apps, AppCategory
+    
+    # Get all apps in the system
+    all_apps = get_all_apps()
+    
+    # Get apps user has access to
+    accessible_app_codes = set(get_available_app_codes_for_role(current_user.role))
+    
+    # Build response with access information
+    apps_with_access = []
+    for app in all_apps:
+        app_dict = app.to_dict()
+        app_dict['has_access'] = app.code in accessible_app_codes
+        apps_with_access.append(app_dict)
+    
+    # Group by category
+    apps_by_category = {}
+    for category in AppCategory:
+        apps_by_category[category.value] = [
+            app for app in apps_with_access
+            if app['category'] == category.value
+        ]
+    
+    return {
+        "user_role": current_user.role,
+        "total_apps": len(all_apps),
+        "accessible_apps": len(accessible_app_codes),
+        "apps": apps_with_access,
+        "apps_by_category": apps_by_category,
+        "categories": [cat.value for cat in AppCategory]
+    }

src/app/config/apps.py

@@ -0,0 +1,442 @@
+"""
+Application Configuration
+Defines all apps in the system with metadata, permissions, and role-based access
+"""
+from typing import Dict, List, Optional
+from enum import Enum
+
+
+class AppCategory(str, Enum):
+    """App categories for organization"""
+    CORE = "core"
+    OPERATIONS = "operations"
+    SALES = "sales"
+    TEAM = "team"
+    FINANCE = "finance"
+    SETTINGS = "settings"
+
+
+class AppDefinition:
+    """
+    Application definition with metadata
+    
+    Attributes:
+        code: Unique app code (lowercase with underscores)
+        name: Display name
+        description: Brief description of the app
+        icon: Icon name (from your icon library)
+        route: Frontend route path
+        category: App category for grouping
+        requires_permission: Optional specific permission required
+        is_active: Whether app is currently available
+    """
+    
+    def __init__(
+        self,
+        code: str,
+        name: str,
+        description: str,
+        icon: str,
+        route: str,
+        category: AppCategory,
+        requires_permission: Optional[str] = None,
+        is_active: bool = True
+    ):
+        self.code = code
+        self.name = name
+        self.description = description
+        self.icon = icon
+        self.route = route
+        self.category = category
+        self.requires_permission = requires_permission
+        self.is_active = is_active
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary for API responses"""
+        return {
+            "code": self.code,
+            "name": self.name,
+            "description": self.description,
+            "icon": self.icon,
+            "route": self.route,
+            "category": self.category.value,
+            "requires_permission": self.requires_permission,
+            "is_active": self.is_active
+        }
+
+
+# ============================================================
+# ALL APPS DEFINITION - Single Source of Truth
+# ============================================================
+
+APPS: Dict[str, AppDefinition] = {
+    # CORE APPS
+    "dashboard": AppDefinition(
+        code="dashboard",
+        name="Dashboard",
+        description="Overview of key metrics and activities",
+        icon="dashboard",
+        route="/dashboard",
+        category=AppCategory.CORE
+    ),
+    
+    "organizations": AppDefinition(
+        code="organizations",
+        name="Organizations",
+        description="Manage client and contractor organizations",
+        icon="building",
+        route="/organizations",
+        category=AppCategory.CORE,
+        requires_permission="view_organizations"
+    ),
+    
+    "users": AppDefinition(
+        code="users",
+        name="Users",
+        description="User management and permissions",
+        icon="users",
+        route="/users",
+        category=AppCategory.CORE,
+        requires_permission="view_users"
+    ),
+    
+    "activity": AppDefinition(
+        code="activity",
+        name="Activity Log",
+        description="System-wide audit trail and activity monitoring",
+        icon="activity",
+        route="/activity",
+        category=AppCategory.CORE,
+        requires_permission="view_audit_logs"
+    ),
+    
+    # OPERATIONS
+    "tickets": AppDefinition(
+        code="tickets",
+        name="Tickets",
+        description="Service tickets and work orders",
+        icon="ticket",
+        route="/tickets",
+        category=AppCategory.OPERATIONS
+    ),
+    
+    "projects": AppDefinition(
+        code="projects",
+        name="Projects",
+        description="Project management and tracking",
+        icon="folder",
+        route="/projects",
+        category=AppCategory.OPERATIONS
+    ),
+    
+    "maps": AppDefinition(
+        code="maps",
+        name="Maps",
+        description="Field operations map view",
+        icon="map",
+        route="/map",
+        category=AppCategory.OPERATIONS
+    ),
+    
+    "contractors": AppDefinition(
+        code="contractors",
+        name="Contractors",
+        description="Contractor management and assignments",
+        icon="hard-hat",
+        route="/contractors",
+        category=AppCategory.OPERATIONS,
+        requires_permission="view_contractors"
+    ),
+    
+    # SALES
+    "sales_orders": AppDefinition(
+        code="sales_orders",
+        name="Sales Orders",
+        description="Sales order management and tracking",
+        icon="shopping-cart",
+        route="/sales-orders",
+        category=AppCategory.SALES,
+        requires_permission="view_sales_orders"
+    ),
+    
+    "customers": AppDefinition(
+        code="customers",
+        name="Customers",
+        description="Customer relationship management",
+        icon="users",
+        route="/customers",
+        category=AppCategory.SALES,
+        requires_permission="view_customers"
+    ),
+    
+    "reports": AppDefinition(
+        code="reports",
+        name="Reports",
+        description="Analytics and reporting",
+        icon="chart-bar",
+        route="/reports",
+        category=AppCategory.OPERATIONS
+    ),
+    
+    # TEAM MANAGEMENT
+    "team": AppDefinition(
+        code="team",
+        name="Team",
+        description="Team member management and scheduling",
+        icon="users",
+        route="/team",
+        category=AppCategory.TEAM
+    ),
+    
+    "timesheets": AppDefinition(
+        code="timesheets",
+        name="Timesheets",
+        description="Time tracking and attendance",
+        icon="clock",
+        route="/timesheets",
+        category=AppCategory.TEAM
+    ),
+    
+    "payroll": AppDefinition(
+        code="payroll",
+        name="Payroll",
+        description="Payroll management and processing",
+        icon="dollar-sign",
+        route="/payroll",
+        category=AppCategory.FINANCE,
+        requires_permission="view_payroll"
+    ),
+    
+    # PERSONAL
+    "profile": AppDefinition(
+        code="profile",
+        name="My Profile",
+        description="Personal profile and settings",
+        icon="user",
+        route="/profile",
+        category=AppCategory.SETTINGS
+    ),
+    
+    "expenses": AppDefinition(
+        code="expenses",
+        name="Expenses",
+        description="Expense reporting and reimbursement",
+        icon="receipt",
+        route="/expenses",
+        category=AppCategory.FINANCE
+    ),
+    
+    "documents": AppDefinition(
+        code="documents",
+        name="Documents",
+        description="Document management and storage",
+        icon="file-text",
+        route="/documents",
+        category=AppCategory.OPERATIONS
+    ),
+    
+    # SETTINGS & ADMIN
+    "settings": AppDefinition(
+        code="settings",
+        name="Settings",
+        description="Application settings and preferences",
+        icon="settings",
+        route="/settings",
+        category=AppCategory.SETTINGS
+    ),
+    
+    "billing": AppDefinition(
+        code="billing",
+        name="Billing",
+        description="Billing and subscription management",
+        icon="credit-card",
+        route="/billing",
+        category=AppCategory.FINANCE,
+        requires_permission="view_billing"
+    ),
+    
+    "notifications": AppDefinition(
+        code="notifications",
+        name="Notifications",
+        description="Notification center and alerts",
+        icon="bell",
+        route="/notifications",
+        category=AppCategory.CORE
+    ),
+    
+    "help": AppDefinition(
+        code="help",
+        name="Help & Support",
+        description="Documentation and support resources",
+        icon="help-circle",
+        route="/help",
+        category=AppCategory.SETTINGS
+    ),
+}
+
+
+# ============================================================
+# ROLE-BASED ACCESS - Defines which apps each role can access
+# ============================================================
+
+ROLE_APP_ACCESS: Dict[str, List[str]] = {
+    "platform_admin": [
+        # Core admin apps
+        "dashboard", "organizations", "users", "activity",
+        # Management & settings
+        "settings", "billing", "notifications", "help"
+    ],
+    
+    "client_admin": [
+        # Core operations
+        "dashboard", "projects", "tickets", "team",
+        # Sales & customers
+        "sales_orders", "customers",
+        # Contractor management
+        "contractors",
+        # Analytics & settings
+        "reports", "settings", "help"
+    ],
+    
+    "contractor_admin": [
+        # Core operations
+        "dashboard", "projects", "tickets", "team",
+        # Time & payroll
+        "timesheets", "payroll",
+        # Analytics & settings
+        "reports", "settings", "help"
+    ],
+    
+    "sales_manager": [
+        # Sales focus
+        "dashboard", "sales_orders", "customers",
+        # Operations support
+        "team", "maps", "reports",
+        # Settings
+        "settings", "help"
+    ],
+    
+    "project_manager": [
+        # Project operations
+        "dashboard", "projects", "tickets", "team",
+        # Field operations
+        "maps", "reports",
+        # Settings
+        "settings", "help"
+    ],
+    
+    "dispatcher": [
+        # Dispatch operations
+        "dashboard", "tickets", "maps", "team",
+        # Operations support
+        "projects", "reports",
+        # Settings
+        "settings", "help"
+    ],
+    
+    "field_agent": [
+        # Field operations
+        "tickets", "maps", "timesheets",
+        # Personal
+        "profile", "expenses", "documents",
+        # Support
+        "help"
+    ],
+    
+    "sales_agent": [
+        # Sales operations
+        "dashboard", "sales_orders", "customers", "maps",
+        # Personal
+        "profile", "reports",
+        # Support
+        "help"
+    ]
+}
+
+
+# ============================================================
+# DEFAULT FAVORITE APPS - Initial favorites for each role
+# ============================================================
+
+DEFAULT_FAVORITE_APPS: Dict[str, List[str]] = {
+    "platform_admin": ["dashboard", "organizations", "users", "activity"],
+    "client_admin": ["dashboard", "projects", "tickets", "team"],
+    "contractor_admin": ["dashboard", "projects", "tickets", "team"],
+    "sales_manager": ["dashboard", "sales_orders", "customers", "reports"],
+    "project_manager": ["dashboard", "projects", "tickets", "team"],
+    "dispatcher": ["dashboard", "tickets", "maps", "team"],
+    "field_agent": ["tickets", "maps", "timesheets", "profile"],
+    "sales_agent": ["dashboard", "sales_orders", "customers", "maps"]
+}
+
+
+# ============================================================
+# HELPER FUNCTIONS
+# ============================================================
+
+def get_app_by_code(app_code: str) -> Optional[AppDefinition]:
+    """Get app definition by code"""
+    return APPS.get(app_code)
+
+
+def get_apps_by_codes(app_codes: List[str]) -> List[AppDefinition]:
+    """Get multiple app definitions by codes"""
+    return [APPS[code] for code in app_codes if code in APPS]
+
+
+def get_available_apps_for_role(role: str) -> List[AppDefinition]:
+    """
+    Get all apps available for a specific role
+    
+    Args:
+        role: User role (e.g., 'platform_admin', 'field_agent')
+    
+    Returns:
+        List of AppDefinition objects for the role
+    """
+    app_codes = ROLE_APP_ACCESS.get(role, [])
+    return get_apps_by_codes(app_codes)
+
+
+def get_available_app_codes_for_role(role: str) -> List[str]:
+    """Get list of app codes available for a role"""
+    return ROLE_APP_ACCESS.get(role, [])
+
+
+def get_default_favorites_for_role(role: str) -> List[str]:
+    """Get default favorite app codes for a role"""
+    return DEFAULT_FAVORITE_APPS.get(role, [])
+
+
+def validate_apps_for_role(app_codes: List[str], role: str) -> tuple[bool, List[str]]:
+    """
+    Validate that app codes are available for the given role
+    
+    Args:
+        app_codes: List of app codes to validate
+        role: User role
+    
+    Returns:
+        Tuple of (is_valid, invalid_apps)
+        - is_valid: True if all apps are valid for role
+        - invalid_apps: List of invalid app codes
+    """
+    available_apps = set(get_available_app_codes_for_role(role))
+    invalid_apps = [code for code in app_codes if code not in available_apps]
+    
+    return (len(invalid_apps) == 0, invalid_apps)
+
+
+def get_apps_by_category(category: AppCategory) -> List[AppDefinition]:
+    """Get all apps in a specific category"""
+    return [app for app in APPS.values() if app.category == category]
+
+
+def get_all_app_codes() -> List[str]:
+    """Get list of all app codes in the system"""
+    return list(APPS.keys())
+
+
+def get_all_apps() -> List[AppDefinition]:
+    """Get list of all app definitions"""
+    return list(APPS.values())

src/app/schemas/user_preferences.py

@@ -144,57 +144,8 @@ class UserPreferencesResponse(BaseModel):
         }
 
 
-# Default favorite apps by role (using database app codes - lowercase with underscores)
-DEFAULT_FAVORITE_APPS = {
-    "platform_admin": ["dashboard", "organizations", "users", "activity"],
-    "client_admin": ["dashboard", "projects", "tickets", "team"],
-    "contractor_admin": ["dashboard", "projects", "tickets", "team"],
-    "sales_manager": ["dashboard", "sales_orders", "customers", "reports"],
-    "project_manager": ["dashboard", "projects", "tickets", "team"],
-    "dispatcher": ["dashboard", "tickets", "maps", "team"],
-    "field_agent": ["tickets", "maps", "timesheets", "profile"],
-    "sales_agent": ["dashboard", "sales_orders", "customers", "maps"]
-}
-
-# Available apps by role (what they can favorite - max 6)
-AVAILABLE_APPS = {
-    "platform_admin": [
-        # Core apps
-        "dashboard", "organizations", "users", "activity",
-        # Management
-        "settings", "billing", "notifications", "help"
-    ],
-    "client_admin": [
-        "dashboard", "projects", "tickets", "team", "sales_orders",
-        "customers", "contractors", "reports", "settings", "help"
-    ],
-    "contractor_admin": [
-        "dashboard", "projects", "tickets", "team", "timesheets",
-        "payroll", "reports", "settings", "help"
-    ],
-    "sales_manager": [
-        "dashboard", "sales_orders", "customers", "reports",
-        "team", "maps", "settings", "help"
-    ],
-    "project_manager": [
-        "dashboard", "projects", "tickets", "team", "reports",
-        "maps", "settings", "help"
-    ],
-    "dispatcher": [
-        "dashboard", "tickets", "maps", "team", "projects",
-        "reports", "settings", "help"
-    ],
-    "field_agent": [
-        "tickets", "maps", "timesheets", "profile", "expenses",
-        "documents", "help"
-    ],
-    "sales_agent": [
-        "dashboard", "sales_orders", "customers", "maps",
-        "profile", "reports", "help"
-    ]
-}
-
 # Available dashboard widgets by role
+# Note: DEFAULT_FAVORITE_APPS and AVAILABLE_APPS moved to app.config.apps
 DEFAULT_DASHBOARD_WIDGETS = {
     "platform_admin": ["recent_tickets", "team_performance", "sla_metrics", "organizations_overview"],
     "client_admin": ["recent_tickets", "team_performance", "sla_metrics", "project_status"],