feat: app management roles for who can view what app

docs/api/user-profile/APP_ACCESS_UPDATE_SUMMARY.md

@@ -0,0 +1,375 @@
+# App Access Model Update - Summary
+
+## Overview
+
+Updated the app management system to reflect real-world business scenarios where users wear multiple hats and need broad VIEW access with controlled ACTION permissions.
+
+**Date:** November 18, 2025  
+**Updated Files:**
+- `src/app/config/apps.py`
+- `docs/api/user-profile/APP_MANAGEMENT_SYSTEM.md`
+
+---
+
+## Philosophy Change
+
+### Before: Restrictive Access
+- Roles had limited app access
+- Field agents couldn't see payroll
+- Dispatchers had narrow view
+- Sales managers isolated from operations
+
+### After: Broad Views, Restricted Actions
+- **Most roles see most apps** (VIEW access)
+- **Actions controlled via RBAC** (create/edit/delete permissions)
+- **Real-world flexibility** (admins can wear multiple hats)
+- **Casual workers track earnings** (field/sales agents see payroll)
+
+---
+
+## New Apps Added (4)
+
+1. **Incidents** - Incident tracking and resolution
+   - Category: Operations
+   - Icon: alert-triangle
+   - Route: /incidents
+
+2. **Tasks** - Task management and assignment
+   - Category: Operations
+   - Icon: check-square
+   - Route: /tasks
+
+3. **Subscriptions** - Recurring revenue management
+   - Category: Finance
+   - Icon: refresh-cw
+   - Route: /subscriptions
+   - Requires: view_subscriptions permission
+
+4. **Inventory** - Asset management
+   - Category: Operations
+   - Icon: package
+   - Route: /inventory
+   - Requires: view_inventory permission
+
+**Total Apps:** 26 (was 22)
+
+---
+
+## Role Access Changes
+
+### Platform Admin
+- **Before:** 8 apps
+- **After:** 26 apps (ALL)
+- **Reason:** System administrators need full visibility
+
+### Client Admin
+- **Before:** 10 apps
+- **After:** 23 apps
+- **Added:** Organizations, incidents, tasks, maps, timesheets, payroll, expenses, documents, inventory, subscriptions, billing, notifications
+- **Reason:** Can work as PM/dispatcher, needs full business visibility
+
+### Contractor Admin
+- **Before:** 9 apps
+- **After:** 23 apps
+- **Added:** Organizations, incidents, tasks, sales_orders, customers, maps, expenses, documents, inventory, subscriptions, billing, notifications, contractors
+- **Reason:** Can work as PM/dispatcher, needs operational visibility
+
+### Sales Manager
+- **Before:** 8 apps
+- **After:** 24 apps
+- **Added:** Projects, tickets, incidents, tasks, timesheets, payroll, expenses, contractors, documents, inventory, subscriptions, billing, notifications
+- **Reason:** Needs finance & operations visibility for fulfillment pipeline
+
+### Project Manager
+- **Before:** 8 apps
+- **After:** 25 apps
+- **Added:** Organizations, incidents, tasks, sales_orders, customers, contractors, timesheets, payroll, expenses, documents, inventory, subscriptions, billing, notifications
+- **Reason:** Needs full visibility for project coordination
+
+### Dispatcher
+- **Before:** 8 apps
+- **After:** 20 apps
+- **Added:** Incidents, tasks, sales_orders, customers, contractors, timesheets, expenses, documents, inventory, subscriptions
+- **Reason:** Sees what PM sees, different action permissions
+
+### Field Agent (Casual Worker)
+- **Before:** 7 apps (no payroll)
+- **After:** 14 apps
+- **Added:** Dashboard, incidents, tasks, **payroll**, customers, notifications
+- **Reason:** Track daily earnings from errands, see customer info for field visits
+
+### Sales Agent (Casual Worker)
+- **Before:** 7 apps (no payroll)
+- **After:** 15 apps
+- **Added:** Tickets, tasks, **payroll**, expenses, documents, notifications
+- **Reason:** Track sales commissions, follow up on customer issues
+
+---
+
+## Why Casual Workers Need Payroll
+
+### Problem
+Field agents and sales agents are typically casual/gig workers who:
+- Get paid per completed task (field agent: "How much did I earn today?")
+- Earn commission on sales (sales agent: "What's my commission this week?")
+- Want transparency on their compensation
+- Need to verify payments
+
+### Solution
+Give VIEW-only access to payroll app with:
+- **Row-level security:** Workers only see their own payroll records
+- **No action permissions:** Can't modify payroll data
+- **Real-time visibility:** Track daily/weekly earnings
+- **Transparent compensation:** Build trust with workers
+
+### Implementation
+```python
+# Backend query with row-level filtering
+if user.role in ['field_agent', 'sales_agent']:
+    payroll = Payroll.query.filter(Payroll.user_id == user.id)
+else:
+    payroll = Payroll.query  # Admins see all
+```
+
+---
+
+## Multi-Role Reality
+
+### Use Case: Small Business Client Admin
+
+**Scenario:** John is a client admin at a small company. He also:
+- Coordinates projects (PM role)
+- Dispatches field agents (dispatcher role)
+- Approves timesheets (HR role)
+- Reviews sales reports (sales manager role)
+
+**Solution:**
+- John sees ALL 23 apps (broad VIEW access)
+- Different permissions for different actions:
+  - ✅ Can create projects (has `can_create_project`)
+  - ✅ Can dispatch agents (has `can_assign_tickets`)
+  - ❌ Cannot approve payroll (lacks `can_approve_payroll`)
+  - ✅ Can view sales reports (has `can_view_sales`)
+
+**UI Behavior:**
+- Navigation shows all accessible apps
+- Action buttons appear/disappear based on permissions
+- Tooltips explain why actions are disabled
+
+---
+
+## Action Permissions vs View Access
+
+### View Access (App Level)
+- Controlled by `ROLE_APP_ACCESS` in `apps.py`
+- Determines which apps appear in navigation
+- Broad by default for most roles
+
+### Action Permissions (Feature Level)
+- Controlled by RBAC system (database `permissions` table)
+- Fine-grained (can_create_ticket, can_approve_payroll, etc.)
+- Checked on every mutation/action
+- Independent of app access
+
+### Example Matrix
+
+| Role | Payroll App Access | View Own Payroll | View All Payroll | Approve Payroll | Process Payroll |
+|------|-------------------|------------------|------------------|-----------------|-----------------|
+| Field Agent | ✅ Yes | ✅ Yes | ❌ No | ❌ No | ❌ No |
+| Sales Agent | ✅ Yes | ✅ Yes | ❌ No | ❌ No | ❌ No |
+| Dispatcher | ✅ Yes | ✅ Yes | ✅ Yes* | ❌ No | ❌ No |
+| PM | ✅ Yes | ✅ Yes | ✅ Yes* | ❌ No | ❌ No |
+| Contractor Admin | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
+| Client Admin | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
+
+*Limited to their team/organization
+
+---
+
+## Default Favorites Update
+
+### Changed
+- **Contractor Admin:** Added "payroll" to defaults (was team)
+- **Dispatcher:** Added "tasks" to defaults (was team)
+- **Field Agent:** Changed to "tickets, maps, timesheets, payroll"
+- **Sales Agent:** Changed to "sales_orders, customers, maps, payroll"
+
+### Why
+- Reflect most-used apps for each role
+- Casual workers prioritize earnings tracking
+- Dispatchers focus on task assignment
+
+---
+
+## Frontend Impact
+
+### Navigation Bar
+```javascript
+// Before: Hardcoded app list
+const navItems = ['dashboard', 'tickets', 'projects'];
+
+// After: Dynamic from API
+const { apps } = useFetchApps();
+const accessibleApps = apps.filter(app => app.has_access);
+```
+
+### App Launcher
+```javascript
+// Before: Role-based switch statement
+switch(userRole) {
+  case 'field_agent': return ['tickets', 'maps'];
+  // ...
+}
+
+// After: API-driven with categories
+const { apps_by_category } = useFetchApps();
+{Object.entries(apps_by_category).map(([category, apps]) => (
+  <CategorySection>
+    {apps.filter(app => app.has_access).map(renderApp)}
+  </CategorySection>
+))}
+```
+
+### Action Buttons
+```javascript
+// Separate permission checks for actions
+{hasPermission('can_create_ticket') && (
+  <Button onClick={createTicket}>Create Ticket</Button>
+)}
+
+{hasPermission('can_approve_payroll') && (
+  <Button onClick={approvePayroll}>Approve</Button>
+)}
+```
+
+---
+
+## Backend Implementation
+
+### Row-Level Security Example
+```python
+# Payroll endpoint
+@router.get("/payroll")
+def get_payroll(user: User = Depends(get_current_user), db: Session = Depends(get_db)):
+    query = db.query(Payroll)
+    
+    # Apply row-level filtering
+    if user.role in ['field_agent', 'sales_agent']:
+        # Workers only see their own records
+        query = query.filter(Payroll.user_id == user.id)
+    elif user.role == 'dispatcher':
+        # Dispatchers see their team
+        query = query.filter(Payroll.organization_id == user.organization_id)
+    # Admins see all (no additional filter)
+    
+    return query.all()
+```
+
+### Permission Decorator
+```python
+def require_permission(permission: str):
+    def decorator(func):
+        async def wrapper(*args, user: User = Depends(get_current_user), **kwargs):
+            if not user.has_permission(permission):
+                raise HTTPException(403, f"Missing permission: {permission}")
+            return await func(*args, user=user, **kwargs)
+        return wrapper
+    return decorator
+
+@router.post("/payroll/approve")
+@require_permission('can_approve_payroll')
+def approve_payroll(payroll_id: int, user: User):
+    # Only executes if user has permission
+    pass
+```
+
+---
+
+## Testing Checklist
+
+### Backend Tests
+- [ ] All 26 apps defined in APPS dictionary
+- [ ] All roles have valid app access lists
+- [ ] Helper functions work with new apps
+- [ ] Default favorites include valid app codes
+- [ ] Row-level security filters work correctly
+
+### Frontend Tests
+- [ ] Navigation shows correct apps per role
+- [ ] App launcher displays all accessible apps
+- [ ] Categories render correctly
+- [ ] Action buttons appear/disappear based on permissions
+- [ ] Settings page allows favoriting new apps
+- [ ] Max 6 favorites enforced
+- [ ] Invalid apps rejected with clear error
+
+### Integration Tests
+- [ ] Field agent sees only their payroll records
+- [ ] Dispatcher sees incidents, tasks, expenses
+- [ ] PM sees all apps except platform admin apps
+- [ ] Sales manager sees finance and inventory
+- [ ] Client admin can work as PM
+- [ ] Payroll access doesn't grant approval permissions
+
+---
+
+## Migration Steps
+
+### Phase 1: Backend (Done ✅)
+1. Add 4 new apps to APPS dictionary
+2. Update ROLE_APP_ACCESS for all 8 roles
+3. Update DEFAULT_FAVORITE_APPS
+4. Add philosophy comment
+
+### Phase 2: Frontend (Next)
+1. Update API calls to fetch new apps
+2. Test navigation with expanded app lists
+3. Verify app launcher categories
+4. Test favorites with new apps
+5. Implement permission-based action buttons
+
+### Phase 3: Permissions Setup
+1. Define action permissions in database
+2. Assign permissions to roles
+3. Implement row-level security queries
+4. Add permission decorators to endpoints
+
+### Phase 4: Testing
+1. User acceptance testing with each role
+2. Verify casual workers can see earnings
+3. Test multi-role scenarios
+4. Performance testing with 26 apps
+
+---
+
+## Breaking Changes
+
+### None! 🎉
+
+This is a **backward-compatible** update:
+- Existing apps still work
+- Old favorites still valid
+- No API contract changes
+- Only additive changes (more apps, more access)
+
+Frontend will automatically:
+- Fetch new apps from API
+- Display expanded navigation
+- Allow favoriting new apps
+
+---
+
+## Future Enhancements
+
+1. **Permission Management UI** - Admin interface to assign permissions
+2. **Role Templates** - Pre-configured permission sets per role
+3. **Custom Roles** - Organizations define their own roles
+4. **App Analytics** - Track which apps users access most
+5. **Dynamic Permissions** - Time-based or condition-based permissions
+6. **App Bundles** - Group apps into bundles (Operations Bundle, Finance Bundle)
+
+---
+
+**Updated By:** AI Assistant  
+**Reviewed By:** Pending  
+**Status:** Ready for Frontend Integration

