feat: add meta_apps config and include in login and preferences endpoints for project role navigation context

docs/agent/thoughts/frontend.md

@@ -0,0 +1,433 @@
+# Frontend Team - Navigation & App Context Requirements
+
+**Date:** 2025-11-21  
+**Topic:** Project Selection & Context-Aware App Navigation  
+**Status:** Pending Backend Implementation
+
+---
+
+## Problem Statement
+
+We've implemented a project selection system for project-based roles (Project Manager, Sales Manager, Dispatcher, Field Agent). These users now have two distinct contexts:
+
+1. **Outside Project Context**: `/dashboard` - Project selection view
+2. **Inside Project Context**: `/project/:projectId` - Project-specific dashboard
+
+Currently, the navigation system shows all available apps regardless of context. This creates a poor UX because:
+- Users see project-specific apps (Tickets, Inventory, Map, etc.) when they're on the project selection screen
+- These apps are not functional without a project context
+- It's confusing and cluttered
+
+## Proposed Solution
+
+We need the **backend to provide context-aware app lists** based on user role and current context.
+
+---
+
+## Backend API Requirements
+
+### Current API Response Structure
+```json
+GET /api/v1/users/me/preferences
+
+{
+  "available_apps": [
+    { "code": "dashboard", "name": "Dashboard", "route": "/dashboard" },
+    { "code": "tickets", "name": "Tickets", "route": "/tickets" },
+    { "code": "settings", "name": "Settings", "route": "/settings" },
+    // ... all apps
+  ],
+  "current_favorites": ["dashboard", "tickets", "inventory"],
+  "default_favorites": ["dashboard", "tickets", "map"]
+}
+```
+
+### Proposed API Response Structure
+```json
+GET /api/v1/users/me/preferences
+
+{
+  "available_apps": [
+    { "code": "dashboard", "name": "Dashboard", "route": "/dashboard" },
+    { "code": "tickets", "name": "Tickets", "route": "/tickets" },
+    { "code": "inventory", "name": "Inventory", "route": "/inventory" },
+    { "code": "settings", "name": "Settings", "route": "/settings" },
+    { "code": "help", "name": "Help", "route": "/help" },
+    // ... all apps user has access to
+  ],
+  
+  "meta_apps": [
+    "dashboard",
+    "settings", 
+    "help",
+    "notifications",
+    "search"
+  ],
+  
+  "current_favorites": ["dashboard", "tickets", "inventory"],
+  "default_favorites": ["dashboard", "tickets", "map"]
+}
+```
+
+---
+
+## App Categorization by Role
+
+### For Project-Based Roles (PM, Sales Manager, Dispatcher, Field Agent)
+
+**Meta Apps** (Available outside project context):
+- `dashboard` - For returning to project selection
+- `settings` - User preferences
+- `help` - Help & support
+- `notifications` - User notifications
+- `search` - Global search (if applicable)
+
+**Project Apps** (Only available inside project context):
+- `tickets` - Work orders/tickets
+- `inventory` - Inventory management
+- `map` - Map view
+- `finance` - Financial data
+- `expenses` - Expense tracking
+- `payroll` - Payroll (if applicable)
+- `team` - Team management
+- `projects` - Project list (might be meta for some roles)
+- `reports` - Reporting
+- `customers` - Customer management
+- `documents` - Document management
+
+### For Admin Roles (Platform Admin, Client Admin, Contractor Admin)
+
+**All apps are always available** - No context switching needed.
+
+Their apps might include:
+- `dashboard` - Admin dashboard
+- `organizations` - Organization management (Platform Admin)
+- `users` - User management
+- `activity` - Activity logs
+- `billing` - Billing (Platform Admin)
+- `invitations` - User invitations
+- `team` - Team management (Org Admins)
+- `projects` - Project management (Org Admins)
+- `settings` - Settings
+- `help` - Help
+
+---
+
+## Backend Implementation Requirements
+
+### 1. Add `meta_apps` Field to User Preferences Response
+
+The backend should return a `meta_apps` array that lists app codes that are available **outside** of a project context.
+
+**Logic:**
+- For **project-based roles**: Return a curated list of meta apps
+- For **admin roles**: Return empty array `[]` or all apps (since they don't have context switching)
+
+### 2. Role-Based Meta Apps Configuration
+
+Create a configuration mapping for each role:
+
+```python
+# Example backend configuration
+META_APPS_BY_ROLE = {
+    'project_manager': ['dashboard', 'settings', 'help', 'notifications', 'search'],
+    'sales_manager': ['dashboard', 'settings', 'help', 'notifications', 'search'],
+    'dispatcher': ['dashboard', 'settings', 'help', 'notifications', 'search'],
+    'field_agent': ['dashboard', 'settings', 'help', 'notifications', 'search'],
+    
+    # Admin roles - no context switching, so empty or all apps
+    'platform_admin': [],
+    'client_admin': [],
+    'contractor_admin': [],
+}
+```
+
+### 3. Update Preferences Endpoint
+
+**Endpoint:** `GET /api/v1/users/me/preferences`
+
+**Response Schema:**
+```typescript
+{
+  available_apps: Array<{
+    code: string;
+    name: string;
+    route: string;
+  }>;
+  
+  meta_apps: string[];  // NEW FIELD - Array of app codes available outside project context
+  
+  current_favorites: string[];
+  default_favorites: string[];
+}
+```
+
+### 4. Validation Rules
+
+- `meta_apps` should only contain codes that exist in `available_apps`
+- For admin roles, `meta_apps` can be empty or contain all app codes
+- For project-based roles, `meta_apps` should be a subset of `available_apps`
+
+---
+
+## Frontend Implementation Plan
+
+Once the backend provides `meta_apps`, we'll implement the following:
+
+### 1. Detect Project Context
+
+```typescript
+// In a new hook or context
+const location = useLocation();
+const isInProjectContext = location.pathname.startsWith('/project/');
+```
+
+### 2. Filter Apps in StickyHeader
+
+```typescript
+const visibleFavoriteApps = useMemo(() => {
+  const { meta_apps } = availableApps;
+  const isProjectBasedRole = !['platform_admin', 'client_admin', 'contractor_admin'].includes(user.role);
+  
+  // If outside project context and user is project-based role
+  if (!isInProjectContext && isProjectBasedRole) {
+    // Show only meta apps from favorites
+    return accessibleFavoriteApps.filter(app => meta_apps.includes(app.code));
+  }
+  
+  // Otherwise show all favorites
+  return accessibleFavoriteApps;
+}, [isInProjectContext, user.role, accessibleFavoriteApps, availableApps.meta_apps]);
+```
+
+### 3. Filter Apps in AppLauncher
+
+```typescript
+const visibleApps = useMemo(() => {
+  const { meta_apps } = availableApps;
+  const isProjectBasedRole = !['platform_admin', 'client_admin', 'contractor_admin'].includes(user.role);
+  
+  // If outside project context and user is project-based role
+  if (!isInProjectContext && isProjectBasedRole) {
+    // Show only meta apps
+    return accessibleApps.filter(app => meta_apps.includes(app.code));
+  }
+  
+  // Otherwise show all apps
+  return accessibleApps;
+}, [isInProjectContext, user.role, accessibleApps, availableApps.meta_apps]);
+```
+
+### 4. Handle Favorites
+
+**Important:** When a user is outside a project context, their favorite apps should still be **saved** but just **not displayed** if they're project apps.
+
+**Behavior:**
+- User sets favorites: `['dashboard', 'tickets', 'inventory', 'settings']`
+- Outside project context: Only show `['dashboard', 'settings']` (meta apps)
+- Inside project context: Show all `['dashboard', 'tickets', 'inventory', 'settings']`
+
+This ensures when they enter a project, their favorites are immediately available.
+
+---
+
+## User Experience Flow
+
+### Scenario 1: PM Logs In (Multiple Projects)
+
+1. **Login** → Lands on `/dashboard` (project selection)
+2. **Header Pills**: Shows only meta apps from favorites (e.g., Dashboard, Settings)
+3. **App Launcher**: Shows only meta apps (Dashboard, Settings, Help, Notifications)
+4. **User selects project** → Navigates to `/project/abc-123`
+5. **Header Pills**: Now shows ALL favorites (Dashboard, Tickets, Inventory, Settings)
+6. **App Launcher**: Shows ALL available apps
+
+### Scenario 2: PM with Single Project (Auto-Navigate)
+
+1. **Login** → Lands on `/dashboard`
+2. **Auto-navigates** to `/project/abc-123` (single project)
+3. **Header Pills**: Shows all favorites immediately
+4. **App Launcher**: Shows all apps immediately
+5. **User never sees the restricted view** (seamless experience)
+
+### Scenario 3: Admin Logs In
+
+1. **Login** → Lands on `/dashboard` (admin dashboard)
+2. **Header Pills**: Shows all favorites (no filtering)
+3. **App Launcher**: Shows all apps (no filtering)
+4. **No context switching** - always sees everything
+
+---
+
+## Benefits of Backend-Driven Approach
+
+### 1. **Centralized Logic**
+- App categorization lives in one place (backend)
+- Easy to update which apps are meta vs project-specific
+- No hardcoded lists in frontend
+
+### 2. **Role Flexibility**
+- Different roles can have different meta apps
+- Easy to add new roles with custom meta app lists
+- Backend controls access, frontend just displays
+
+### 3. **Consistency**
+- Same logic applies to all frontend components
+- No risk of frontend/backend mismatch
+- Single source of truth
+
+### 4. **Scalability**
+- Easy to add new app types in the future
+- Can introduce more context levels if needed
+- Frontend code stays simple
+
+### 5. **Security**
+- Backend enforces what apps are available
+- Frontend can't accidentally show unauthorized apps
+- Access control remains server-side
+
+---
+
+## Migration & Backward Compatibility
+
+### Phase 1: Backend Update
+- Add `meta_apps` field to preferences response
+- Populate based on user role
+- Ensure existing fields remain unchanged
+
+### Phase 2: Frontend Update
+- Update `useUserPreferences` types to include `meta_apps`
+- Implement filtering logic in StickyHeader
+- Implement filtering logic in AppLauncher
+- Add context detection
+
+### Phase 3: Testing
+- Test all role types
+- Test project context switching
+- Test favorite app persistence
+- Test edge cases (direct URLs, bookmarks)
+
+### Backward Compatibility
+- If `meta_apps` is missing or empty, show all apps (current behavior)
+- No breaking changes for existing users
+- Gradual rollout possible
+
+---
+
+## Open Questions for Backend Team
+
+1. **Should `meta_apps` be role-based or user-specific?**
+   - Recommendation: Role-based for consistency, but allow user overrides if needed
+
+2. **Should `projects` app be meta or project-specific?**
+   - For PM: Probably meta (they manage multiple projects)
+   - For Field Agent: Probably project-specific (they work in one project at a time)
+
+3. **Should `dashboard` always be in meta apps?**
+   - Yes - users need a way to return to project selection
+
+4. **How to handle apps that work in both contexts?**
+   - Example: `search` might work globally or within a project
+   - Recommendation: If it works outside project, include in meta apps
+
+5. **Should we support per-user customization of meta apps?**
+   - Or is role-based sufficient?
+   - Recommendation: Start with role-based, add user customization later if needed
+
+---
+
+## Example API Responses by Role
+
+### Project Manager
+```json
+{
+  "available_apps": [
+    { "code": "dashboard", "name": "Dashboard", "route": "/dashboard" },
+    { "code": "tickets", "name": "Tickets", "route": "/tickets" },
+    { "code": "inventory", "name": "Inventory", "route": "/inventory" },
+    { "code": "map", "name": "Map", "route": "/map" },
+    { "code": "finance", "name": "Finance", "route": "/finance" },
+    { "code": "team", "name": "Team", "route": "/team" },
+    { "code": "reports", "name": "Reports", "route": "/reports" },
+    { "code": "settings", "name": "Settings", "route": "/settings" },
+    { "code": "help", "name": "Help", "route": "/help" },
+    { "code": "notifications", "name": "Notifications", "route": "/notifications" }
+  ],
+  "meta_apps": ["dashboard", "settings", "help", "notifications"],
+  "current_favorites": ["dashboard", "tickets", "inventory", "map"],
+  "default_favorites": ["dashboard", "tickets", "inventory", "map"]
+}
+```
+
+### Platform Admin
+```json
+{
+  "available_apps": [
+    { "code": "dashboard", "name": "Dashboard", "route": "/dashboard" },
+    { "code": "organizations", "name": "Organizations", "route": "/organizations" },
+    { "code": "users", "name": "Users", "route": "/users" },
+    { "code": "activity", "name": "Activity", "route": "/activity" },
+    { "code": "billing", "name": "Billing", "route": "/billing" },
+    { "code": "invitations", "name": "Invitations", "route": "/invitations" },
+    { "code": "settings", "name": "Settings", "route": "/settings" },
+    { "code": "help", "name": "Help", "route": "/help" }
+  ],
+  "meta_apps": [],  // Empty - no context switching for admins
+  "current_favorites": ["dashboard", "organizations", "users"],
+  "default_favorites": ["dashboard", "organizations", "users"]
+}
+```
+
+### Field Agent
+```json
+{
+  "available_apps": [
+    { "code": "dashboard", "name": "Dashboard", "route": "/dashboard" },
+    { "code": "tickets", "name": "Tickets", "route": "/tickets" },
+    { "code": "map", "name": "Map", "route": "/map" },
+    { "code": "inventory", "name": "Inventory", "route": "/inventory" },
+    { "code": "settings", "name": "Settings", "route": "/settings" },
+    { "code": "help", "name": "Help", "route": "/help" }
+  ],
+  "meta_apps": ["dashboard", "settings", "help"],
+  "current_favorites": ["tickets", "map", "inventory"],
+  "default_favorites": ["tickets", "map", "inventory"]
+}
+```
+
+---
+
+## Summary
+
+**What we need from backend:**
+1. Add `meta_apps: string[]` field to `/api/v1/users/me/preferences` response
+2. Populate `meta_apps` based on user role
+3. For project-based roles: Include apps that work outside project context
+4. For admin roles: Empty array or all apps (no context switching)
+
+**What frontend will do:**
+1. Detect if user is in project context (via route)
+2. Filter favorite apps in header based on `meta_apps` when outside project
+3. Filter all apps in launcher based on `meta_apps` when outside project
+4. Show all apps normally when inside project or for admin roles
+
+**Result:**
+- Clean UX for project selection
+- No irrelevant apps shown
+- Seamless transition when entering/exiting projects
+- Backend controls app categorization
+- Frontend just displays what backend provides
+
+---
+
+**Next Steps:**
+1. Backend team reviews this proposal
+2. Backend implements `meta_apps` field
+3. Frontend team updates filtering logic
+4. QA tests all role types and contexts
+5. Deploy and monitor
+
+---
+
+**Contact:** Frontend Team  
+**For Questions:** Please review and provide feedback on the proposed API changes

src/app/api/v1/auth.py

@@ -21,6 +21,7 @@ from app.config.apps import (
     get_available_apps_for_role,
     get_available_app_codes_for_role,
     get_default_favorites_for_role,
+    get_meta_apps_for_role,
     validate_apps_for_role,
     get_app_by_code,
     APPS
@@ -518,6 +519,9 @@ async def login_full(
         # Step 4: Get available apps
         available_apps = get_available_apps_for_role(user.role)
         
+        # Step 4b: Get meta apps (apps available outside project context)
+        meta_apps = get_meta_apps_for_role(user.role)
+        
         # Step 5: Audit log (async, doesn't block response)
         AuditService.log_auth_event(
             db=db,
@@ -548,7 +552,8 @@ async def login_full(
                 "contractor_id": str(user.contractor_id) if user.contractor_id else None,
             },
             "preferences": preferences,
-            "available_apps": available_apps
+            "available_apps": available_apps,
+            "meta_apps": meta_apps
         }
         
     except HTTPException:
@@ -1237,11 +1242,15 @@ async def get_available_apps_for_user(
     # Get default favorites
     default_favorites = get_default_favorites_for_role(current_user.role)
     
+    # Get meta apps (apps available outside project context)
+    meta_apps = get_meta_apps_for_role(current_user.role)
+    
     return {
         "role": current_user.role,
         "current_favorites": current_favorites,
         "available_apps": available_apps_detail,  # Full app metadata
         "default_favorites": default_favorites,
+        "meta_apps": meta_apps,  # Apps available outside project context
         "max_favorites": 6
     }
 

src/app/config/apps.py

@@ -431,6 +431,26 @@ DEFAULT_FAVORITE_APPS: Dict[str, List[str]] = {
 }
 
 
+# ============================================================
+# META APPS - Apps available outside project context
+# Used for context-aware navigation in project-based roles
+# ============================================================
+
+META_APPS_BY_ROLE: Dict[str, List[str]] = {
+    # Project-based roles: Only show context-independent apps outside project
+    "project_manager": ["dashboard", "settings", "notifications", "help"],
+    "sales_manager": ["dashboard", "settings", "notifications", "help"],
+    "dispatcher": ["dashboard", "settings", "notifications", "help"],
+    "field_agent": ["dashboard", "settings", "notifications", "help"],
+    "sales_agent": ["dashboard", "settings", "notifications", "help"],
+    
+    # Admin roles: No context switching - empty list means show all apps always
+    "platform_admin": [],
+    "client_admin": [],
+    "contractor_admin": []
+}
+
+
 # ============================================================
 # HELPER FUNCTIONS
 # ============================================================
@@ -469,6 +489,11 @@ def get_default_favorites_for_role(role: str) -> List[str]:
     return DEFAULT_FAVORITE_APPS.get(role, [])
 
 
+def get_meta_apps_for_role(role: str) -> List[str]:
+    """Get meta app codes for a role (apps available outside project context)"""
+    return META_APPS_BY_ROLE.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