docs/api/user-profile/APP_MANAGEMENT_SYSTEM.md

@@ -94,18 +94,21 @@ class AppDefinition:
 
 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 |
+| Category | Purpose | Example Apps | Total |
+|----------|---------|--------------|-------|
+| **Core** | Essential platform features | Dashboard, Organizations, Users, Activity, Notifications | 5 apps |
+| **Operations** | Field operations & ticketing | Tickets, Projects, Maps, Contractors, Incidents, Tasks, Documents, Inventory, Reports | 9 apps |
+| **Sales** | Sales & customer management | Sales Orders, Customers | 2 apps |
+| **Team** | Team management & scheduling | Team, Timesheets | 2 apps |
+| **Finance** | Financial management | Payroll, Billing, Expenses, Subscriptions | 4 apps |
+| **Settings** | Configuration & support | Settings, Profile, Help | 3 apps |
 
-### Example App Definition
+**Total Apps in System:** 26 apps
+
+### Example App Definitions
 
 ```python
+# Core App
 "dashboard": AppDefinition(
     code="dashboard",
     name="Dashboard",
@@ -114,8 +117,45 @@ Apps are organized into 6 categories:
     route="/dashboard",
     category=AppCategory.CORE
 )
+
+# Operations App with Permission
+"incidents": AppDefinition(
+    code="incidents",
+    name="Incidents",
+    description="Incident tracking and resolution",
+    icon="alert-triangle",
+    route="/incidents",
+    category=AppCategory.OPERATIONS
+)
+
+# Finance App with Permission
+"subscriptions": AppDefinition(
+    code="subscriptions",
+    name="Subscriptions",
+    description="Subscription and recurring revenue management",
+    icon="refresh-cw",
+    route="/subscriptions",
+    category=AppCategory.FINANCE,
+    requires_permission="view_subscriptions"  # Action permissions controlled separately
+)
 ```
 
+### New Apps Added
+
+**Operations:**
+- **Incidents** - Incident tracking and resolution for critical issues
+- **Tasks** - Task management and assignment for daily operations
+- **Inventory** - Inventory and asset management
+
+**Finance:**
+- **Subscriptions** - Recurring revenue and subscription management
+
+**Why These Apps?**
+- **Dispatchers** need to see incidents, tasks, expenses, sales orders, and subscriptions
+- **Field Agents & Sales Agents** (casual workers) need to track their daily earnings via payroll
+- **PMs** need full visibility into all business operations
+- **Sales Managers** need finance and inventory visibility to understand fulfillment
+
 ---
 
 ## API Endpoints
@@ -502,18 +542,30 @@ Create the frontend page and add route:
 
 ## Role Configuration
 
+### Philosophy: Views Are Broad, Actions Are Restricted
+
+**Key Principle:** Most roles can VIEW most apps to understand the full business context. Action permissions (create, edit, delete) are controlled separately via RBAC (Role-Based Access Control).
+
+**Real-World Reality:**
+- A **client_admin** can also do PM or dispatcher work
+- A **PM** needs visibility into sales, finance, and operations for coordination
+- A **dispatcher** sees what PM sees but has different action permissions
+- **Field agents & sales agents** (casual workers) need to track their daily earnings via payroll
+
 ### 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 |
+| Role | Total Apps | Key Focus | Default Favorites |
+|------|-----------|-----------|-------------------|
+| **Platform Admin** | 26 apps (ALL) | System management | Dashboard, Organizations, Users, Activity |
+| **Client Admin** | 23 apps (ALMOST ALL) | Can work as PM/dispatcher too | Dashboard, Projects, Tickets, Team |
+| **Contractor Admin** | 23 apps (ALMOST ALL) | Can work as PM/dispatcher too | Dashboard, Projects, Tickets, Payroll |
+| **Sales Manager** | 24 apps (ALMOST ALL) | Sales + operations visibility | Dashboard, Sales Orders, Customers, Reports |
+| **Project Manager** | 25 apps (ALMOST ALL) | Full business visibility | Dashboard, Projects, Tickets, Team |
+| **Dispatcher** | 20 apps | Same views as PM, different actions | Dashboard, Tickets, Maps, Tasks |
+| **Field Agent** | 14 apps | Daily work + earnings tracking | Tickets, Maps, Timesheets, Payroll |
+| **Sales Agent** | 15 apps | Sales + commission tracking | Sales Orders, Customers, Maps, Payroll |
+
+**Note:** Numbers represent apps with VIEW access. Action permissions (create/edit/delete) are controlled via separate RBAC permissions.
 
 ### Modifying Role Access
 
@@ -532,6 +584,66 @@ ROLE_APP_ACCESS = {
 
 ---
 
+## Special Considerations
+
+### Casual Workers (Field Agents & Sales Agents)
+
+**Payroll Access for Earnings Tracking:**
+
+Field agents and sales agents are typically casual workers who:
+- Get paid per task/errand completed (field agents)
+- Earn commissions on sales (sales agents)
+- Need to track their daily/weekly earnings
+- Want transparency on their compensation
+
+**Why Payroll Access:**
+- **Field Agent:** "How much did I earn from today's 5 service calls?"
+- **Sales Agent:** "What's my commission from this week's sales?"
+- VIEW-only access to their own earnings data
+- Cannot see other workers' payroll (controlled by row-level security)
+- Cannot modify payroll data (controlled by action permissions)
+
+**Implementation:**
+```python
+# Backend: Row-level security
+if user.role in ['field_agent', 'sales_agent']:
+    # Only show their own payroll records
+    payroll = db.query(Payroll).filter(
+        Payroll.user_id == user.id
+    )
+else:
+    # Admins/managers can see all payroll
+    payroll = db.query(Payroll)
+```
+
+### Multi-Role Reality
+
+**Client/Contractor Admins Wearing Multiple Hats:**
+
+In real-world small/medium businesses:
+- A client_admin might also coordinate projects (PM role)
+- Same person might dispatch field agents (dispatcher role)
+- They need access to ALL apps but with different permissions
+
+**Solution:**
+- Give admins VIEW access to all apps
+- Control ACTIONS via permissions (can_create_project, can_approve_payroll, etc.)
+- UI shows/hides action buttons based on permissions
+- Backend validates permissions on all mutations
+
+**Example:**
+```javascript
+// Frontend: Conditional action buttons
+{hasPermission('can_create_ticket') && (
+  <Button onClick={createTicket}>Create Ticket</Button>
+)}
+
+// Backend: Permission check
+@require_permission('can_create_ticket')
+def create_ticket(ticket_data):
+    # Only executes if user has permission
+```
+
 ## Best Practices
 
 ### Backend

src/app/config/apps.py

@@ -272,84 +272,137 @@ APPS: Dict[str, AppDefinition] = {
         route="/help",
         category=AppCategory.SETTINGS
     ),
+    
+    # ADDITIONAL OPERATIONS
+    "incidents": AppDefinition(
+        code="incidents",
+        name="Incidents",
+        description="Incident tracking and resolution",
+        icon="alert-triangle",
+        route="/incidents",
+        category=AppCategory.OPERATIONS
+    ),
+    
+    "tasks": AppDefinition(
+        code="tasks",
+        name="Tasks",
+        description="Task management and assignment",
+        icon="check-square",
+        route="/tasks",
+        category=AppCategory.OPERATIONS
+    ),
+    
+    "subscriptions": AppDefinition(
+        code="subscriptions",
+        name="Subscriptions",
+        description="Subscription and recurring revenue management",
+        icon="refresh-cw",
+        route="/subscriptions",
+        category=AppCategory.FINANCE,
+        requires_permission="view_subscriptions"
+    ),
+    
+    "inventory": AppDefinition(
+        code="inventory",
+        name="Inventory",
+        description="Inventory and asset management",
+        icon="package",
+        route="/inventory",
+        category=AppCategory.OPERATIONS,
+        requires_permission="view_inventory"
+    ),
 }
 
 
 # ============================================================
 # ROLE-BASED ACCESS - Defines which apps each role can access
+# 
+# PHILOSOPHY: Views are broad, actions are restricted
+# - Most roles can VIEW most apps to understand the full business context
+# - Action permissions (create, edit, delete) are controlled separately via RBAC
+# - This reflects real-world scenarios where:
+#   * A client_admin can also do PM/dispatcher work
+#   * A PM needs visibility into sales, finance, and operations
+#   * A dispatcher sees what PM sees but has different action permissions
+#   * Field agents & sales agents (casual workers) track their daily earnings
 # ============================================================
 
 ROLE_APP_ACCESS: Dict[str, List[str]] = {
     "platform_admin": [
-        # Core admin apps
+        # Platform admin has access to ALL apps for system management
         "dashboard", "organizations", "users", "activity",
-        # Management & settings
-        "settings", "billing", "notifications", "help"
+        "tickets", "projects", "maps", "contractors", "incidents", "tasks",
+        "sales_orders", "customers", "reports",
+        "team", "timesheets", "payroll",
+        "expenses", "documents", "inventory", "subscriptions",
+        "profile", "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"
+        # Client admin has access to ALL apps (can also work as PM/dispatcher)
+        # Action permissions differ but views are the same
+        "dashboard", "organizations", "projects", "tickets", "team", "incidents", "tasks",
+        "sales_orders", "customers", "contractors", "reports",
+        "maps", "timesheets", "payroll", "expenses", "documents",
+        "inventory", "subscriptions", "billing",
+        "profile", "settings", "notifications", "help"
     ],
     
     "contractor_admin": [
-        # Core operations
-        "dashboard", "projects", "tickets", "team",
-        # Time & payroll
-        "timesheets", "payroll",
-        # Analytics & settings
-        "reports", "settings", "help"
+        # Contractor admin has access to ALL apps (can also work as PM/dispatcher)
+        # Focus on contractor operations but can see everything
+        "dashboard", "organizations", "projects", "tickets", "team", "incidents", "tasks",
+        "sales_orders", "customers", "contractors", "reports",
+        "maps", "timesheets", "payroll", "expenses", "documents",
+        "inventory", "subscriptions", "billing",
+        "profile", "settings", "notifications", "help"
     ],
     
     "sales_manager": [
-        # Sales focus
-        "dashboard", "sales_orders", "customers",
-        # Operations support
-        "team", "maps", "reports",
-        # Settings
-        "settings", "help"
+        # Sales manager has access to ALL apps including finance & inventory
+        # Can see operations to understand fulfillment pipeline
+        "dashboard", "projects", "tickets", "team", "incidents", "tasks",
+        "sales_orders", "customers", "reports", "maps",
+        "timesheets", "payroll", "expenses", "inventory", "subscriptions",
+        "contractors", "documents", "billing",
+        "profile", "settings", "notifications", "help"
     ],
     
     "project_manager": [
-        # Project operations
-        "dashboard", "projects", "tickets", "team",
-        # Field operations
-        "maps", "reports",
-        # Settings
-        "settings", "help"
+        # PM has access to ALL apps - needs full visibility for project coordination
+        # Can see sales, finance, team, operations - everything
+        "dashboard", "organizations", "projects", "tickets", "team", "incidents", "tasks",
+        "sales_orders", "customers", "contractors", "reports", "maps",
+        "timesheets", "payroll", "expenses", "documents", "inventory", "subscriptions",
+        "billing", "profile", "settings", "notifications", "help"
     ],
     
     "dispatcher": [
-        # Dispatch operations
-        "dashboard", "tickets", "maps", "team",
-        # Operations support
-        "projects", "reports",
-        # Settings
-        "settings", "help"
+        # Dispatcher sees what PM sees (same views, different action permissions)
+        # Needs full visibility to coordinate field operations
+        "dashboard", "projects", "tickets", "team", "incidents", "tasks",
+        "sales_orders", "customers", "contractors", "reports", "maps",
+        "timesheets", "expenses", "documents", "inventory", "subscriptions",
+        "profile", "settings", "notifications", "help"
     ],
     
     "field_agent": [
-        # Field operations
-        "tickets", "maps", "timesheets",
-        # Personal
-        "profile", "expenses", "documents",
-        # Support
-        "help"
+        # Field agents (casual workers) need to see their earnings and daily work
+        # Include payroll to track earnings from daily errands
+        "dashboard", "tickets", "maps", "timesheets", "tasks", "incidents",
+        "payroll",  # Track their daily earnings
+        "expenses", "documents", "customers",  # Customer info for field visits
+        "profile", "notifications", "help"
     ],
     
     "sales_agent": [
-        # Sales operations
-        "dashboard", "sales_orders", "customers", "maps",
-        # Personal
-        "profile", "reports",
-        # Support
-        "help"
+        # Sales agents (casual workers) need to track their commission/earnings
+        # Include payroll to see earnings from sales
+        "dashboard", "sales_orders", "customers", "maps", "reports",
+        "tickets", "tasks",  # Follow up on customer issues
+        "payroll",  # Track their sales commissions/earnings
+        "expenses", "documents",
+        "profile", "notifications", "help"
     ]
 }
 
@@ -361,12 +414,12 @@ ROLE_APP_ACCESS: Dict[str, List[str]] = {
 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"],
+    "contractor_admin": ["dashboard", "projects", "tickets", "payroll"],
     "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"]
+    "dispatcher": ["dashboard", "tickets", "maps", "tasks"],
+    "field_agent": ["tickets", "maps", "timesheets", "payroll"],  # Focus on work & earnings
+    "sales_agent": ["sales_orders", "customers", "maps", "payroll"]  # Focus on sales & commissions
 }