feat: unified sync notification system, realtime timesheets and payroll, simplified project role compensation

docs/dev/NOTIFICATION_SYSTEM.md

@@ -0,0 +1,448 @@
+# Notification System - Developer Guide
+
+## 🎯 Overview
+
+The SwiftOps notification system is a **2-tier architecture** designed for reliability, scalability, and maintainability. It handles all notifications across the platform with a consistent, world-class approach.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    NOTIFICATION SYSTEM                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  TIER 1: Notification Creation (Synchronous)                │
+│  ┌────────────────────────────────────────────────────┐    │
+│  │  NotificationCreator                                │    │
+│  │  - Creates notification records in database         │    │
+│  │  - Synchronous, transaction-safe                    │    │
+│  │  - Guaranteed to be saved                           │    │
+│  │  - Rolls back with parent operation                 │    │
+│  └────────────────────────────────────────────────────┘    │
+│                          ↓                                   │
+│  TIER 2: Notification Delivery (Asynchronous)               │
+│  ┌────────────────────────────────────────────────────┐    │
+│  │  NotificationDelivery                               │    │
+│  │  - Delivers via external channels (WhatsApp, etc.)  │    │
+│  │  - Non-blocking background tasks                    │    │
+│  │  - Handles failures gracefully                      │    │
+│  │  - Configurable per channel                         │    │
+│  └────────────────────────────────────────────────────┘    │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```python
+from fastapi import BackgroundTasks
+from app.services.notification_creator import NotificationCreator
+from app.services.notification_delivery import NotificationDelivery
+
+# In your endpoint
+@router.post("/tickets/assign")
+def assign_ticket(
+    background_tasks: BackgroundTasks,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    # Your business logic
+    ticket = create_ticket(...)
+    assignment = assign_to_agent(...)
+    
+    # TIER 1: Create notification (synchronous)
+    notification = NotificationCreator.create(
+        db=db,
+        user_id=agent.id,
+        title="New Ticket Assigned",
+        message=f"You have been assigned to {ticket.ticket_name}",
+        source_type="ticket",
+        source_id=ticket.id,
+        notification_type="assignment",
+        channel="whatsapp",
+        project_id=ticket.project_id,
+        metadata={
+            "ticket_number": ticket.ticket_number,
+            "priority": "high",
+            "action_url": f"/tickets/{ticket.id}"
+        }
+    )
+    
+    # Commit notification with your business logic
+    db.commit()
+    
+    # TIER 2: Queue delivery (asynchronous, non-blocking)
+    NotificationDelivery.queue_delivery(
+        background_tasks=background_tasks,
+        notification_id=notification.id
+    )
+    
+    return {"status": "success"}
+```
+
+---
+
+## 📚 API Reference
+
+### NotificationCreator
+
+#### `create()` - Create Single Notification
+
+```python
+notification = NotificationCreator.create(
+    db: Session,                    # Database session
+    user_id: UUID,                  # User to notify
+    title: str,                     # Short title (for display)
+    message: str,                   # Detailed message
+    source_type: str,               # Entity type (ticket, expense, payroll, etc.)
+    source_id: Optional[UUID],      # Entity ID (None for bulk operations)
+    notification_type: str,         # Notification type (assignment, payment, alert, etc.)
+    channel: str = "in_app",        # Delivery channel (in_app, whatsapp, email, sms, push)
+    metadata: Optional[Dict] = None,# Additional data (action URLs, context, etc.)
+    project_id: Optional[UUID] = None  # Optional project ID for filtering
+) -> Notification
+```
+
+**Example:**
+```python
+notification = NotificationCreator.create(
+    db=db,
+    user_id=agent.id,
+    title="Ticket Assigned",
+    message="You have been assigned to install fiber at Customer A",
+    source_type="ticket",
+    source_id=ticket.id,
+    notification_type="assignment",
+    channel="whatsapp",
+    project_id=ticket.project_id,
+    metadata={
+        "ticket_number": "TKT-001",
+        "priority": "high",
+        "action_url": f"/tickets/{ticket.id}"
+    }
+)
+db.commit()
+```
+
+#### `create_bulk()` - Create Multiple Notifications
+
+```python
+notifications = NotificationCreator.create_bulk(
+    db: Session,
+    user_ids: List[UUID],           # List of users to notify
+    title: str,                     # Same title for all
+    message: str,                   # Same message for all
+    source_type: str,
+    source_id: Optional[UUID],
+    notification_type: str,
+    channel: str = "in_app",
+    metadata: Optional[Dict] = None,
+    project_id: Optional[UUID] = None
+) -> List[Notification]
+```
+
+**Example:**
+```python
+# Notify all workers about payroll export
+worker_ids = [worker1.id, worker2.id, worker3.id]
+notifications = NotificationCreator.create_bulk(
+    db=db,
+    user_ids=worker_ids,
+    title="💰 Payment Processed",
+    message="Your payment has been processed",
+    source_type="payroll",
+    source_id=None,
+    notification_type="payment",
+    channel="whatsapp"
+)
+db.commit()
+```
+
+#### `notify_project_team()` - Notify Team Members by Role
+
+```python
+notifications = NotificationCreator.notify_project_team(
+    db: Session,
+    project_id: UUID,               # Project ID
+    title: str,
+    message: str,
+    source_type: str,
+    source_id: Optional[UUID],
+    notification_type: str,
+    roles: Optional[List[AppRole]] = None,  # Filter by roles (PM, Dispatcher, etc.)
+    channel: str = "in_app",
+    metadata: Optional[Dict] = None,
+    exclude_user_ids: Optional[List[UUID]] = None  # Exclude specific users
+) -> List[Notification]
+```
+
+**Example:**
+```python
+# Notify all managers when ticket is dropped
+notifications = NotificationCreator.notify_project_team(
+    db=db,
+    project_id=ticket.project_id,
+    title="⚠️ Ticket Dropped - Action Required",
+    message=f"{agent.name} dropped ticket: {ticket.name}",
+    source_type="ticket",
+    source_id=ticket.id,
+    notification_type="ticket_dropped",
+    roles=[AppRole.PROJECT_MANAGER, AppRole.DISPATCHER],
+    exclude_user_ids=[agent.id]  # Don't notify the agent who dropped
+)
+db.commit()
+```
+
+---
+
+### NotificationDelivery
+
+#### `queue_delivery()` - Queue Single Notification
+
+```python
+NotificationDelivery.queue_delivery(
+    background_tasks: BackgroundTasks,  # FastAPI BackgroundTasks
+    notification_id: UUID               # Notification ID to deliver
+) -> None
+```
+
+**Example:**
+```python
+NotificationDelivery.queue_delivery(
+    background_tasks=background_tasks,
+    notification_id=notification.id
+)
+```
+
+#### `queue_bulk_delivery()` - Queue Multiple Notifications
+
+```python
+NotificationDelivery.queue_bulk_delivery(
+    background_tasks: BackgroundTasks,
+    notification_ids: List[UUID]        # List of notification IDs
+) -> None
+```
+
+**Example:**
+```python
+NotificationDelivery.queue_bulk_delivery(
+    background_tasks=background_tasks,
+    notification_ids=[n.id for n in notifications]
+)
+```
+
+---
+
+## 🎨 Common Patterns
+
+### Pattern 1: Single User Notification
+
+```python
+@router.post("/tickets/assign")
+def assign_ticket(
+    background_tasks: BackgroundTasks,
+    db: Session = Depends(get_db)
+):
+    # Business logic
+    assignment = create_assignment(...)
+
+    # Create notification
+    notification = NotificationCreator.create(
+        db=db,
+        user_id=agent.id,
+        title="Ticket Assigned",
+        message=f"You have been assigned to {ticket.name}",
+        source_type="ticket",
+        source_id=ticket.id,
+        notification_type="assignment",
+        channel="whatsapp"
+    )
+    db.commit()
+
+    # Queue delivery
+    NotificationDelivery.queue_delivery(
+        background_tasks=background_tasks,
+        notification_id=notification.id
+    )
+
+    return assignment
+```
+
+### Pattern 2: Notify Project Team by Role
+
+```python
+@router.post("/tickets/{ticket_id}/drop")
+def drop_ticket(
+    background_tasks: BackgroundTasks,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    # Business logic
+    ticket = drop_ticket(...)
+
+    # Notify all managers and dispatchers
+    notifications = NotificationCreator.notify_project_team(
+        db=db,
+        project_id=ticket.project_id,
+        title="⚠️ Ticket Dropped",
+        message=f"{current_user.name} dropped ticket: {ticket.name}",
+        source_type="ticket",
+        source_id=ticket.id,
+        notification_type="ticket_dropped",
+        roles=[AppRole.PROJECT_MANAGER, AppRole.DISPATCHER],
+        exclude_user_ids=[current_user.id]
+    )
+    db.commit()
+
+    # Queue delivery
+    NotificationDelivery.queue_bulk_delivery(
+        background_tasks=background_tasks,
+        notification_ids=[n.id for n in notifications]
+    )
+
+    return ticket
+```
+
+---
+
+## ⚙️ Configuration
+
+### Channel Configuration
+
+For MVP, all external channels are **disabled by default**. Notifications are created but not delivered externally.
+
+**File:** `src/app/services/notification_delivery.py`
+
+```python
+class NotificationDeliveryConfig:
+    # For MVP, all external channels are disabled
+    ENABLE_WHATSAPP = False  # Set to True when ready
+    ENABLE_EMAIL = False     # Set to True when ready
+    ENABLE_SMS = False       # Set to True when ready
+    ENABLE_PUSH = False      # Set to True when ready
+
+    # In-app notifications are always enabled
+    ENABLE_IN_APP = True
+```
+
+**To enable a channel:**
+1. Set the flag to `True` in `NotificationDeliveryConfig`
+2. Implement the delivery method (e.g., `_deliver_whatsapp()`)
+3. Test thoroughly
+4. Deploy
+
+---
+
+## 🔍 Best Practices
+
+### 1. Always Commit Notifications
+
+```python
+# ✅ CORRECT
+notification = NotificationCreator.create(...)
+db.commit()  # Commit before queuing delivery
+
+NotificationDelivery.queue_delivery(...)
+```
+
+```python
+# ❌ WRONG
+notification = NotificationCreator.create(...)
+NotificationDelivery.queue_delivery(...)  # Notification not committed yet!
+db.commit()
+```
+
+### 2. Use Metadata for Context
+
+```python
+# ✅ CORRECT - Rich metadata
+notification = NotificationCreator.create(
+    db=db,
+    user_id=user.id,
+    title="Ticket Assigned",
+    message="You have been assigned...",
+    source_type="ticket",
+    source_id=ticket.id,
+    notification_type="assignment",
+    metadata={
+        "ticket_number": ticket.ticket_number,
+        "priority": "high",
+        "action_url": f"/tickets/{ticket.id}",
+        "customer_name": ticket.customer_name
+    }
+)
+```
+
+### 3. Handle Notification Failures Gracefully
+
+```python
+# ✅ CORRECT - Don't fail business logic if notification fails
+try:
+    notification = NotificationCreator.create(...)
+    db.commit()
+    NotificationDelivery.queue_delivery(...)
+except Exception as e:
+    logger.error(f"Failed to create notification: {e}")
+    # Continue with business logic
+```
+
+---
+
+## 🚀 Migration from Old System
+
+### Old Pattern (NotificationHelper - Async)
+
+```python
+# ❌ OLD - Don't use this anymore
+await NotificationHelper.notify_ticket_assigned(
+    db=db,
+    ticket=ticket,
+    agent=agent
+)
+```
+
+### New Pattern (NotificationCreator - Sync)
+
+```python
+# ✅ NEW - Use this instead
+notification = NotificationCreator.create(
+    db=db,
+    user_id=agent.id,
+    title="Ticket Assigned",
+    message=f"You have been assigned to {ticket.name}",
+    source_type="ticket",
+    source_id=ticket.id,
+    notification_type="assignment",
+    channel="whatsapp"
+)
+db.commit()
+
+NotificationDelivery.queue_delivery(
+    background_tasks=background_tasks,
+    notification_id=notification.id
+)
+```
+
+---
+
+## 📞 Support
+
+For questions or issues with the notification system:
+1. Check this documentation
+2. Review existing implementations in:
+   - `src/app/api/v1/payroll.py` (payroll export)
+   - `src/app/api/v1/ticket_assignments.py` (ticket drop)
+   - `src/app/services/expense_service.py` (expense submission)
+3. Contact the development team
+
+---
+
+**Last Updated:** 2024-12-12
+**Version:** 1.0.0
+**Status:** Production Ready ✅
+
+

docs/features/REALTIME_TIMESHEET_IMPLEMENTATION.md

@@ -0,0 +1,714 @@
+# Real-Time Timesheet Updates - Implementation Guide
+
+**Date:** 2025-12-12
+**Status:** Ready for Implementation
+**Estimated Time:** 6-7 hours
+
+---
+
+## Business Requirements (CONFIRMED)
+
+### 1. Multi-Project Support
+- **Frequency:** RARE but POSSIBLE
+- **Reason:** Different projects pay different rates
+- **Solution:** Unique constraint `(user_id, project_id, work_date)`
+- **Impact:** One agent can have multiple timesheets per day (one per project)
+
+### 2. Immutability Rules
+- **Rule:** Past timesheets NEVER change
+- **Reason:** Historical accuracy - agent's work should not be forgotten
+- **Example:** Manager deletes completed ticket → Yesterday's timesheet stays unchanged
+- **Implementation:** Only update timesheet if `work_date = TODAY`
+
+### 3. Expense Date Constraints
+- **Rule:** Expenses can ONLY be submitted for TODAY
+- **Reason:** Prevents agents from constructing lies
+- **UI:** Expense submission button is within ticket view (same day)
+- **Implementation:** API validation rejects expenses with `expense_date != TODAY`
+
+### 4. Check-in/Check-out Calculation
+- **Check-in:** `MIN(journey_started_at)` - When agent starts first journey
+- **Check-out:** `MAX(ended_at)` - When agent finishes last ticket
+- **Source:** `ticket_assignments` table
+- **Calculation:** Real-time aggregation from assignments
+
+### 5. Optimistic Locking
+- **Purpose:** Prevent concurrent update conflicts
+- **Implementation:** `version` column auto-incremented on every update
+- **Behavior:** Update fails if version changed, retry with fresh data
+
+---
+
+## Database Schema Changes
+
+### Migration 1: Add Version Column to Timesheets
+
+```sql
+-- Add version column for optimistic locking
+ALTER TABLE timesheets
+ADD COLUMN version INTEGER NOT NULL DEFAULT 1;
+
+-- Create trigger to auto-increment version on update
+CREATE OR REPLACE FUNCTION increment_timesheet_version()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.version = OLD.version + 1;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trigger_increment_timesheet_version
+BEFORE UPDATE ON timesheets
+FOR EACH ROW
+EXECUTE FUNCTION increment_timesheet_version();
+
+-- Add index for version queries
+CREATE INDEX idx_timesheets_version ON timesheets(version);
+```
+
+### Migration 2: Fix Unique Constraint (Multi-Project Support)
+
+```sql
+-- Drop old constraint (user_id, work_date)
+ALTER TABLE timesheets
+DROP CONSTRAINT IF EXISTS uq_timesheets_user_date;
+
+-- Add new constraint (user_id, project_id, work_date)
+ALTER TABLE timesheets
+ADD CONSTRAINT uq_timesheets_user_project_date
+UNIQUE (user_id, project_id, work_date);
+
+-- Note: This allows multiple timesheets per day (one per project)
+```
+
+### Migration 3: Add Timesheet Sync Tracking to Source Tables
+
+```sql
+-- Add to ticket_assignments
+ALTER TABLE ticket_assignments
+ADD COLUMN timesheet_synced BOOLEAN NOT NULL DEFAULT FALSE,
+ADD COLUMN timesheet_synced_at TIMESTAMP WITH TIME ZONE;
+
+CREATE INDEX idx_ticket_assignments_timesheet_synced
+ON ticket_assignments(timesheet_synced)
+WHERE timesheet_synced = FALSE;
+
+-- Add to ticket_expenses
+ALTER TABLE ticket_expenses
+ADD COLUMN timesheet_synced BOOLEAN NOT NULL DEFAULT FALSE,
+ADD COLUMN timesheet_synced_at TIMESTAMP WITH TIME ZONE;
+
+CREATE INDEX idx_ticket_expenses_timesheet_synced
+ON ticket_expenses(timesheet_synced)
+WHERE timesheet_synced = FALSE;
+
+-- Add to tickets
+ALTER TABLE tickets
+ADD COLUMN timesheet_synced BOOLEAN NOT NULL DEFAULT FALSE,
+ADD COLUMN timesheet_synced_at TIMESTAMP WITH TIME ZONE;
+
+CREATE INDEX idx_tickets_timesheet_synced
+ON tickets(timesheet_synced)
+WHERE timesheet_synced = FALSE;
+```
+
+### Migration 4: Add Missing Expense Columns to Timesheets
+
+```sql
+-- Check if expense columns exist, add if missing
+ALTER TABLE timesheets
+ADD COLUMN IF NOT EXISTS total_expenses NUMERIC(12, 2) DEFAULT 0 NOT NULL,
+ADD COLUMN IF NOT EXISTS approved_expenses NUMERIC(12, 2) DEFAULT 0 NOT NULL,
+ADD COLUMN IF NOT EXISTS pending_expenses NUMERIC(12, 2) DEFAULT 0 NOT NULL,
+ADD COLUMN IF NOT EXISTS rejected_expenses NUMERIC(12, 2) DEFAULT 0 NOT NULL,
+ADD COLUMN IF NOT EXISTS expense_claims_count INTEGER DEFAULT 0 NOT NULL;
+
+-- Add comments
+COMMENT ON COLUMN timesheets.total_expenses IS 'Total expense amount claimed this day';
+COMMENT ON COLUMN timesheets.approved_expenses IS 'Approved expense amount';
+COMMENT ON COLUMN timesheets.pending_expenses IS 'Pending approval amount';
+COMMENT ON COLUMN timesheets.rejected_expenses IS 'Rejected expense amount';
+COMMENT ON COLUMN timesheets.expense_claims_count IS 'Number of expense claims submitted';
+```
+
+---
+
+## Core Service Design
+
+### Service: `TimesheetRealtimeService`
+
+**File:** `src/app/services/timesheet_realtime_service.py`
+
+**Key Methods:**
+
+1. `update_timesheet_for_event(db, user_id, project_id, work_date, event_type, entity_type, entity_id)`
+   - Main entry point for all timesheet updates
+   - Validates work_date == today (immutability rule)
+   - Calls aggregation methods
+   - Upserts timesheet with optimistic locking
+   - Marks source record as synced
+
+
+### Ticket Completion (1 event)
+
+**File:** `src/app/api/v1/ticket_completion.py`
+
+7. **Ticket Marked Complete**
+   - Trigger: After ticket status changed to completed
+   - Updates: All assignments for this ticket
+   - Date: `ticket.completed_at.date()`
+   - Note: May update multiple agents' timesheets
+
+### Ticket Expenses (4 events)
+
+**File:** `src/app/api/v1/ticket_expenses.py`
+
+8. **Expense Created** (agent submits)
+   - Trigger: After expense created
+   - Updates: `total_expenses`, `pending_expenses`, `expense_claims_count`
+   - Date: `expense.expense_date` (must be TODAY)
+   - Validation: Reject if `expense.expense_date != TODAY`
+
+9. **Expense Updated** (agent edits before approval)
+   - Trigger: After expense amount changed
+   - Updates: Recalculate expense totals
+   - Date: `expense.expense_date`
+
+10. **Expense Approved** (manager approves)
+    - Trigger: After approval
+    - Updates: Move from `pending_expenses` to `approved_expenses`
+    - Date: `expense.expense_date`
+
+11. **Expense Rejected** (manager rejects)
+    - Trigger: After rejection
+    - Updates: Move from `pending_expenses` to `rejected_expenses`
+    - Date: `expense.expense_date`
+
+---
+
+## Implementation Details
+
+### Immutability Enforcement
+
+```python
+def update_timesheet_for_event(
+    db: Session,
+    user_id: UUID,
+    project_id: UUID,
+    work_date: date,
+    event_type: str,
+    entity_type: str,
+    entity_id: UUID
+) -> Optional[UUID]:
+    """
+    Update timesheet for an event.
+
+    IMMUTABILITY RULE: Only update if work_date == today
+    """
+    from datetime import date as date_class
+
+    # Enforce immutability
+    if work_date < date_class.today():
+        logger.warning(
+            f"Skipping timesheet update for past date: {work_date}. "
+            f"Event: {event_type}, Entity: {entity_type}:{entity_id}"
+        )
+        return None
+
+    # Only update today's timesheet
+    if work_date > date_class.today():
+        logger.warning(
+            f"Skipping timesheet update for future date: {work_date}. "
+            f"Event: {event_type}, Entity: {entity_type}:{entity_id}"
+        )
+        return None
+
+    # Proceed with update...
+```
+
+### Optimistic Locking with Retry
+
+```python
+def _upsert_timesheet_with_lock(
+    db: Session,
+    user_id: UUID,
+    project_id: UUID,
+    work_date: date,
+    metrics: dict,
+    max_retries: int = 3
+) -> Optional[UUID]:
+    """
+    Upsert timesheet with optimistic locking.
+    Retries on version conflict.
+    """
+    for attempt in range(max_retries):
+        try:
+            # Get existing timesheet
+            existing = db.query(Timesheet).filter(
+                Timesheet.user_id == user_id,
+                Timesheet.project_id == project_id,
+                Timesheet.work_date == work_date,
+                Timesheet.deleted_at.is_(None)
+            ).first()
+
+            if existing:
+                # UPDATE with version check
+                current_version = existing.version
+
+                result = db.query(Timesheet).filter(
+                    Timesheet.id == existing.id,
+                    Timesheet.version == current_version  # Optimistic lock
+                ).update(metrics)
+
+                if result == 0:
+                    # Version conflict - another update happened
+                    logger.warning(
+                        f"Optimistic lock conflict on timesheet {existing.id}. "
+                        f"Retry {attempt + 1}/{max_retries}"
+                    )
+                    db.rollback()
+                    continue  # Retry
+
+                db.commit()
+                return existing.id
+            else:
+                # INSERT new timesheet
+                new_timesheet = Timesheet(
+                    user_id=user_id,
+                    project_id=project_id,
+                    work_date=work_date,
+                    version=1,
+                    **metrics
+                )
+                db.add(new_timesheet)
+                db.commit()
+                return new_timesheet.id
+
+        except Exception as e:
+            logger.error(f"Error upserting timesheet: {e}")
+            db.rollback()
+            if attempt == max_retries - 1:
+                return None
+            continue
+
+    return None
+```
+
+### Aggregation Queries
+
+```python
+def _aggregate_ticket_metrics(
+    db: Session,
+    user_id: UUID,
+    project_id: UUID,
+    work_date: date
+) -> dict:
+    """
+    Aggregate ticket metrics for a specific day.
+
+    Uses MIN(journey_started_at) for check-in
+    Uses MAX(ended_at) for check-out
+    """
+    from sqlalchemy import func, case
+    from app.models.ticket_assignment import TicketAssignment
+    from app.models.ticket import Ticket
+
+    # Query assignments for this day
+    query = db.query(
+        # Count by action type
+        func.count(
+            case((TicketAssignment.action == 'assigned', 1))
+        ).label('tickets_assigned'),
+        func.count(
+            case((TicketAssignment.action == 'completed', 1))
+        ).label('tickets_completed'),
+        func.count(
+            case((TicketAssignment.action == 'rejected', 1))
+        ).label('tickets_rejected'),
+        func.count(
+            case((TicketAssignment.action == 'dropped', 1))
+        ).label('tickets_cancelled'),
+
+        # Check-in/out times
+        func.min(TicketAssignment.journey_started_at).label('check_in_time'),
+        func.max(TicketAssignment.ended_at).label('check_out_time')
+    ).join(
+        Ticket, TicketAssignment.ticket_id == Ticket.id
+    ).filter(
+        TicketAssignment.user_id == user_id,
+        Ticket.project_id == project_id,
+        func.date(TicketAssignment.assigned_at) == work_date,
+        TicketAssignment.deleted_at.is_(None),
+        Ticket.deleted_at.is_(None)
+    )
+
+    result = query.first()
+
+    # Calculate hours worked
+    hours_worked = None
+    if result.check_in_time and result.check_out_time:
+        delta = result.check_out_time - result.check_in_time
+        hours_worked = round(delta.total_seconds() / 3600, 2)
+
+    return {
+        'tickets_assigned': result.tickets_assigned or 0,
+        'tickets_completed': result.tickets_completed or 0,
+        'tickets_rejected': result.tickets_rejected or 0,
+        'tickets_cancelled': result.tickets_cancelled or 0,
+        'check_in_time': result.check_in_time,
+        'check_out_time': result.check_out_time,
+        'hours_worked': hours_worked
+    }
+
+
+def _aggregate_expense_metrics(
+    db: Session,
+    user_id: UUID,
+    project_id: UUID,
+    work_date: date
+) -> dict:
+    """
+    Aggregate expense metrics for a specific day.
+    """
+    from sqlalchemy import func, case
+    from app.models.ticket_expense import TicketExpense
+    from app.models.ticket import Ticket
+
+    query = db.query(
+        func.count(TicketExpense.id).label('expense_claims_count'),
+        func.sum(TicketExpense.amount).label('total_expenses'),
+        func.sum(
+            case((TicketExpense.is_approved == True, TicketExpense.amount), else_=0)
+        ).label('approved_expenses'),
+        func.sum(
+            case((TicketExpense.is_approved.is_(None), TicketExpense.amount), else_=0)
+        ).label('pending_expenses'),
+        func.sum(
+            case((TicketExpense.is_approved == False, TicketExpense.amount), else_=0)
+        ).label('rejected_expenses')
+    ).join(
+        Ticket, TicketExpense.ticket_id == Ticket.id
+    ).filter(
+        TicketExpense.incurred_by_user_id == user_id,
+        Ticket.project_id == project_id,
+        TicketExpense.expense_date == work_date,
+        TicketExpense.deleted_at.is_(None),
+        Ticket.deleted_at.is_(None)
+    )
+
+    result = query.first()
+
+    return {
+        'expense_claims_count': result.expense_claims_count or 0,
+        'total_expenses': float(result.total_expenses or 0),
+        'approved_expenses': float(result.approved_expenses or 0),
+        'pending_expenses': float(result.pending_expenses or 0),
+        'rejected_expenses': float(result.rejected_expenses or 0)
+    }
+```
+
+---
+
+## Error Handling Strategy
+
+### Graceful Degradation
+
+```python
+# In API endpoints (ticket_assignments.py, ticket_expenses.py, etc.)
+
+try:
+    from app.services.timesheet_realtime_service import update_timesheet_for_event
+    from datetime import date
+
+    # Main operation already succeeded
+    # Timesheet update is best-effort
+
+    timesheet_id = update_timesheet_for_event(
+        db=db,
+        user_id=assignment.user_id,
+        project_id=assignment.ticket.project_id,
+        work_date=date.today(),
+        event_type='assignment_created',
+        entity_type='ticket_assignment',
+        entity_id=assignment.id
+    )
+
+    if timesheet_id:
+        logger.info(f"Timesheet {timesheet_id} updated for assignment {assignment.id}")
+    else:
+        logger.warning(f"Failed to update timesheet for assignment {assignment.id}")
+
+except Exception as e:
+    # Don't let timesheet failures block main operation
+    logger.error(f"Timesheet update error: {e}", exc_info=True)
+    # Continue - main operation already succeeded
+```
+
+### Sync Tracking
+
+```python
+def _mark_entity_synced(
+    db: Session,
+    entity_type: str,
+    entity_id: UUID
+) -> bool:
+    """
+    Mark source entity as synced to timesheet.
+    """
+    try:
+        if entity_type == 'ticket_assignment':
+            db.query(TicketAssignment).filter(
+                TicketAssignment.id == entity_id
+            ).update({
+                'timesheet_synced': True,
+                'timesheet_synced_at': func.now()
+            })
+        elif entity_type == 'ticket_expense':
+            db.query(TicketExpense).filter(
+                TicketExpense.id == entity_id
+            ).update({
+                'timesheet_synced': True,
+                'timesheet_synced_at': func.now()
+            })
+        elif entity_type == 'ticket':
+            db.query(Ticket).filter(
+                Ticket.id == entity_id
+            ).update({
+                'timesheet_synced': True,
+                'timesheet_synced_at': func.now()
+            })
+
+        db.commit()
+        return True
+    except Exception as e:
+        logger.error(f"Failed to mark {entity_type}:{entity_id} as synced: {e}")
+        db.rollback()
+        return False
+```
+
+---
+
+## Manual Reconciliation API
+
+### Endpoint 1: Find Unsynced Records
+
+```python
+@router.get("/timesheets/unsynced-records")
+async def get_unsynced_records(
+    entity_type: str = Query(..., regex="^(assignment|expense|ticket)$"),
+    project_id: Optional[UUID] = None,
+    since: Optional[datetime] = None,
+    limit: int = Query(100, le=1000),
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Find records that failed to sync to timesheets.
+
+    Authorization: Project Manager, Dispatcher, Platform Admin
+    """
+    # Check permissions
+    if current_user.role not in ['project_manager', 'dispatcher', 'platform_admin']:
+        raise HTTPException(status_code=403, detail="Insufficient permissions")
+
+    # Query based on entity type
+    if entity_type == 'assignment':
+        query = db.query(TicketAssignment).filter(
+            TicketAssignment.timesheet_synced == False,
+            TicketAssignment.deleted_at.is_(None)
+        )
+        if project_id:
+            query = query.join(Ticket).filter(Ticket.project_id == project_id)
+        if since:
+            query = query.filter(TicketAssignment.created_at >= since)
+
+    # ... similar for expense and ticket
+
+    records = query.limit(limit).all()
+
+    return {
+        "entity_type": entity_type,
+        "count": len(records),
+        "records": records
+    }
+```
+
+### Endpoint 2: Reconcile Unsynced Records
+
+```python
+@router.post("/timesheets/reconcile-unsynced")
+async def reconcile_unsynced_records(
+    entity_type: str = Query(..., regex="^(assignment|expense|ticket)$"),
+    project_id: Optional[UUID] = None,
+    limit: int = Query(100, le=1000),
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Manually reconcile unsynced records.
+
+    Authorization: Project Manager, Platform Admin
+    """
+    # Check permissions
+    if current_user.role not in ['project_manager', 'platform_admin']:
+        raise HTTPException(status_code=403, detail="Insufficient permissions")
+
+    # Find unsynced records
+    # ... (same query as above)
+
+    success_count = 0
+    error_count = 0
+    errors = []
+
+    for record in records:
+        try:
+            timesheet_id = update_timesheet_for_event(
+                db=db,
+                user_id=record.user_id,
+                project_id=record.ticket.project_id,
+                work_date=record.assigned_at.date(),
+                event_type='manual_reconciliation',
+                entity_type=entity_type,
+                entity_id=record.id
+            )
+
+            if timesheet_id:
+                success_count += 1
+            else:
+                error_count += 1
+                errors.append(f"Failed to sync {entity_type}:{record.id}")
+
+        except Exception as e:
+            error_count += 1
+            errors.append(f"Error syncing {entity_type}:{record.id}: {str(e)}")
+
+    return {
+        "total_found": len(records),
+        "success_count": success_count,
+        "error_count": error_count,
+        "errors": errors
+    }
+```
+
+---
+
+## Testing Checklist
+
+### Unit Tests
+
+- [ ] Test aggregation queries return correct counts
+- [ ] Test optimistic locking conflict handling
+- [ ] Test immutability enforcement (skip past dates)
+- [ ] Test multi-project support (separate timesheets)
+- [ ] Test check-in/out calculation
+- [ ] Test expense metrics aggregation
+
+### Integration Tests
+
+- [ ] Create assignment → Verify timesheet updated
+- [ ] Complete ticket → Verify timesheet updated
+- [ ] Create expense → Verify timesheet updated
+- [ ] Approve expense → Verify pending moved to approved
+- [ ] Multi-project same day → Verify two timesheets
+- [ ] Concurrent updates → Verify no lost updates
+
+### Edge Cases
+
+- [ ] Past date event → Verify timesheet NOT updated
+- [ ] Future date event → Verify timesheet NOT updated
+- [ ] Deleted ticket → Verify past timesheet unchanged
+- [ ] Database error → Verify main operation succeeds
+- [ ] Unsynced records → Verify manual reconciliation works
+
+---
+
+## Deployment Checklist
+
+### Pre-Deployment
+
+- [ ] Run database migrations in staging
+- [ ] Verify no constraint violations
+- [ ] Test all integration points
+- [ ] Review error handling
+- [ ] Check performance (query times)
+
+### Deployment
+
+- [ ] Backup database
+- [ ] Run migrations in production
+- [ ] Deploy code changes
+- [ ] Monitor error logs for 1 hour
+- [ ] Spot-check timesheet accuracy
+
+### Post-Deployment
+
+- [ ] Verify no errors in logs
+- [ ] Check unsynced record count
+- [ ] Test payroll calculation
+- [ ] Monitor performance metrics
+- [ ] Document any issues
+
+---
+
+**Ready to implement!** 🚀
+
+2. `_aggregate_ticket_metrics(db, user_id, project_id, work_date)`
+   - Counts assignments by action type
+   - Returns: tickets_assigned, tickets_completed, tickets_rejected, tickets_cancelled
+
+3. `_aggregate_expense_metrics(db, user_id, project_id, work_date)`
+   - Sums expenses by approval status
+   - Returns: total_expenses, approved_expenses, pending_expenses, rejected_expenses, expense_claims_count
+
+4. `_calculate_check_times(db, user_id, project_id, work_date)`
+   - MIN(journey_started_at) as check_in
+   - MAX(ended_at) as check_out
+   - Returns: check_in_time, check_out_time, hours_worked
+
+5. `_upsert_timesheet_with_lock(db, user_id, project_id, work_date, metrics, version)`
+   - Upserts timesheet with optimistic locking
+   - Retries on version conflict (max 3 attempts)
+   - Returns: timesheet_id or None
+
+6. `_mark_entity_synced(db, entity_type, entity_id)`
+   - Updates source record: timesheet_synced = TRUE, timesheet_synced_at = NOW()
+
+---
+
+## Integration Points (11 Total)
+
+### Ticket Assignments (6 events)
+
+**File:** `src/app/api/v1/ticket_assignments.py`
+
+1. **Assignment Created** (dispatcher assigns)
+   - Trigger: After assignment created
+   - Updates: `tickets_assigned`
+   - Date: `assignment.assigned_at.date()`
+
+2. **Self-Assignment** (agent picks ticket)
+   - Trigger: After self-assignment
+   - Updates: `tickets_assigned`
+   - Date: `assignment.assigned_at.date()`
+
+3. **Assignment Accepted** (agent accepts)
+   - Trigger: After status change to accepted
+   - Updates: Refresh check-in time
+   - Date: `assignment.assigned_at.date()`
+
+4. **Assignment Rejected** (agent rejects)
+   - Trigger: After status change to rejected
+   - Updates: `tickets_rejected`
+   - Date: `assignment.assigned_at.date()`
+
+5. **Assignment Dropped** (agent can't complete)
+   - Trigger: After status change to dropped
+   - Updates: `tickets_cancelled`
+   - Date: `assignment.ended_at.date()`
+
+6. **Assignment Completed** (agent finishes)
+   - Trigger: After status change to completed
+   - Updates: `tickets_completed`
+   - Date: `assignment.ended_at.date()`
+
+

src/app/api/v1/expenses.py

@@ -10,7 +10,7 @@ Provides endpoints for:
 - Statistics and reporting
 """
 
-from fastapi import APIRouter, Depends, HTTPException, status, Query
+from fastapi import APIRouter, Depends, HTTPException, status, Query, BackgroundTasks
 from sqlalchemy.orm import Session
 from typing import Optional, List
 from uuid import UUID
@@ -254,12 +254,13 @@ def update_expense(
 def approve_expense(
     expense_id: UUID,
     data: TicketExpenseApprove,
+    background_tasks: BackgroundTasks,
     current_user: User = Depends(get_current_user),
     db: Session = Depends(get_db)
 ):
     """Approve or reject expense"""
     try:
-        expense = ExpenseService.approve_expense(db, expense_id, data, current_user.id)
+        expense = ExpenseService.approve_expense(db, expense_id, data, current_user.id, background_tasks)
         
         response = TicketExpenseResponse.model_validate(expense)
         response.incurred_by_user_name = expense.incurred_by_user.full_name if expense.incurred_by_user else None
@@ -375,12 +376,13 @@ def update_payment_details(
 def mark_expense_paid(
     expense_id: UUID,
     data: TicketExpenseMarkPaid,
+    background_tasks: BackgroundTasks,
     current_user: User = Depends(get_current_user),
     db: Session = Depends(get_db)
 ):
     """Mark expense as paid"""
     try:
-        expense = ExpenseService.mark_paid(db, expense_id, data)
+        expense = ExpenseService.mark_paid(db, expense_id, data, background_tasks)
         
         response = TicketExpenseResponse.model_validate(expense)
         response.incurred_by_user_name = expense.incurred_by_user.full_name if expense.incurred_by_user else None

src/app/api/v1/invoice_generation.py

@@ -7,7 +7,7 @@ Endpoints for:
 - Exporting invoices to CSV
 - Regenerating viewing tokens
 """
-from fastapi import APIRouter, Depends, HTTPException, Response, Query
+from fastapi import APIRouter, Depends, HTTPException, Response, Query, BackgroundTasks
 from sqlalchemy.orm import Session
 from typing import List, Optional
 from uuid import UUID
@@ -18,6 +18,7 @@ from app.api.deps import get_db, get_current_user
 from app.models.user import User
 from app.models.enums import AppRole
 from app.services.invoice_generation_service import InvoiceGenerationService
+from app.services.notification_delivery import NotificationDelivery
 from app.schemas.invoice_generation import (
     InvoiceGenerateRequest,
     AvailableTicketResponse,
@@ -121,6 +122,7 @@ def get_available_tickets(
 @router.post("/generate", response_model=InvoiceGenerateResponse)
 def generate_invoice(
     data: InvoiceGenerateRequest,
+    background_tasks: BackgroundTasks,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user)
 ):
@@ -181,8 +183,8 @@ def generate_invoice(
             )
     
     check_invoice_permission(current_user, contractor_id)
-    
-    invoice, viewing_link, csv_link = InvoiceGenerationService.generate_invoice_from_tickets(
+
+    invoice, viewing_link, csv_link, notification_ids = InvoiceGenerationService.generate_invoice_from_tickets(
         db=db,
         contractor_id=contractor_id,
         client_id=client_id,
@@ -191,7 +193,14 @@ def generate_invoice(
         invoice_metadata=data.dict(exclude={'ticket_ids', 'contractor_id', 'client_id', 'project_id'}),
         current_user=current_user
     )
-    
+
+    # Queue notification delivery (Tier 2 - Asynchronous)
+    if notification_ids:
+        NotificationDelivery.queue_bulk_delivery(
+            background_tasks=background_tasks,
+            notification_ids=notification_ids
+        )
+
     return InvoiceGenerateResponse(
         success=True,
         invoice_id=invoice.id,

src/app/api/v1/payroll.py

@@ -1,7 +1,7 @@
 """
 Payroll API Endpoints - Weekly payroll generation and management
 """
-from fastapi import APIRouter, Depends, HTTPException, status, Query, Request
+from fastapi import APIRouter, Depends, HTTPException, status, Query, Request, BackgroundTasks
 from sqlalchemy.orm import Session
 from typing import Optional, List
 from uuid import UUID
@@ -25,6 +25,8 @@ from app.schemas.payroll import (
 )
 from app.services.payroll_service import PayrollService
 from app.services.audit_service import AuditService
+from app.services.notification_creator import NotificationCreator
+from app.services.notification_delivery import NotificationDelivery
 from app.core.permissions import require_permission
 
 logger = logging.getLogger(__name__)
@@ -60,15 +62,18 @@ async def generate_payroll(
     **Business Rules:**
     - Pay period must be exactly 7 days (Monday-Sunday)
     - Cannot regenerate if already paid (unless force flag)
-    - Aggregates data from timesheets and ticket_assignments
+    - Aggregates data from timesheets
     - Uses compensation rates from project_roles
-    
+
     **Calculation:**
-    - flat_rate_amount: From project_role (weekly rate)
-    - ticket_earnings: (base_amount * tickets_closed) + commission
-    - hours_worked: Sum from timesheets (PRESENT status)
-    - days_worked: Count of PRESENT days
-    - total_amount: flat_rate + ticket_earnings + bonus - deductions
+    - base_earnings: Calculated from compensation_type:
+      * FIXED_RATE: days_worked × base_rate (or hours × base_rate for hourly)
+      * PER_UNIT: tickets_closed × per_unit_rate
+      * COMMISSION: ticket_value × commission_percentage
+      * FIXED_PLUS_COMMISSION: (days × base_rate) + (ticket_value × commission%)
+    - days_worked: Count of PRESENT days from timesheets
+    - tickets_closed: Count from timesheet ticket metrics
+    - total_amount: base_earnings + bonus - deductions
     
     **Response:**
     - success: True if generated, False if skipped
@@ -467,3 +472,277 @@ async def mark_payroll_as_paid(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail=f"Failed to mark payroll as paid: {str(e)}"
         )
+
+
+# ============================================
+# PAYROLL EXPORT FOR PAYMENT
+# ============================================
+
+@router.post("/export", status_code=status.HTTP_200_OK)
+@require_permission("manage_payroll")
+def export_payroll_for_payment(
+    background_tasks: BackgroundTasks,
+    from_date: date = Query(..., description="Period start date (inclusive)"),
+    to_date: date = Query(..., description="Period end date (inclusive)"),
+    project_id: Optional[UUID] = Query(None, description="Filter by project"),
+    user_id: Optional[UUID] = Query(None, description="Filter by user"),
+    request: Request = None,
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Export unpaid payroll to Tende Pay CSV format and mark as paid.
+
+    **How Payroll Works:**
+    1. Payroll is generated/updated in REAL-TIME when timesheets are created/updated
+    2. When timesheet is created, system checks if payroll exists for that user+project+period
+    3. If exists → UPDATE existing payroll | If not → CREATE new payroll
+    4. On payment day, manager exports payroll for the period
+    5. System retrieves MOST RECENT payout details at export time (not stored in payroll)
+    6. Manager reviews CSV + warnings, then exports
+    7. System marks exported payroll records as paid
+
+    **Authorization:**
+    - Platform admins
+    - Project managers
+
+    **Query Parameters:**
+    - from_date: Period start date (filters by period_start_date >= from_date)
+    - to_date: Period end date (filters by period_end_date <= to_date)
+    - project_id: Optional - filter by specific project
+    - user_id: Optional - filter by specific user
+
+    **Business Rules:**
+    - Only exports unpaid payroll (is_paid = false)
+    - Retrieves payment details from user's primary financial account AT EXPORT TIME
+    - Missing fields generate WARNINGS but do NOT fail the export
+    - ALL payroll records are exported (even with missing payment details)
+    - Marks all exported payroll as paid (irreversible)
+    - Sets payment_reference to PAYROLL_EXPORT_{timestamp}_{user_id}
+
+    **Payment Details (Retrieved at Export Time):**
+    - Fetched from user_financial_accounts (is_primary = true, is_active = true)
+    - Supports: mobile_money (M-Pesa), bank_transfer
+    - Missing/invalid details → WARNING (not failure)
+    - Manager can manually fix CSV before uploading to Tende Pay
+
+    **Narration Format:**
+    - "Payroll {period}: {days} days worked, {tickets} tickets closed, {amount} KES"
+    - Example: "Payroll 2024-12-02 to 2024-12-08: 5 days worked, 12 tickets closed, 5000 KES"
+
+    **Response:**
+    - CSV file with Tende Pay bulk payment format
+    - Warnings included as comments at end of file
+    - X-Warning-Count header with number of warnings
+    - X-Exported-Count header with number of payroll records exported
+
+    **Warnings (Non-Blocking):**
+    - User has no financial account → exported with empty payment details
+    - Invalid payment details → exported with warning
+    - Missing ID number → exported with empty ID field
+    - Unsupported payment method → exported with empty payment details
+
+    **Example:**
+    ```
+    POST /api/v1/payroll/export?from_date=2024-12-02&to_date=2024-12-08&project_id=xxx
+    ```
+    """
+    import csv
+    import io
+    from datetime import datetime
+    from fastapi.responses import StreamingResponse
+
+    try:
+        # Export payroll
+        csv_rows, warnings, exported_payroll_records = PayrollService.export_for_payment(
+            db=db,
+            from_date=from_date,
+            to_date=to_date,
+            current_user=current_user,
+            project_id=project_id,
+            user_id=user_id
+        )
+
+        # Generate Tende Pay CSV
+        output = io.StringIO()
+        if csv_rows:
+            # Tende Pay column order (must match template exactly)
+            fieldnames = [
+                "NAME",
+                "ID NUMBER",
+                "PHONE NUMBER",
+                "AMOUNT",
+                "PAYMENT MODE",
+                "BANK (Optional)",
+                "BANK ACCOUNT NO (Optional)",
+                "PAYBILL BUSINESS NO (Optional)",
+                "PAYBILL ACCOUNT NO (Optional)",
+                "BUY GOODS TILL NO (Optional)",
+                "BILL PAYMENT BILLER CODE (Optional)",
+                "BILL PAYMENT ACCOUNT NO (Optional)",
+                "NARRATION (OPTIONAL)"
+            ]
+            writer = csv.DictWriter(output, fieldnames=fieldnames)
+            writer.writeheader()
+            writer.writerows(csv_rows)
+
+        # Add warnings as comments at the end
+        if warnings:
+            output.write("\n# WARNINGS:\n")
+            for warning in warnings:
+                output.write(f"# {warning}\n")
+
+        output.seek(0)
+        filename = f"tende_pay_payroll_{from_date.isoformat()}_{to_date.isoformat()}_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}.csv"
+
+        # Log audit trail (keep async for now - separate concern)
+        await AuditService.log_action(
+            db=db,
+            user_id=current_user.id,
+            action="export_payroll_for_payment",
+            resource_type="payroll",
+            resource_id=None,
+            details={
+                "from_date": from_date.isoformat(),
+                "to_date": to_date.isoformat(),
+                "project_id": str(project_id) if project_id else None,
+                "user_id": str(user_id) if user_id else None,
+                "exported_count": len(csv_rows),
+                "warning_count": len(warnings)
+            },
+            ip_address=request.client.host if request and request.client else None
+        )
+
+        logger.info(
+            f"Exported {len(csv_rows)} payroll records for payment "
+            f"(period: {from_date} to {to_date}, warnings: {len(warnings)})"
+        )
+
+        # Create notifications (Tier 1 - Synchronous)
+        notifications_created = []
+        if exported_payroll_records:
+            # Calculate totals for manager notification
+            total_amount = sum(p.total_amount for p in exported_payroll_records)
+            total_days_worked = sum(p.days_worked or 0 for p in exported_payroll_records)
+            total_tickets_closed = sum(p.tickets_closed or 0 for p in exported_payroll_records)
+
+            # Create manager notification
+            manager_notification = NotificationCreator.create(
+                db=db,
+                user_id=current_user.id,
+                title=f"Payroll Export Complete: {len(exported_payroll_records)} records",
+                message=(
+                    f"Successfully exported payroll for period {from_date.isoformat()} to {to_date.isoformat()}.\n\n"
+                    f"📊 Summary:\n"
+                    f"• Workers: {len(exported_payroll_records)}\n"
+                    f"• Total Amount: {total_amount:,.2f} KES\n"
+                    f"• Total Days Worked: {total_days_worked}\n"
+                    f"• Total Tickets Closed: {total_tickets_closed}\n"
+                    f"• Warnings: {len(warnings)}"
+                ),
+                source_type="payroll",
+                source_id=None,  # Bulk export, no single ID
+                notification_type="payroll_exported",
+                channel="in_app",
+                project_id=project_id,
+                metadata={
+                    "payroll_count": len(exported_payroll_records),
+                    "total_amount": float(total_amount),
+                    "total_days_worked": total_days_worked,
+                    "total_tickets_closed": total_tickets_closed,
+                    "period_start": from_date.isoformat(),
+                    "period_end": to_date.isoformat(),
+                    "warning_count": len(warnings),
+                    "warnings": warnings[:10] if warnings else []  # First 10 warnings
+                }
+            )
+            notifications_created.append(manager_notification)
+
+            # Create worker notifications
+            for payroll in exported_payroll_records:
+                worker = db.query(User).filter(User.id == payroll.user_id).first()
+                if worker:
+                    # Build work breakdown message
+                    work_details = []
+                    if payroll.days_worked and payroll.days_worked > 0:
+                        work_details.append(f"{payroll.days_worked} days worked")
+                    if payroll.tickets_closed and payroll.tickets_closed > 0:
+                        work_details.append(f"{payroll.tickets_closed} tickets closed")
+
+                    work_summary = ", ".join(work_details) if work_details else "work completed"
+
+                    # Build earnings breakdown
+                    earnings_parts = []
+                    if payroll.base_earnings and payroll.base_earnings > 0:
+                        earnings_parts.append(f"Base: {payroll.base_earnings:,.2f} KES")
+                    if payroll.bonus_amount and payroll.bonus_amount > 0:
+                        earnings_parts.append(f"Bonus: {payroll.bonus_amount:,.2f} KES")
+                    if payroll.deductions and payroll.deductions > 0:
+                        earnings_parts.append(f"Deductions: -{payroll.deductions:,.2f} KES")
+
+                    earnings_breakdown = "\n".join([f"• {part}" for part in earnings_parts])
+
+                    worker_notification = NotificationCreator.create(
+                        db=db,
+                        user_id=worker.id,
+                        title=f"💰 Payment Processed: {payroll.total_amount:,.2f} KES",
+                        message=(
+                            f"Your payment for {from_date.isoformat()} to {to_date.isoformat()} has been processed.\n\n"
+                            f"📋 Work Summary:\n"
+                            f"• {work_summary}\n\n"
+                            f"💵 Earnings Breakdown:\n"
+                            f"{earnings_breakdown}\n\n"
+                            f"Total Payment: {payroll.total_amount:,.2f} KES"
+                        ),
+                        source_type="payroll",
+                        source_id=payroll.id,
+                        notification_type="payment",
+                        channel="whatsapp",  # Workers get WhatsApp notifications
+                        project_id=project_id,
+                        metadata={
+                            "payroll_id": str(payroll.id),
+                            "period_start": from_date.isoformat(),
+                            "period_end": to_date.isoformat(),
+                            "total_amount": float(payroll.total_amount),
+                            "base_earnings": float(payroll.base_earnings) if payroll.base_earnings else 0,
+                            "bonus_amount": float(payroll.bonus_amount) if payroll.bonus_amount else 0,
+                            "deductions": float(payroll.deductions) if payroll.deductions else 0,
+                            "days_worked": payroll.days_worked or 0,
+                            "tickets_closed": payroll.tickets_closed or 0
+                        }
+                    )
+                    notifications_created.append(worker_notification)
+
+            # Commit all notifications
+            db.commit()
+
+            logger.info(
+                f"Created {len(notifications_created)} notifications "
+                f"({len(exported_payroll_records)} workers + 1 manager)"
+            )
+
+            # Queue delivery for external channels (Tier 2 - Asynchronous)
+            NotificationDelivery.queue_bulk_delivery(
+                background_tasks=background_tasks,
+                notification_ids=[n.id for n in notifications_created]
+            )
+
+        # Return CSV file
+        return StreamingResponse(
+            iter([output.getvalue()]),
+            media_type="text/csv",
+            headers={
+                "Content-Disposition": f"attachment; filename={filename}",
+                "X-Warning-Count": str(len(warnings)),
+                "X-Exported-Count": str(len(csv_rows))
+            }
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error exporting payroll: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to export payroll: {str(e)}"
+        )

src/app/api/v1/projects.py

@@ -1,7 +1,7 @@
 """
 Projects API Endpoints - Complete CRUD with nested resources
 """
-from fastapi import APIRouter, Depends, HTTPException, status, Query, Request
+from fastapi import APIRouter, Depends, HTTPException, status, Query, Request, BackgroundTasks
 from sqlalchemy.orm import Session
 from sqlalchemy import or_
 from typing import Optional, List
@@ -701,6 +701,7 @@ async def update_project(
 async def complete_project_setup(
     project_id: UUID,
     setup_data: ProjectSetup,
+    background_tasks: BackgroundTasks,
     request: Request,
     current_user: User = Depends(get_current_active_user),
     db: Session = Depends(get_db)
@@ -728,7 +729,7 @@ async def complete_project_setup(
     - Project becomes ready for operations
     """
     try:
-        result = ProjectService.complete_project_setup(db, project_id, setup_data, current_user)
+        result = ProjectService.complete_project_setup(db, project_id, setup_data, current_user, background_tasks)
         
         # Audit log
         AuditService.log_action(
@@ -1894,10 +1895,17 @@ async def create_project_role(
     - compensation_type: flat_rate, commission, hourly, commission_plus_bonus, or custom
     
     **Compensation Requirements by Type:**
-    - flat_rate: Requires flat_rate_amount
-    - commission: Requires commission_percentage
-    - hourly: Requires hourly_rate
-    - commission_plus_bonus: Requires base_amount, commission_percentage
+    - FIXED_RATE: Requires base_rate + rate_period (HOUR, DAY, WEEK, MONTH)
+    - PER_UNIT: Requires per_unit_rate
+    - COMMISSION: Requires commission_percentage
+    - FIXED_PLUS_COMMISSION: Requires base_rate + rate_period + commission_percentage
+
+    **Examples:**
+    - Kenya daily worker: FIXED_RATE, base_rate=1000, rate_period=DAY
+    - USA hourly worker: FIXED_RATE, base_rate=25, rate_period=HOUR
+    - Per-ticket tech: PER_UNIT, per_unit_rate=500
+    - Sales agent: COMMISSION, commission_percentage=10
+    - Hybrid: FIXED_PLUS_COMMISSION, base_rate=500, rate_period=DAY, commission_percentage=5
     """
     try:
         role = ProjectService.create_project_role(db, project_id, role_data, current_user)

src/app/api/v1/sales_orders.py

@@ -17,7 +17,7 @@ Endpoints:
 - DELETE /sales-orders/{id} - Soft delete
 - GET /sales-orders/csv-template - Download CSV template
 """
-from fastapi import APIRouter, Depends, HTTPException, status, Query, UploadFile, File, Form
+from fastapi import APIRouter, Depends, HTTPException, status, Query, UploadFile, File, Form, BackgroundTasks
 from fastapi.responses import StreamingResponse
 from sqlalchemy.orm import Session
 from typing import Optional
@@ -32,6 +32,7 @@ from app.api.deps import get_db, get_current_user, get_current_active_user
 from app.models.user import User
 from app.models.enums import AppRole
 from app.services.sales_order_service import SalesOrderService
+from app.services.notification_delivery import NotificationDelivery
 from app.schemas.sales_order import *
 from app.schemas.filters import SalesOrderFilters
 from app.utils.phone_utils import normalize_kenyan_phone
@@ -300,6 +301,7 @@ async def import_sales_orders_from_csv(
     file: UploadFile = File(...),
     project_id: str = Form(...),
     project_region_id: Optional[str] = Form(None),
+    background_tasks: BackgroundTasks,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user)
 ):
@@ -413,7 +415,7 @@ async def import_sales_orders_from_csv(
         )
         
         # Bulk create
-        result = SalesOrderService.bulk_create_from_csv(db, import_data, current_user)
+        result = SalesOrderService.bulk_create_from_csv(db, import_data, current_user, background_tasks)
         
         # Add parse errors to row_results
         from app.schemas.sales_order import SalesOrderImportRowResult
@@ -868,6 +870,7 @@ async def promote_sales_order_to_ticket(
 @router.post("/bulk-promote", response_model=SalesOrderBulkPromoteResult)
 async def bulk_promote_sales_orders_to_tickets(
     data: SalesOrderBulkPromote,
+    background_tasks: BackgroundTasks,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user)
 ):
@@ -877,9 +880,9 @@ async def bulk_promote_sales_orders_to_tickets(
     Authorization: Checked by service for each order
     """
     try:
-        result = SalesOrderService.bulk_promote_to_tickets(db, data, current_user)
+        result = SalesOrderService.bulk_promote_to_tickets(db, data, current_user, background_tasks)
         logger.info(f"Bulk promote: {result.successful} successful, {result.failed} failed")
-        
+
         return result
     except HTTPException:
         raise

src/app/api/v1/tasks.py

@@ -1,7 +1,7 @@
 """
 Tasks API Endpoints - Infrastructure project task management
 """
-from fastapi import APIRouter, Depends, HTTPException, status, Query, Request
+from fastapi import APIRouter, Depends, HTTPException, status, Query, Request, BackgroundTasks
 from sqlalchemy.orm import Session
 from typing import Optional, List
 from uuid import UUID
@@ -83,6 +83,7 @@ def parse_task_filters(
 async def create_task(
     data: TaskCreate,
     request: Request,
+    background_tasks: BackgroundTasks,
     current_user: User = Depends(get_current_active_user),
     db: Session = Depends(get_db)
 ):
@@ -127,7 +128,7 @@ async def create_task(
     - Computed properties (is_completed, is_overdue, has_location, duration_days)
     """
     try:
-        task = TaskService.create_task(db, data, current_user)
+        task = TaskService.create_task(db, data, current_user, background_tasks)
         
         # Log audit trail
         await AuditService.log_action(
@@ -654,6 +655,7 @@ async def complete_task(
     task_id: UUID,
     data: TaskComplete,
     request: Request,
+    background_tasks: BackgroundTasks,
     current_user: User = Depends(get_current_active_user),
     db: Session = Depends(get_db)
 ):
@@ -665,7 +667,7 @@ async def complete_task(
     Auto-sets started_at if not already set.
     """
     try:
-        task = TaskService.complete_task(db, task_id, data, current_user)
+        task = TaskService.complete_task(db, task_id, data, current_user, background_tasks)
         
         # Log audit trail
         await AuditService.log_action(
@@ -709,6 +711,7 @@ async def cancel_task(
     task_id: UUID,
     data: TaskCancel,
     request: Request,
+    background_tasks: BackgroundTasks,
     current_user: User = Depends(get_current_active_user),
     db: Session = Depends(get_db)
 ):
@@ -720,7 +723,7 @@ async def cancel_task(
     Requires cancellation reason.
     """
     try:
-        task = TaskService.cancel_task(db, task_id, data, current_user)
+        task = TaskService.cancel_task(db, task_id, data, current_user, background_tasks)
         
         # Log audit trail
         await AuditService.log_action(

src/app/api/v1/ticket_assignments.py

@@ -8,7 +8,7 @@ Handles:
 - Queue management
 """
 
-from fastapi import APIRouter, Depends, HTTPException, status, Query
+from fastapi import APIRouter, Depends, HTTPException, status, Query, BackgroundTasks
 from sqlalchemy.orm import Session
 from typing import List, Optional
 from uuid import UUID
@@ -20,6 +20,8 @@ from app.api.deps import get_db, get_current_user
 from app.models.user import User
 from app.models.enums import AppRole
 from app.services.ticket_assignment_service import TicketAssignmentService
+from app.services.notification_creator import NotificationCreator
+from app.services.notification_delivery import NotificationDelivery
 from app.schemas.ticket_assignment import (
     TicketAssignCreate,
     TicketAssignTeamCreate,
@@ -511,11 +513,83 @@ def mark_customer_unavailable(
 def drop_assignment(
     assignment_id: UUID,
     data: AssignmentDrop,
+    background_tasks: BackgroundTasks,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user)
 ):
     service = TicketAssignmentService(db)
-    return service.drop_assignment(assignment_id, current_user.id, data)
+    result = service.drop_assignment(assignment_id, current_user.id, data)
+
+    # Create notifications for managers (Tier 1 - Synchronous)
+    try:
+        from app.models.ticket_assignment import TicketAssignment
+        from app.models.ticket import Ticket
+
+        # Get fresh assignment and ticket data
+        assignment = db.query(TicketAssignment).filter(TicketAssignment.id == assignment_id).first()
+        if assignment:
+            ticket = db.query(Ticket).filter(Ticket.id == assignment.ticket_id).first()
+            if ticket:
+                # Build drop reason message
+                drop_type_labels = {
+                    "equipment_issue": "Equipment Issue",
+                    "site_access_denied": "Site Access Denied",
+                    "customer_unavailable": "Customer Unavailable",
+                    "safety_concern": "Safety Concern",
+                    "other": "Other"
+                }
+                drop_type_label = drop_type_labels.get(data.drop_type, data.drop_type)
+
+                # Notify all managers and dispatchers in the project
+                notifications = NotificationCreator.notify_project_team(
+                    db=db,
+                    project_id=ticket.project_id,
+                    title="⚠️ Ticket Dropped - Action Required",
+                    message=(
+                        f"{current_user.name} dropped ticket: {ticket.ticket_name or ticket.ticket_type}\n\n"
+                        f"🔴 Reason: {drop_type_label}\n"
+                        f"💬 Details: {data.reason or 'No details provided'}\n\n"
+                        f"⚡ This ticket is now in PENDING REVIEW and needs your attention."
+                    ),
+                    source_type="ticket",
+                    source_id=ticket.id,
+                    notification_type="ticket_dropped",
+                    roles=[AppRole.PROJECT_MANAGER, AppRole.DISPATCHER],
+                    channel="in_app",
+                    exclude_user_ids=[current_user.id],  # Don't notify the agent who dropped
+                    metadata={
+                        "ticket_id": str(ticket.id),
+                        "ticket_name": ticket.ticket_name,
+                        "ticket_type": ticket.ticket_type,
+                        "assignment_id": str(assignment.id),
+                        "dropped_by_user_id": str(current_user.id),
+                        "dropped_by_name": current_user.name,
+                        "drop_type": data.drop_type,
+                        "reason": data.reason,
+                        "requires_action": True,
+                        "priority": "high",
+                        "action_url": f"/tickets/{ticket.id}"
+                    }
+                )
+
+                # Commit notifications
+                db.commit()
+
+                logger.info(
+                    f"Created {len(notifications)} drop notifications for ticket {ticket.id}"
+                )
+
+                # Queue delivery (Tier 2 - Asynchronous)
+                NotificationDelivery.queue_bulk_delivery(
+                    background_tasks=background_tasks,
+                    notification_ids=[n.id for n in notifications]
+                )
+
+    except Exception as e:
+        # Don't fail the request if notification fails
+        logger.warning(f"Failed to create drop notification: {str(e)}", exc_info=True)
+
+    return result
 
 
 @router.post(

src/app/api/v1/tickets.py

@@ -13,7 +13,7 @@ Authorization:
 - dispatcher: Their contractor's projects
 - client_admin: View only
 """
-from fastapi import APIRouter, Depends, status, Query
+from fastapi import APIRouter, Depends, status, Query, BackgroundTasks
 from sqlalchemy.orm import Session
 from typing import List, Optional
 from uuid import UUID
@@ -981,6 +981,7 @@ def reschedule_ticket(
 def cancel_ticket(
     ticket_id: UUID,
     data: TicketCancel,
+    background_tasks: BackgroundTasks,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user)
 ):
@@ -1008,7 +1009,8 @@ def cancel_ticket(
         db=db,
         ticket_id=ticket_id,
         data=data,
-        current_user=current_user
+        current_user=current_user,
+        background_tasks=background_tasks
     )
     
     return TicketResponse.from_orm(ticket)
@@ -1022,6 +1024,7 @@ def cancel_ticket(
 def reopen_ticket(
     ticket_id: UUID,
     data: TicketReopen,
+    background_tasks: BackgroundTasks,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user)
 ):
@@ -1052,7 +1055,8 @@ def reopen_ticket(
         db=db,
         ticket_id=ticket_id,
         data=data,
-        current_user=current_user
+        current_user=current_user,
+        background_tasks=background_tasks
     )
     
     return TicketResponse.from_orm(ticket)

src/app/models/enums.py

@@ -50,18 +50,30 @@ class ProjectStatus(str, enum.Enum):
 
 
 class CompensationType(str, enum.Enum):
-    """Compensation models"""
-    # NEW - Simple cash-based (recommended for Kenyan context)
-    PER_DAY = "per_day"           # Fixed daily rate (e.g., 1000 KES/day)
-    PER_WEEK = "per_week"         # Fixed weekly rate (e.g., 7000 KES/week)
-    PER_TICKET = "per_ticket"     # Fixed per ticket (e.g., 500 KES/ticket)
-    
-    # OLD - Keep for backward compatibility
-    FLAT_RATE = "flat_rate"       # Legacy: weekly flat rate
-    COMMISSION = "commission"     # Percentage-based earnings
-    HYBRID = "hybrid"             # Mixed compensation
-    HOURLY = "hourly"             # Hourly rate
-    CUSTOM = "custom"             # Fully flexible
+    """
+    Compensation models - Simplified global structure
+
+    Four types cover all compensation scenarios worldwide:
+    - FIXED_RATE: Time-based pay (hourly, daily, weekly, monthly)
+    - PER_UNIT: Work-based pay (per-ticket, per-job, per-item)
+    - COMMISSION: Percentage-based pay (sales commission)
+    - FIXED_PLUS_COMMISSION: Hybrid (base + commission)
+    """
+    FIXED_RATE = "FIXED_RATE"                      # Time-based: hourly, daily, weekly, monthly
+    PER_UNIT = "PER_UNIT"                          # Work-based: per-ticket, per-job
+    COMMISSION = "COMMISSION"                      # Percentage-based: sales commission
+    FIXED_PLUS_COMMISSION = "FIXED_PLUS_COMMISSION"  # Hybrid: base + commission
+
+
+class RatePeriod(str, enum.Enum):
+    """
+    Rate period for FIXED_RATE compensation
+    Defines the time unit for base_rate
+    """
+    HOUR = "HOUR"      # Hourly rate (e.g., $25/hour in USA)
+    DAY = "DAY"        # Daily rate (e.g., 1000 KES/day in Kenya)
+    WEEK = "WEEK"      # Weekly rate (e.g., 7000 KES/week)
+    MONTH = "MONTH"    # Monthly salary (e.g., 50000 KES/month)
 
 
 class TimesheetStatus(str, enum.Enum):

src/app/models/project.py

@@ -235,80 +235,72 @@ class ProjectRegion(BaseModel):
 class ProjectRole(BaseModel):
     """
     ProjectRole model - Defines roles and compensation within a project
-    Maps to 'project_roles' table in docs/schema/schema.sql
-    
-    Purpose: Define job functions and pay structures for project workers
-    Used primarily for casual workers paid weekly
-    Examples: 'Technician', 'Supervisor', 'Driver', 'Helper'
+
+    Simplified global compensation structure with 4 types:
+    - FIXED_RATE: Time-based pay (hourly, daily, weekly, monthly)
+    - PER_UNIT: Work-based pay (per-ticket, per-job)
+    - COMMISSION: Percentage-based pay (sales commission)
+    - FIXED_PLUS_COMMISSION: Hybrid (base + commission)
+
+    Examples:
+    - Kenya daily worker: FIXED_RATE, base_rate=1000, rate_period=DAY
+    - USA hourly worker: FIXED_RATE, base_rate=25, rate_period=HOUR
+    - Per-ticket tech: PER_UNIT, per_unit_rate=500
+    - Sales agent: COMMISSION, commission_percentage=10
+    - Hybrid: FIXED_PLUS_COMMISSION, base_rate=500, rate_period=DAY, commission_percentage=5
     """
     __tablename__ = "project_roles"
-    
+
     # Relationships
     project_id = Column(UUID(as_uuid=True), ForeignKey('projects.id', ondelete='CASCADE'), nullable=False)
-    
+
     # Role Definition
     role_name = Column(Text, nullable=False)  # e.g., 'Technician', 'Supervisor'
     description = Column(Text, nullable=True)
-    
+
     # Compensation Structure
     compensation_type = Column(String(50), nullable=False)  # CompensationType enum in DB
-    
-    # NEW - Simple cash-based fields (recommended)
-    daily_rate = Column(Numeric(precision=12, scale=2), nullable=True)  # Fixed daily rate (e.g., 1000 KES/day)
-    weekly_rate = Column(Numeric(precision=12, scale=2), nullable=True)  # Fixed weekly rate (e.g., 7000 KES/week)
-    per_ticket_rate = Column(Numeric(precision=12, scale=2), nullable=True)  # Fixed per ticket (e.g., 500 KES/ticket)
-    
-    # OLD - Keep for backward compatibility
-    flat_rate_amount = Column(Numeric(precision=12, scale=2), nullable=True)  # Legacy: weekly flat rate
-    commission_percentage = Column(Numeric(precision=5, scale=2), nullable=True)  # Commission per ticket
-    base_amount = Column(Numeric(precision=12, scale=2), nullable=True)  # Base amount per ticket
-    bonus_percentage = Column(Numeric(precision=5, scale=2), nullable=True)  # Bonus percentage
-    hourly_rate = Column(Numeric(precision=12, scale=2), nullable=True)  # Hourly rate
-    
+
+    # For FIXED_RATE and FIXED_PLUS_COMMISSION
+    base_rate = Column(Numeric(precision=12, scale=2), nullable=True)  # Base rate amount
+    rate_period = Column(String(10), nullable=True)  # RatePeriod enum: HOUR, DAY, WEEK, MONTH
+
+    # For PER_UNIT
+    per_unit_rate = Column(Numeric(precision=12, scale=2), nullable=True)  # Per-ticket/job rate
+
+    # For COMMISSION and FIXED_PLUS_COMMISSION
+    commission_percentage = Column(Numeric(precision=5, scale=2), nullable=True)  # Commission %
+
     # Status
     is_active = Column(Boolean, default=True, nullable=False)
-    
+
     # Relationships
     project = relationship("Project", back_populates="roles")
-    
+
     # Table constraints
     __table_args__ = (
-        # New simple fields
-        CheckConstraint(
-            'daily_rate IS NULL OR daily_rate >= 0',
-            name='chk_positive_daily_rate'
-        ),
+        # FIXED_RATE requires base_rate and rate_period
         CheckConstraint(
-            'weekly_rate IS NULL OR weekly_rate >= 0',
-            name='chk_positive_weekly_rate'
+            "compensation_type != 'FIXED_RATE' OR (base_rate IS NOT NULL AND base_rate >= 0 AND rate_period IS NOT NULL)",
+            name='chk_fixed_rate_fields'
         ),
+        # PER_UNIT requires per_unit_rate
         CheckConstraint(
-            'per_ticket_rate IS NULL OR per_ticket_rate >= 0',
-            name='chk_positive_per_ticket_rate'
+            "compensation_type != 'PER_UNIT' OR (per_unit_rate IS NOT NULL AND per_unit_rate >= 0)",
+            name='chk_per_unit_fields'
         ),
-        # Old fields (backward compatibility)
+        # COMMISSION requires commission_percentage
         CheckConstraint(
-            'flat_rate_amount IS NULL OR flat_rate_amount >= 0',
-            name='chk_positive_flat_rate'
+            "compensation_type != 'COMMISSION' OR (commission_percentage IS NOT NULL AND commission_percentage >= 0 AND commission_percentage <= 100)",
+            name='chk_commission_fields'
         ),
+        # FIXED_PLUS_COMMISSION requires base_rate, rate_period, and commission_percentage
         CheckConstraint(
-            'commission_percentage IS NULL OR (commission_percentage >= 0 AND commission_percentage <= 100)',
-            name='chk_valid_commission'
-        ),
-        CheckConstraint(
-            'base_amount IS NULL OR base_amount >= 0',
-            name='chk_positive_base_amount'
-        ),
-        CheckConstraint(
-            'bonus_percentage IS NULL OR (bonus_percentage >= 0 AND bonus_percentage <= 100)',
-            name='chk_valid_bonus'
-        ),
-        CheckConstraint(
-            'hourly_rate IS NULL OR hourly_rate >= 0',
-            name='chk_positive_hourly_rate'
+            "compensation_type != 'FIXED_PLUS_COMMISSION' OR (base_rate IS NOT NULL AND base_rate >= 0 AND rate_period IS NOT NULL AND commission_percentage IS NOT NULL AND commission_percentage >= 0 AND commission_percentage <= 100)",
+            name='chk_fixed_plus_commission_fields'
         ),
     )
-    
+
     def __repr__(self):
         return f"<ProjectRole(name='{self.role_name}', type='{self.compensation_type}')>"
 

src/app/models/ticket.py

@@ -98,7 +98,11 @@ class Ticket(BaseModel):
     # Metadata
     notes = Column(Text, nullable=True)
     additional_metadata = Column(JSONB, nullable=False, default=dict, server_default='{}')
-    
+
+    # Timesheet Sync Tracking
+    timesheet_synced = Column(Boolean, default=False, nullable=False)  # Has this been synced to timesheets?
+    timesheet_synced_at = Column(DateTime(timezone=True), nullable=True)  # When was it synced?
+
     # Concurrency Control (Optimistic Locking)
     version = Column(Integer, nullable=False, default=1)
     

src/app/models/ticket_assignment.py

@@ -77,6 +77,10 @@ class TicketAssignment(BaseModel):
     reason = Column(Text, nullable=True)  # Why assigned/dropped/rejected
     notes = Column(Text, nullable=True)
 
+    # Timesheet Sync Tracking
+    timesheet_synced = Column(Boolean, default=False, nullable=False)  # Has this been synced to timesheets?
+    timesheet_synced_at = Column(DateTime(timezone=True), nullable=True)  # When was it synced?
+
     # Relationships
     ticket = relationship("Ticket", back_populates="assignments", lazy="select")
     user = relationship("User", foreign_keys=[user_id], lazy="select")

src/app/models/ticket_expense.py

@@ -122,7 +122,11 @@ class TicketExpense(BaseModel):
         default={},
         server_default="{}"
     )  # Can store split details: {"split_with": ["user-id-1", "user-id-2"], "split_amount": 500}
-    
+
+    # Timesheet Sync Tracking
+    timesheet_synced = Column(Boolean, default=False, nullable=False)  # Has this been synced to timesheets?
+    timesheet_synced_at = Column(TIMESTAMP(timezone=True), nullable=True)  # When was it synced?
+
     # Timestamps inherited from BaseModel (created_at, updated_at, deleted_at)
     
     # Relationships

src/app/models/timesheet.py

@@ -53,17 +53,27 @@ class Timesheet(BaseModel):
     leave_reason = Column(Text, nullable=True)
     leave_approved_by_user_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
     
-    # Daily Ticket Metrics (calculated by daily cron job)
+    # Daily Ticket Metrics (updated in real-time)
     tickets_assigned = Column(Integer, default=0, nullable=False)  # Number of tickets assigned this day
     tickets_completed = Column(Integer, default=0, nullable=False)  # Number of tickets completed this day
     tickets_rescheduled = Column(Integer, default=0, nullable=False)  # Number of tickets rescheduled this day
     tickets_cancelled = Column(Integer, default=0, nullable=False)  # Number of tickets cancelled this day
     tickets_rejected = Column(Integer, default=0, nullable=False)  # Number of tickets rejected this day
+
+    # Daily Expense Metrics (updated in real-time)
+    total_expenses = Column(Numeric(12, 2), default=0, nullable=False)  # Total expense amount claimed
+    approved_expenses = Column(Numeric(12, 2), default=0, nullable=False)  # Approved expense amount
+    pending_expenses = Column(Numeric(12, 2), default=0, nullable=False)  # Pending approval amount
+    rejected_expenses = Column(Numeric(12, 2), default=0, nullable=False)  # Rejected expense amount
+    expense_claims_count = Column(Integer, default=0, nullable=False)  # Number of expense claims submitted
     
     # Payroll Linkage (tracks if this timesheet has been used in payroll calculation)
     is_payroll_generated = Column(Boolean, default=False, nullable=False)
     payroll_id = Column(UUID(as_uuid=True), ForeignKey("user_payroll.id", ondelete="SET NULL"), nullable=True, index=True)
     
+    # Optimistic Locking (prevents concurrent update conflicts)
+    version = Column(Integer, default=1, nullable=False)  # Auto-incremented by trigger on update
+
     # Metadata
     notes = Column(Text, nullable=True)
     additional_metadata = Column(JSONB, default={}, nullable=False)
@@ -76,7 +86,7 @@ class Timesheet(BaseModel):
     
     # Constraints
     __table_args__ = (
-        UniqueConstraint('user_id', 'work_date', name='uq_timesheets_user_date'),
+        UniqueConstraint('user_id', 'project_id', 'work_date', name='uq_timesheets_user_project_date'),
         CheckConstraint('hours_worked IS NULL OR (hours_worked >= 0 AND hours_worked <= 24)', name='chk_valid_hours'),
         CheckConstraint('check_out_time IS NULL OR check_in_time IS NULL OR check_out_time >= check_in_time', name='chk_check_times'),
     )

src/app/models/user_payroll.py

@@ -13,26 +13,32 @@ from app.models.base import BaseModel
 class UserPayroll(BaseModel):
     """
     User Payroll (Worker Compensation & Payment Tracking)
-    
+
     Tracks all work done by users and their compensation.
-    Used primarily for casual workers paid weekly.
-    Tracks tickets closed, bonuses, flat rates, and payment status.
-    
+    Used for all workers (casual, hourly, salaried).
+
     Key Features:
-    - Weekly pay periods (Monday-Sunday)
-    - Aggregated work summary (tickets, hours, days)
-    - Compensation breakdown (flat rate, ticket earnings, bonuses, deductions)
+    - Flexible pay periods (weekly, bi-weekly, monthly)
+    - Aggregated work summary from timesheets (tickets, days)
+    - Simple compensation: base_earnings + bonus - deductions
     - Payment tracking with reference numbers
     - Optimistic locking for concurrent updates
-    
+
     Business Rules:
     - One payroll record per user per project per pay period
     - period_end_date >= period_start_date
     - All amounts must be non-negative
-    - total_amount = flat_rate + ticket_earnings + bonus - deductions
+    - total_amount = base_earnings + bonus - deductions
     - Can only be paid once (is_paid flag)
     - Version column prevents race conditions during recalculation
-    
+
+    Compensation Calculation:
+    - base_earnings calculated from project_role compensation_type:
+      * FIXED_RATE: days_worked × base_rate (or hours × base_rate for hourly)
+      * PER_UNIT: tickets_closed × per_unit_rate
+      * COMMISSION: ticket_value × commission_percentage
+      * FIXED_PLUS_COMMISSION: (days × base_rate) + (ticket_value × commission%)
+
     Generation:
     - Automatically generated weekly (Monday morning for previous Mon-Sun)
     - Recalculated if timesheets are corrected
@@ -50,15 +56,13 @@ class UserPayroll(BaseModel):
     period_start_date = Column(Date, nullable=False, index=True)
     period_end_date = Column(Date, nullable=False, index=True)
     
-    # Work Summary (aggregated from timesheets and ticket_assignments)
+    # Work Summary (aggregated from timesheets)
     tickets_closed = Column(Integer, default=0, nullable=False)
-    hours_worked = Column(Numeric(10, 2), default=0, nullable=False)
     days_worked = Column(Integer, default=0, nullable=False)
-    
+
     # Compensation Breakdown
-    flat_rate_amount = Column(Numeric(12, 2), default=0, nullable=False)  # Weekly flat rate
-    ticket_earnings = Column(Numeric(12, 2), default=0, nullable=False)   # Earnings from tickets
-    bonus_amount = Column(Numeric(12, 2), default=0, nullable=False)       # Performance bonuses
+    base_earnings = Column(Numeric(12, 2), default=0, nullable=False)     # Calculated from compensation_type
+    bonus_amount = Column(Numeric(12, 2), default=0, nullable=False)       # Performance bonuses (manual)
     deductions = Column(Numeric(12, 2), default=0, nullable=False)         # Deductions (advances, etc.)
     total_amount = Column(Numeric(12, 2), nullable=False)                  # Total compensation
     
@@ -87,14 +91,12 @@ class UserPayroll(BaseModel):
     
     # Constraints
     __table_args__ = (
-        UniqueConstraint('user_id', 'project_id', 'period_start_date', 'period_end_date', 
+        UniqueConstraint('user_id', 'project_id', 'period_start_date', 'period_end_date',
                         name='uq_user_payroll_period'),
         CheckConstraint('period_end_date >= period_start_date', name='chk_valid_period'),
         CheckConstraint('tickets_closed >= 0', name='chk_positive_tickets'),
-        CheckConstraint('hours_worked >= 0', name='chk_positive_hours'),
         CheckConstraint('days_worked >= 0', name='chk_positive_days'),
-        CheckConstraint('flat_rate_amount >= 0', name='chk_positive_flat_rate'),
-        CheckConstraint('ticket_earnings >= 0', name='chk_positive_ticket_earnings'),
+        CheckConstraint('base_earnings >= 0', name='chk_positive_base_earnings'),
         CheckConstraint('bonus_amount >= 0', name='chk_positive_bonus'),
         CheckConstraint('deductions >= 0', name='chk_positive_deductions'),
         CheckConstraint('total_amount >= 0', name='chk_positive_total'),
@@ -117,7 +119,7 @@ class UserPayroll(BaseModel):
     @property
     def net_earnings(self) -> Decimal:
         """Calculate net earnings (before deductions)"""
-        return Decimal(self.flat_rate_amount or 0) + Decimal(self.ticket_earnings or 0) + Decimal(self.bonus_amount or 0)
+        return Decimal(self.base_earnings or 0) + Decimal(self.bonus_amount or 0)
     
     def calculate_total(self) -> Decimal:
         """Calculate total compensation amount"""
@@ -145,10 +147,8 @@ class UserPayroll(BaseModel):
     def recalculate_from_data(
         self,
         tickets_closed: int,
-        hours_worked: Decimal,
         days_worked: int,
-        flat_rate: Decimal,
-        ticket_earnings: Decimal,
+        base_earnings: Decimal,
         bonus: Decimal = Decimal('0'),
         deductions: Decimal = Decimal('0'),
         calculation_notes: Optional[str] = None
@@ -156,16 +156,14 @@ class UserPayroll(BaseModel):
         """Recalculate payroll from fresh data (used when timesheets are corrected)"""
         if self.is_paid:
             raise ValueError("Cannot recalculate paid payroll")
-        
+
         self.tickets_closed = tickets_closed
-        self.hours_worked = hours_worked
         self.days_worked = days_worked
-        self.flat_rate_amount = flat_rate
-        self.ticket_earnings = ticket_earnings
+        self.base_earnings = base_earnings
         self.bonus_amount = bonus
         self.deductions = deductions
         self.total_amount = self.calculate_total()
-        
+
         if calculation_notes:
             self.calculation_notes = calculation_notes
         

src/app/schemas/notification.py

@@ -38,6 +38,7 @@ class NotificationSourceType(str, Enum):
     SALES_ORDER = "sales_order"
     INCIDENT = "incident"
     TASK = "task"
+    PAYROLL = "payroll"
     SYSTEM = "system"
     USER = "user"
 
@@ -56,6 +57,9 @@ class NotificationType(str, Enum):
     REMINDER = "reminder"
     ALERT = "alert"
     INFO = "info"
+    PAYMENT = "payment"
+    PAYROLL_EXPORTED = "payroll_exported"
+    TICKET_DROPPED = "ticket_dropped"
 
 
 # ============================================

src/app/schemas/payroll.py

@@ -56,8 +56,7 @@ class PayrollBatchGenerateRequest(BaseModel):
 
 class PayrollUpdateRequest(BaseModel):
     """Request to update payroll details (before payment)"""
-    flat_rate_amount: Optional[Decimal] = Field(None, ge=0, description="Weekly flat rate")
-    ticket_earnings: Optional[Decimal] = Field(None, ge=0, description="Earnings from tickets")
+    base_earnings: Optional[Decimal] = Field(None, ge=0, description="Base earnings (calculated from compensation)")
     bonus_amount: Optional[Decimal] = Field(None, ge=0, description="Performance bonuses")
     deductions: Optional[Decimal] = Field(None, ge=0, description="Deductions (advances, etc.)")
     calculation_notes: Optional[str] = Field(None, max_length=1000, description="Notes about calculation")
@@ -96,12 +95,10 @@ class PayrollResponse(BaseModel):
     
     # Work Summary
     tickets_closed: int
-    hours_worked: Decimal
     days_worked: int
-    
+
     # Compensation Breakdown
-    flat_rate_amount: Decimal
-    ticket_earnings: Decimal
+    base_earnings: Decimal
     bonus_amount: Decimal
     deductions: Decimal
     total_amount: Decimal

src/app/schemas/project.py

@@ -363,47 +363,64 @@ class ProjectRoleBase(BaseModel):
     """Base schema for project role"""
     role_name: str = Field(..., min_length=1, max_length=100, description="Role name")
     description: Optional[str] = None
-    compensation_type: Literal[
-        "per_day", "per_week", "per_ticket",  # NEW - Simple types
-        "flat_rate", "commission", "hybrid", "hourly", "custom"  # OLD - Backward compatibility
-    ]
+    compensation_type: Literal["FIXED_RATE", "PER_UNIT", "COMMISSION", "FIXED_PLUS_COMMISSION"]
 
 
 class ProjectRoleCreate(ProjectRoleBase):
-    """Schema for creating a project role"""
-    # NEW - Simple cash-based fields (recommended)
-    daily_rate: Optional[Decimal] = Field(None, ge=0, description="Fixed daily rate (e.g., 1000 KES/day)")
-    weekly_rate: Optional[Decimal] = Field(None, ge=0, description="Fixed weekly rate (e.g., 7000 KES/week)")
-    per_ticket_rate: Optional[Decimal] = Field(None, ge=0, description="Fixed per ticket (e.g., 500 KES/ticket)")
-    
-    # OLD - Keep for backward compatibility
-    flat_rate_amount: Optional[Decimal] = Field(None, ge=0, description="Legacy: Weekly flat rate")
-    commission_percentage: Optional[Decimal] = Field(None, ge=0, le=100, description="Commission %")
-    base_amount: Optional[Decimal] = Field(None, ge=0, description="Base amount per ticket")
-    bonus_percentage: Optional[Decimal] = Field(None, ge=0, le=100, description="Bonus %")
-    hourly_rate: Optional[Decimal] = Field(None, ge=0, description="Hourly rate")
+    """
+    Schema for creating a project role
+
+    Field requirements by compensation_type:
+    - FIXED_RATE: base_rate + rate_period required
+    - PER_UNIT: per_unit_rate required
+    - COMMISSION: commission_percentage required
+    - FIXED_PLUS_COMMISSION: base_rate + rate_period + commission_percentage required
+    """
+    # For FIXED_RATE and FIXED_PLUS_COMMISSION
+    base_rate: Optional[Decimal] = Field(None, ge=0, description="Base rate amount (e.g., 1000 KES/day, 25 USD/hour)")
+    rate_period: Optional[Literal["HOUR", "DAY", "WEEK", "MONTH"]] = Field(None, description="Time period for base_rate")
+
+    # For PER_UNIT
+    per_unit_rate: Optional[Decimal] = Field(None, ge=0, description="Per-ticket/job rate (e.g., 500 KES/ticket)")
+
+    # For COMMISSION and FIXED_PLUS_COMMISSION
+    commission_percentage: Optional[Decimal] = Field(None, ge=0, le=100, description="Commission percentage (0-100)")
+
+    @model_validator(mode='after')
+    def validate_compensation_fields(self):
+        """Validate that required fields are provided based on compensation_type"""
+        comp_type = self.compensation_type
+
+        if comp_type == "FIXED_RATE":
+            if not self.base_rate or not self.rate_period:
+                raise ValueError("FIXED_RATE requires base_rate and rate_period")
+
+        elif comp_type == "PER_UNIT":
+            if not self.per_unit_rate:
+                raise ValueError("PER_UNIT requires per_unit_rate")
+
+        elif comp_type == "COMMISSION":
+            if not self.commission_percentage:
+                raise ValueError("COMMISSION requires commission_percentage")
+
+        elif comp_type == "FIXED_PLUS_COMMISSION":
+            if not self.base_rate or not self.rate_period or not self.commission_percentage:
+                raise ValueError("FIXED_PLUS_COMMISSION requires base_rate, rate_period, and commission_percentage")
+
+        return self
 
 
 class ProjectRoleUpdate(BaseModel):
     """Schema for updating a project role"""
     role_name: Optional[str] = Field(None, min_length=1, max_length=100)
     description: Optional[str] = None
-    compensation_type: Optional[Literal[
-        "per_day", "per_week", "per_ticket",
-        "flat_rate", "commission", "hybrid", "hourly", "custom"
-    ]] = None
-    
-    # NEW - Simple fields
-    daily_rate: Optional[Decimal] = Field(None, ge=0)
-    weekly_rate: Optional[Decimal] = Field(None, ge=0)
-    per_ticket_rate: Optional[Decimal] = Field(None, ge=0)
-    
-    # OLD - Backward compatibility
-    flat_rate_amount: Optional[Decimal] = Field(None, ge=0)
+    compensation_type: Optional[Literal["FIXED_RATE", "PER_UNIT", "COMMISSION", "FIXED_PLUS_COMMISSION"]] = None
+
+    # Compensation fields
+    base_rate: Optional[Decimal] = Field(None, ge=0)
+    rate_period: Optional[Literal["HOUR", "DAY", "WEEK", "MONTH"]] = None
+    per_unit_rate: Optional[Decimal] = Field(None, ge=0)
     commission_percentage: Optional[Decimal] = Field(None, ge=0, le=100)
-    base_amount: Optional[Decimal] = Field(None, ge=0)
-    bonus_percentage: Optional[Decimal] = Field(None, ge=0, le=100)
-    hourly_rate: Optional[Decimal] = Field(None, ge=0)
     is_active: Optional[bool] = None
 
 
@@ -411,23 +428,17 @@ class ProjectRoleResponse(ProjectRoleBase):
     """Schema for project role response"""
     id: UUID
     project_id: UUID
-    
-    # NEW - Simple fields
-    daily_rate: Optional[Decimal]
-    weekly_rate: Optional[Decimal]
-    per_ticket_rate: Optional[Decimal]
-    
-    # OLD - Backward compatibility
-    flat_rate_amount: Optional[Decimal]
+
+    # Compensation fields
+    base_rate: Optional[Decimal]
+    rate_period: Optional[str]
+    per_unit_rate: Optional[Decimal]
     commission_percentage: Optional[Decimal]
-    base_amount: Optional[Decimal]
-    bonus_percentage: Optional[Decimal]
-    hourly_rate: Optional[Decimal]
-    
+
     is_active: bool
     created_at: datetime
     updated_at: datetime
-    
+
     class Config:
         from_attributes = True
 

src/app/services/expense_service.py

@@ -10,12 +10,15 @@ Handles:
 
 from sqlalchemy.orm import Session, joinedload
 from sqlalchemy import func, and_, or_
-from typing import Optional, List, Dict
+from typing import Optional, List, Dict, TYPE_CHECKING
 from uuid import UUID
 from decimal import Decimal
 from datetime import datetime
 from fastapi import HTTPException, status
 
+if TYPE_CHECKING:
+    from fastapi import BackgroundTasks
+
 from app.models.ticket_expense import TicketExpense
 from app.models.ticket_assignment import TicketAssignment
 from app.models.ticket import Ticket
@@ -30,6 +33,8 @@ from app.schemas.ticket_expense import (
     PaymentMethod,
 )
 from app.core.exceptions import NotFoundException, ValidationException
+from app.services.notification_creator import NotificationCreator
+from app.services.notification_delivery import NotificationDelivery
 import logging
 
 logger = logging.getLogger(__name__)
@@ -100,34 +105,61 @@ class ExpenseService:
             f"location_verified={location_verified}"
         )
         
-        # Notify PM/Dispatcher about expense submission for approval
+        # Create notifications for PM/Dispatcher about expense submission (Tier 1 - Synchronous)
         try:
-            from app.services.notification_helper import NotificationHelper
+            from app.services.notification_creator import NotificationCreator
             from app.models.user import User
-            import asyncio
-            
+            from app.models.ticket import Ticket
+            from app.models.enums import AppRole
+
             # Get the submitting user
             submitted_by = db.query(User).filter(User.id == incurred_by_user_id).first()
-            
+
             # Get ticket to find project
-            from app.models.ticket import Ticket
             ticket = db.query(Ticket).filter(Ticket.id == assignment.ticket_id).first()
-            
+
             if submitted_by and ticket:
-                # Get PMs and dispatchers for this project
-                notify_users = NotificationHelper.get_project_managers_and_dispatchers(db, ticket.project_id)
-                
-                if notify_users:
-                    asyncio.create_task(
-                        NotificationHelper.notify_expense_submitted(
-                            db=db,
-                            expense=expense,
-                            submitted_by=submitted_by,
-                            notify_users=notify_users
-                        )
-                    )
+                # Create notifications for all PMs and dispatchers in the project
+                notifications = NotificationCreator.notify_project_team(
+                    db=db,
+                    project_id=ticket.project_id,
+                    title=f"💰 Expense Submitted: {data.total_cost:,.2f} KES",
+                    message=(
+                        f"{submitted_by.name} submitted an expense for approval.\n\n"
+                        f"📋 Details:\n"
+                        f"• Category: {data.category}\n"
+                        f"• Amount: {data.total_cost:,.2f} KES\n"
+                        f"• Ticket: {ticket.ticket_name or ticket.ticket_type}\n"
+                        f"• Description: {data.description or 'No description'}\n\n"
+                        f"⚡ Please review and approve/reject this expense."
+                    ),
+                    source_type="expense",
+                    source_id=expense.id,
+                    notification_type="expense_submitted",
+                    roles=[AppRole.PROJECT_MANAGER, AppRole.DISPATCHER],
+                    channel="in_app",
+                    metadata={
+                        "expense_id": str(expense.id),
+                        "ticket_id": str(ticket.id),
+                        "ticket_name": ticket.ticket_name,
+                        "submitted_by_user_id": str(submitted_by.id),
+                        "submitted_by_name": submitted_by.name,
+                        "category": data.category,
+                        "total_cost": float(data.total_cost),
+                        "requires_action": True,
+                        "action_url": f"/expenses/{expense.id}"
+                    }
+                )
+
+                # Commit notifications
+                db.commit()
+
+                logger.info(
+                    f"Created {len(notifications)} expense submission notifications for expense {expense.id}"
+                )
+
         except Exception as e:
-            logger.error(f"Failed to send expense submission notification: {str(e)}")
+            logger.error(f"Failed to create expense submission notification: {str(e)}", exc_info=True)
         
         return expense
     
@@ -304,7 +336,8 @@ class ExpenseService:
         db: Session,
         expense_id: UUID,
         data: TicketExpenseApprove,
-        approved_by_user_id: UUID
+        approved_by_user_id: UUID,
+        background_tasks: Optional['BackgroundTasks'] = None
     ) -> TicketExpense:
         """
         Approve or reject an expense
@@ -344,35 +377,59 @@ class ExpenseService:
         status = "approved" if data.is_approved else "rejected"
         logger.info(f"Expense {expense_id} {status} by user {approved_by_user_id}")
         
-        # Notify agent about approval/rejection
+        # Notify agent about approval/rejection (Tier 1 - Synchronous)
         try:
-            from app.services.notification_helper import NotificationHelper
-            from app.models.user import User
-            import asyncio
-            
             # Get the agent who submitted the expense
             agent = db.query(User).filter(User.id == expense.incurred_by_user_id).first()
             approver = db.query(User).filter(User.id == approved_by_user_id).first()
-            
+
             if agent and approver:
                 if data.is_approved:
-                    asyncio.create_task(
-                        NotificationHelper.notify_expense_approved(
-                            db=db,
-                            expense=expense,
-                            approved_by=approver,
-                            agent=agent
-                        )
+                    notification = NotificationCreator.create(
+                        db=db,
+                        user_id=agent.id,
+                        title=f"✅ Expense Approved",
+                        message=f"Your expense of {expense.total_cost} {expense.currency} has been approved by {approver.full_name}.",
+                        source_type="expense",
+                        source_id=expense.id,
+                        notification_type="expense_approved",
+                        channel="in_app",
+                        project_id=expense.ticket.project_id if expense.ticket else None,
+                        metadata={
+                            "expense_id": str(expense.id),
+                            "amount": str(expense.total_cost),
+                            "currency": expense.currency,
+                            "approved_by": approver.full_name,
+                            "action_url": f"/expenses/{expense.id}"
+                        }
                     )
                 else:
-                    asyncio.create_task(
-                        NotificationHelper.notify_expense_rejected(
-                            db=db,
-                            expense=expense,
-                            rejected_by=approver,
-                            agent=agent,
-                            reason=data.rejection_reason or "No reason provided"
-                        )
+                    notification = NotificationCreator.create(
+                        db=db,
+                        user_id=agent.id,
+                        title=f"❌ Expense Rejected",
+                        message=f"Your expense of {expense.total_cost} {expense.currency} was rejected by {approver.full_name}.\n\nReason: {data.rejection_reason or 'No reason provided'}",
+                        source_type="expense",
+                        source_id=expense.id,
+                        notification_type="expense_rejected",
+                        channel="in_app",
+                        project_id=expense.ticket.project_id if expense.ticket else None,
+                        metadata={
+                            "expense_id": str(expense.id),
+                            "amount": str(expense.total_cost),
+                            "currency": expense.currency,
+                            "rejected_by": approver.full_name,
+                            "rejection_reason": data.rejection_reason,
+                            "action_url": f"/expenses/{expense.id}"
+                        }
+                    )
+                db.commit()
+
+                # Queue delivery (Tier 2 - Asynchronous)
+                if background_tasks:
+                    NotificationDelivery.queue_delivery(
+                        background_tasks=background_tasks,
+                        notification_id=notification.id
                     )
         except Exception as e:
             logger.error(f"Failed to send expense approval/rejection notification: {str(e)}")
@@ -383,7 +440,8 @@ class ExpenseService:
     def mark_paid(
         db: Session,
         expense_id: UUID,
-        data: TicketExpenseMarkPaid
+        data: TicketExpenseMarkPaid,
+        background_tasks: Optional['BackgroundTasks'] = None
     ) -> TicketExpense:
         """
         Mark expense as paid
@@ -432,25 +490,41 @@ class ExpenseService:
             f"reference={data.payment_reference}"
         )
         
-        # Notify agent about payment
+        # Notify agent about payment (Tier 1 - Synchronous)
         try:
-            from app.services.notification_helper import NotificationHelper
-            from app.models.user import User
-            import asyncio
-            
             # Get the agent who submitted the expense
             agent = db.query(User).filter(User.id == expense.incurred_by_user_id).first()
-            paid_by = db.query(User).filter(User.id == data.paid_to_user_id).first()
-            
-            if agent and paid_by:
-                asyncio.create_task(
-                    NotificationHelper.notify_expense_paid(
-                        db=db,
-                        expense=expense,
-                        paid_by=paid_by,
-                        agent=agent
-                    )
+            paid_to = db.query(User).filter(User.id == data.paid_to_user_id).first()
+
+            if agent:
+                notification = NotificationCreator.create(
+                    db=db,
+                    user_id=agent.id,
+                    title=f"💰 Expense Paid",
+                    message=f"Your expense of {expense.total_cost} {expense.currency} has been paid.\n\nPayment Method: {expense.payment_method}\nReference: {data.payment_reference or 'N/A'}",
+                    source_type="expense",
+                    source_id=expense.id,
+                    notification_type="expense_paid",
+                    channel="in_app",
+                    project_id=expense.ticket.project_id if expense.ticket else None,
+                    metadata={
+                        "expense_id": str(expense.id),
+                        "amount": str(expense.total_cost),
+                        "currency": expense.currency,
+                        "payment_method": expense.payment_method,
+                        "payment_reference": data.payment_reference,
+                        "paid_to": paid_to.full_name if paid_to else None,
+                        "action_url": f"/expenses/{expense.id}"
+                    }
                 )
+                db.commit()
+
+                # Queue delivery (Tier 2 - Asynchronous)
+                if background_tasks:
+                    NotificationDelivery.queue_delivery(
+                        background_tasks=background_tasks,
+                        notification_id=notification.id
+                    )
         except Exception as e:
             logger.error(f"Failed to send expense payment notification: {str(e)}")
         

src/app/services/invoice_generation_service.py

@@ -30,6 +30,7 @@ from app.models.project import Project
 from app.models.audit_log import AuditLog
 from app.models.enums import TicketStatus, TicketSource, AppRole, AuditAction
 from app.services.contractor_invoice_service import ContractorInvoiceService
+from app.services.notification_creator import NotificationCreator
 
 logger = logging.getLogger(__name__)
 
@@ -115,12 +116,12 @@ class InvoiceGenerationService:
         ticket_ids: List[UUID],
         invoice_metadata: Dict,
         current_user: User
-    ) -> Tuple[ContractorInvoice, str, str]:
+    ) -> Tuple[ContractorInvoice, str, str, List[UUID]]:
         """
         Generate invoice from selected tickets.
         No pricing required - just proof of work.
-        
-        Returns: (invoice, viewing_link, csv_download_link)
+
+        Returns: (invoice, viewing_link, csv_download_link, notification_ids)
         
         Steps:
         1. Validate tickets are completed and not invoiced
@@ -225,7 +226,8 @@ class InvoiceGenerationService:
         viewing_link = f"{base_url}/invoices/view?token={viewing_token}"
         csv_link = f"{base_url}/api/v1/invoices/{invoice.id}/export/csv"
         
-        # Create notifications for ALL PMs in the project
+        # Create notifications for ALL PMs in the project (Tier 1 - Synchronous)
+        notification_ids = []
         project = db.query(Project).filter(Project.id == project_id).first()
         if project:
             # Get all PMs for this contractor
@@ -235,19 +237,19 @@ class InvoiceGenerationService:
                 User.is_active == True,
                 User.deleted_at.is_(None)
             ).all()
-            
+
             for pm in pms:
-                notification = Notification(
+                notification = NotificationCreator.create(
+                    db=db,
                     user_id=pm.id,
-                    project_id=project_id,
-                    source_type="contractor_invoice",
-                    source_id=invoice.id,
                     title=f"Invoice {invoice.invoice_number} Generated",
                     message=f"Work completion invoice created for {len(tickets)} tickets. View and download CSV.",
+                    source_type="contractor_invoice",
+                    source_id=invoice.id,
                     notification_type="invoice_generated",
-                    channel=NotificationChannel.IN_APP,
-                    status=NotificationStatus.PENDING,
-                    additional_metadata={
+                    channel="in_app",
+                    project_id=project_id,
+                    metadata={
                         "invoice_id": str(invoice.id),
                         "invoice_number": invoice.invoice_number,
                         "ticket_ids": [str(t.id) for t in tickets],
@@ -255,14 +257,14 @@ class InvoiceGenerationService:
                         "viewing_link": viewing_link,
                         "csv_download_link": csv_link,
                         "sales_order_numbers": [
-                            item.get('sales_order_number') 
-                            for item in line_items 
+                            item.get('sales_order_number')
+                            for item in line_items
                             if item.get('sales_order_number')
                         ]
                     }
                 )
-                db.add(notification)
-        
+                notification_ids.append(notification.id)
+
         db.commit()
         
         # Audit log
@@ -286,8 +288,8 @@ class InvoiceGenerationService:
         db.commit()
         
         logger.info(f"Generated invoice {invoice.invoice_number} for {len(tickets)} tickets by user {current_user.email}")
-        
-        return invoice, viewing_link, csv_link
+
+        return invoice, viewing_link, csv_link, notification_ids
 
     
     @staticmethod

src/app/services/notification_creator.py

@@ -0,0 +1,325 @@
+"""
+Notification Creator - Tier 1: Synchronous Notification Creation
+
+This is the ONLY way to create notifications in the system.
+All services must use this to ensure consistency and reliability.
+
+Architecture:
+- Tier 1 (This file): Create notification records synchronously in database
+- Tier 2 (notification_delivery.py): Deliver notifications via external channels (WhatsApp, Email, SMS)
+
+Design Principles:
+1. Synchronous - Notifications are created immediately, guaranteed to be saved
+2. Transaction-safe - Notifications roll back with parent operation
+3. Simple - No async complexity, easy to test and debug
+4. Consistent - One pattern used everywhere in the codebase
+5. Scalable - Designed to handle 10,000+ notifications/day
+
+Usage:
+    from app.services.notification_creator import NotificationCreator
+    
+    # Single notification
+    notification = NotificationCreator.create(
+        db=db,
+        user_id=user.id,
+        title="Ticket Assigned",
+        message="You have been assigned to ticket #123",
+        source_type="ticket",
+        source_id=ticket.id,
+        notification_type="assignment",
+        channel="in_app"
+    )
+    db.commit()
+    
+    # Bulk notifications
+    notifications = NotificationCreator.create_bulk(
+        db=db,
+        user_ids=[user1.id, user2.id, user3.id],
+        title="Project Update",
+        message="Project status changed",
+        source_type="project",
+        source_id=project.id,
+        notification_type="status_change"
+    )
+    db.commit()
+"""
+
+import logging
+from sqlalchemy.orm import Session
+from uuid import UUID
+from typing import Optional, List, Dict, Any
+from datetime import datetime
+
+from app.models.notification import Notification, NotificationChannel, NotificationStatus
+from app.models.user import User
+from app.models.enums import AppRole
+
+logger = logging.getLogger(__name__)
+
+
+class NotificationCreator:
+    """
+    Synchronous notification creator.
+    Creates notification records in database - does NOT send them.
+    Delivery is handled separately by NotificationDelivery service.
+    """
+    
+    @staticmethod
+    def create(
+        db: Session,
+        user_id: UUID,
+        title: str,
+        message: str,
+        source_type: str,
+        source_id: Optional[UUID],
+        notification_type: str,
+        channel: str = "in_app",
+        metadata: Optional[Dict[str, Any]] = None,
+        project_id: Optional[UUID] = None
+    ) -> Notification:
+        """
+        Create a single notification record.
+        
+        Args:
+            db: Database session
+            user_id: User to notify
+            title: Notification title (short, for display)
+            message: Notification message (detailed)
+            source_type: Type of entity (ticket, project, expense, payroll, etc.)
+            source_id: ID of the source entity
+            notification_type: Type of notification (assignment, payment, alert, etc.)
+            channel: Delivery channel (in_app, whatsapp, email, sms, push)
+            metadata: Additional data (action URLs, context, etc.)
+            project_id: Optional project ID for filtering
+        
+        Returns:
+            Notification: Created notification record
+        
+        Example:
+            notification = NotificationCreator.create(
+                db=db,
+                user_id=agent.id,
+                title="New Ticket Assigned",
+                message="You have been assigned to install fiber at Customer A",
+                source_type="ticket",
+                source_id=ticket.id,
+                notification_type="assignment",
+                channel="whatsapp",
+                metadata={
+                    "ticket_number": "TKT-001",
+                    "priority": "high",
+                    "action_url": f"/tickets/{ticket.id}"
+                },
+                project_id=ticket.project_id
+            )
+            db.commit()
+        """
+        try:
+            notification = Notification(
+                user_id=user_id,
+                project_id=project_id,
+                source_type=source_type,
+                source_id=source_id,
+                title=title,
+                message=message,
+                notification_type=notification_type,
+                channel=NotificationChannel(channel),
+                status=NotificationStatus.PENDING,
+                additional_metadata=metadata or {},
+                created_at=datetime.utcnow()
+            )
+            
+            db.add(notification)
+            db.flush()  # Get ID without committing (caller controls commit)
+            
+            logger.debug(
+                f"Created notification {notification.id}: {notification_type} for user {user_id} "
+                f"via {channel}"
+            )
+            
+            return notification
+            
+        except Exception as e:
+            logger.error(f"Failed to create notification: {str(e)}", exc_info=True)
+            raise
+
+    @staticmethod
+    def create_bulk(
+        db: Session,
+        user_ids: List[UUID],
+        title: str,
+        message: str,
+        source_type: str,
+        source_id: Optional[UUID],
+        notification_type: str,
+        channel: str = "in_app",
+        metadata: Optional[Dict[str, Any]] = None,
+        project_id: Optional[UUID] = None
+    ) -> List[Notification]:
+        """
+        Create multiple notifications for different users with the same content.
+
+        Args:
+            db: Database session
+            user_ids: List of user IDs to notify
+            title: Notification title (same for all)
+            message: Notification message (same for all)
+            source_type: Type of entity
+            source_id: ID of the source entity
+            notification_type: Type of notification
+            channel: Delivery channel
+            metadata: Additional data (same for all)
+            project_id: Optional project ID
+
+        Returns:
+            List[Notification]: List of created notification records
+
+        Example:
+            # Notify all managers about ticket drop
+            manager_ids = [pm1.id, pm2.id, dispatcher.id]
+            notifications = NotificationCreator.create_bulk(
+                db=db,
+                user_ids=manager_ids,
+                title="⚠️ Ticket Dropped - Action Required",
+                message=f"{agent.name} dropped ticket: {ticket.name}",
+                source_type="ticket",
+                source_id=ticket.id,
+                notification_type="ticket_dropped",
+                channel="in_app",
+                project_id=ticket.project_id
+            )
+            db.commit()
+        """
+        notifications = []
+
+        try:
+            for user_id in user_ids:
+                notification = NotificationCreator.create(
+                    db=db,
+                    user_id=user_id,
+                    title=title,
+                    message=message,
+                    source_type=source_type,
+                    source_id=source_id,
+                    notification_type=notification_type,
+                    channel=channel,
+                    metadata=metadata,
+                    project_id=project_id
+                )
+                notifications.append(notification)
+
+            logger.info(
+                f"Created {len(notifications)} bulk notifications: {notification_type} "
+                f"via {channel}"
+            )
+
+            return notifications
+
+        except Exception as e:
+            logger.error(f"Failed to create bulk notifications: {str(e)}", exc_info=True)
+            raise
+
+    @staticmethod
+    def notify_project_team(
+        db: Session,
+        project_id: UUID,
+        title: str,
+        message: str,
+        source_type: str,
+        source_id: Optional[UUID],
+        notification_type: str,
+        roles: Optional[List[AppRole]] = None,
+        channel: str = "in_app",
+        metadata: Optional[Dict[str, Any]] = None,
+        exclude_user_ids: Optional[List[UUID]] = None
+    ) -> List[Notification]:
+        """
+        Notify all team members in a project (optionally filtered by role).
+
+        Args:
+            db: Database session
+            project_id: Project ID
+            title: Notification title
+            message: Notification message
+            source_type: Type of entity
+            source_id: ID of the source entity
+            notification_type: Type of notification
+            roles: Optional list of roles to notify (e.g., [AppRole.PROJECT_MANAGER, AppRole.DISPATCHER])
+            channel: Delivery channel
+            metadata: Additional data
+            exclude_user_ids: Optional list of user IDs to exclude
+
+        Returns:
+            List[Notification]: List of created notification records
+
+        Example:
+            # Notify all managers and dispatchers in project
+            notifications = NotificationCreator.notify_project_team(
+                db=db,
+                project_id=ticket.project_id,
+                title="Ticket Dropped",
+                message=f"{agent.name} dropped ticket",
+                source_type="ticket",
+                source_id=ticket.id,
+                notification_type="ticket_dropped",
+                roles=[AppRole.PROJECT_MANAGER, AppRole.DISPATCHER],
+                exclude_user_ids=[agent.id]  # Don't notify the agent who dropped
+            )
+            db.commit()
+        """
+        from app.models.project_team import ProjectTeam
+
+        try:
+            # Build query for project team members
+            query = db.query(User).join(ProjectTeam).filter(
+                ProjectTeam.project_id == project_id,
+                User.is_active == True,
+                User.deleted_at.is_(None)
+            )
+
+            # Filter by roles if specified
+            if roles:
+                role_values = [role.value for role in roles]
+                query = query.filter(User.role.in_(role_values))
+
+            # Exclude specific users if specified
+            if exclude_user_ids:
+                query = query.filter(~User.id.in_(exclude_user_ids))
+
+            team_members = query.all()
+
+            if not team_members:
+                logger.warning(
+                    f"No team members found for project {project_id} "
+                    f"with roles {roles}"
+                )
+                return []
+
+            user_ids = [member.id for member in team_members]
+
+            notifications = NotificationCreator.create_bulk(
+                db=db,
+                user_ids=user_ids,
+                title=title,
+                message=message,
+                source_type=source_type,
+                source_id=source_id,
+                notification_type=notification_type,
+                channel=channel,
+                metadata=metadata,
+                project_id=project_id
+            )
+
+            logger.info(
+                f"Notified {len(notifications)} team members in project {project_id}"
+            )
+
+            return notifications
+
+        except Exception as e:
+            logger.error(
+                f"Failed to notify project team {project_id}: {str(e)}",
+                exc_info=True
+            )
+            raise
+

src/app/services/notification_delivery.py

@@ -0,0 +1,333 @@
+"""
+Notification Delivery - Tier 2: Background Notification Delivery
+
+Handles delivery of notifications via external channels (WhatsApp, Email, SMS, Push).
+Works with FastAPI BackgroundTasks for non-blocking delivery.
+
+Architecture:
+- Tier 1 (notification_creator.py): Creates notification records synchronously
+- Tier 2 (This file): Delivers notifications via external channels asynchronously
+
+Design Principles:
+1. Non-blocking - Doesn't slow down API responses
+2. Resilient - Handles failures gracefully, marks status
+3. Configurable - Easy to enable/disable channels for MVP
+4. Future-proof - Easy to migrate to Celery when needed
+
+Usage:
+    from fastapi import BackgroundTasks
+    from app.services.notification_delivery import NotificationDelivery
+    
+    # In endpoint
+    @router.post("/tickets/assign")
+    def assign_ticket(background_tasks: BackgroundTasks, ...):
+        # Create notification (Tier 1 - sync)
+        notification = NotificationCreator.create(
+            db=db,
+            user_id=agent.id,
+            title="Ticket Assigned",
+            message="You have been assigned...",
+            channel="whatsapp"
+        )
+        db.commit()
+        
+        # Queue delivery (Tier 2 - async)
+        NotificationDelivery.queue_delivery(
+            background_tasks=background_tasks,
+            notification_id=notification.id
+        )
+        
+        return response
+
+Configuration:
+    Set in .env:
+    ENABLE_WHATSAPP_NOTIFICATIONS=false  # Disable for MVP
+    ENABLE_EMAIL_NOTIFICATIONS=false     # Disable for MVP
+    ENABLE_SMS_NOTIFICATIONS=false       # Disable for MVP
+"""
+
+import logging
+from uuid import UUID
+from typing import Optional
+from fastapi import BackgroundTasks
+
+from app.core.database import SessionLocal
+from app.models.notification import Notification, NotificationChannel, NotificationStatus
+
+logger = logging.getLogger(__name__)
+
+
+class NotificationDeliveryConfig:
+    """
+    Configuration for notification delivery.
+    Allows enabling/disabling channels without code changes.
+    """
+    
+    # For MVP, all external channels are disabled
+    # Set to True in .env when ready to integrate
+    ENABLE_WHATSAPP = False
+    ENABLE_EMAIL = False
+    ENABLE_SMS = False
+    ENABLE_PUSH = False
+    
+    # In-app notifications are always enabled (no external API)
+    ENABLE_IN_APP = True
+    
+    @classmethod
+    def is_channel_enabled(cls, channel: NotificationChannel) -> bool:
+        """Check if a delivery channel is enabled"""
+        channel_map = {
+            NotificationChannel.IN_APP: cls.ENABLE_IN_APP,
+            NotificationChannel.WHATSAPP: cls.ENABLE_WHATSAPP,
+            NotificationChannel.EMAIL: cls.ENABLE_EMAIL,
+            NotificationChannel.SMS: cls.ENABLE_SMS,
+            NotificationChannel.PUSH: cls.ENABLE_PUSH,
+        }
+        return channel_map.get(channel, False)
+
+
+class NotificationDelivery:
+    """
+    Handles delivery of notifications via external channels.
+    Designed to work with FastAPI BackgroundTasks (MVP) and Celery (future).
+    """
+    
+    @staticmethod
+    def queue_delivery(
+        background_tasks: BackgroundTasks,
+        notification_id: UUID
+    ) -> None:
+        """
+        Queue a notification for background delivery.
+        
+        Args:
+            background_tasks: FastAPI BackgroundTasks instance
+            notification_id: ID of notification to deliver
+        
+        Example:
+            NotificationDelivery.queue_delivery(
+                background_tasks=background_tasks,
+                notification_id=notification.id
+            )
+        """
+        background_tasks.add_task(
+            NotificationDelivery._deliver_notification,
+            notification_id=notification_id
+        )
+        logger.debug(f"Queued notification {notification_id} for delivery")
+    
+    @staticmethod
+    def queue_bulk_delivery(
+        background_tasks: BackgroundTasks,
+        notification_ids: list[UUID]
+    ) -> None:
+        """
+        Queue multiple notifications for background delivery.
+        
+        Args:
+            background_tasks: FastAPI BackgroundTasks instance
+            notification_ids: List of notification IDs to deliver
+        
+        Example:
+            NotificationDelivery.queue_bulk_delivery(
+                background_tasks=background_tasks,
+                notification_ids=[notif.id for notif in notifications]
+            )
+        """
+        for notification_id in notification_ids:
+            NotificationDelivery.queue_delivery(
+                background_tasks=background_tasks,
+                notification_id=notification_id
+            )
+        logger.debug(f"Queued {len(notification_ids)} notifications for delivery")
+    
+    @staticmethod
+    def _deliver_notification(notification_id: UUID) -> None:
+        """
+        Internal method to deliver a notification.
+        Runs in background task.
+        
+        Args:
+            notification_id: ID of notification to deliver
+        """
+        db = SessionLocal()
+        
+        try:
+            # Get notification
+            notification = db.query(Notification).filter(
+                Notification.id == notification_id
+            ).first()
+            
+            if not notification:
+                logger.error(f"Notification {notification_id} not found")
+                return
+
+            # Check if channel is enabled
+            if not NotificationDeliveryConfig.is_channel_enabled(notification.channel):
+                logger.info(
+                    f"Channel {notification.channel.value} is disabled. "
+                    f"Marking notification {notification_id} as skipped."
+                )
+                notification.status = NotificationStatus.SENT  # Mark as sent to avoid retry
+                notification.additional_metadata = notification.additional_metadata or {}
+                notification.additional_metadata["delivery_skipped"] = True
+                notification.additional_metadata["skip_reason"] = "Channel disabled for MVP"
+                db.commit()
+                return
+
+            # In-app notifications don't need external delivery
+            if notification.channel == NotificationChannel.IN_APP:
+                notification.status = NotificationStatus.SENT
+                db.commit()
+                logger.debug(f"In-app notification {notification_id} marked as sent")
+                return
+
+            # Deliver via external channel
+            if notification.channel == NotificationChannel.WHATSAPP:
+                NotificationDelivery._deliver_whatsapp(db, notification)
+            elif notification.channel == NotificationChannel.EMAIL:
+                NotificationDelivery._deliver_email(db, notification)
+            elif notification.channel == NotificationChannel.SMS:
+                NotificationDelivery._deliver_sms(db, notification)
+            elif notification.channel == NotificationChannel.PUSH:
+                NotificationDelivery._deliver_push(db, notification)
+            else:
+                logger.warning(f"Unknown channel: {notification.channel}")
+                notification.status = NotificationStatus.FAILED
+                notification.error_message = f"Unknown channel: {notification.channel}"
+                db.commit()
+
+        except Exception as e:
+            logger.error(
+                f"Failed to deliver notification {notification_id}: {str(e)}",
+                exc_info=True
+            )
+            # Don't raise - background task should not fail
+
+        finally:
+            db.close()
+
+    @staticmethod
+    def _deliver_whatsapp(db, notification: Notification) -> None:
+        """
+        Deliver notification via WhatsApp.
+
+        For MVP: This is a placeholder. When ready to integrate:
+        1. Set ENABLE_WHATSAPP = True in config
+        2. Implement actual WhatsApp API call (Twilio, Africa's Talking, etc.)
+        3. Handle API errors and retries
+        """
+        try:
+            # TODO: Implement WhatsApp delivery
+            # Example:
+            # from app.services.whatsapp_service import WhatsAppService
+            # WhatsAppService.send_message(
+            #     phone_number=notification.user.phone_number,
+            #     message=notification.message
+            # )
+
+            # For now, just log
+            logger.info(
+                f"WhatsApp delivery placeholder for notification {notification.id}. "
+                f"Implement WhatsAppService when ready."
+            )
+
+            notification.status = NotificationStatus.SENT
+            notification.sent_at = notification.sent_at or notification.created_at
+            db.commit()
+
+        except Exception as e:
+            logger.error(f"WhatsApp delivery failed: {str(e)}", exc_info=True)
+            notification.status = NotificationStatus.FAILED
+            notification.error_message = str(e)
+            db.commit()
+
+    @staticmethod
+    def _deliver_email(db, notification: Notification) -> None:
+        """
+        Deliver notification via Email.
+
+        For MVP: This is a placeholder. When ready to integrate:
+        1. Set ENABLE_EMAIL = True in config
+        2. Implement actual Email sending (SendGrid, AWS SES, etc.)
+        3. Handle API errors and retries
+        """
+        try:
+            # TODO: Implement Email delivery
+            # Example:
+            # from app.services.email_service import EmailService
+            # EmailService.send_email(
+            #     to_email=notification.user.email,
+            #     subject=notification.title,
+            #     body=notification.message
+            # )
+
+            logger.info(
+                f"Email delivery placeholder for notification {notification.id}. "
+                f"Implement EmailService when ready."
+            )
+
+            notification.status = NotificationStatus.SENT
+            notification.sent_at = notification.sent_at or notification.created_at
+            db.commit()
+
+        except Exception as e:
+            logger.error(f"Email delivery failed: {str(e)}", exc_info=True)
+            notification.status = NotificationStatus.FAILED
+            notification.error_message = str(e)
+            db.commit()
+
+    @staticmethod
+    def _deliver_sms(db, notification: Notification) -> None:
+        """
+        Deliver notification via SMS.
+
+        For MVP: This is a placeholder. When ready to integrate:
+        1. Set ENABLE_SMS = True in config
+        2. Implement actual SMS sending (Twilio, Africa's Talking, etc.)
+        3. Handle API errors and retries
+        """
+        try:
+            # TODO: Implement SMS delivery
+            logger.info(
+                f"SMS delivery placeholder for notification {notification.id}. "
+                f"Implement SMSService when ready."
+            )
+
+            notification.status = NotificationStatus.SENT
+            notification.sent_at = notification.sent_at or notification.created_at
+            db.commit()
+
+        except Exception as e:
+            logger.error(f"SMS delivery failed: {str(e)}", exc_info=True)
+            notification.status = NotificationStatus.FAILED
+            notification.error_message = str(e)
+            db.commit()
+
+    @staticmethod
+    def _deliver_push(db, notification: Notification) -> None:
+        """
+        Deliver notification via Push Notification.
+
+        For MVP: This is a placeholder. When ready to integrate:
+        1. Set ENABLE_PUSH = True in config
+        2. Implement actual Push notification (Firebase, OneSignal, etc.)
+        3. Handle API errors and retries
+        """
+        try:
+            # TODO: Implement Push notification delivery
+            logger.info(
+                f"Push notification delivery placeholder for notification {notification.id}. "
+                f"Implement PushService when ready."
+            )
+
+            notification.status = NotificationStatus.SENT
+            notification.sent_at = notification.sent_at or notification.created_at
+            db.commit()
+
+        except Exception as e:
+            logger.error(f"Push notification delivery failed: {str(e)}", exc_info=True)
+            notification.status = NotificationStatus.FAILED
+            notification.error_message = str(e)
+            db.commit()
+

src/app/services/notification_helper.py

@@ -1133,3 +1133,235 @@ class NotificationHelper:
         )
         
         logger.info(f"Created notifications for {len(user_ids)} users with roles {roles} in project {project_id}")
+
+    # ============================================
+    # PAYROLL NOTIFICATIONS
+    # ============================================
+
+    @staticmethod
+    async def notify_payroll_exported(
+        db: Session,
+        exported_by: User,
+        payroll_records: List,
+        total_amount: float,
+        total_days_worked: int,
+        total_tickets_closed: int,
+        period_start: str,
+        period_end: str,
+        project_id: Optional[UUID] = None,
+        warnings: Optional[List[str]] = None
+    ):
+        """
+        Notify manager/admin who exported payroll with summary.
+
+        Args:
+            db: Database session
+            exported_by: User who initiated the export
+            payroll_records: List of UserPayroll objects that were exported
+            total_amount: Total payroll amount exported
+            total_days_worked: Total days worked across all payroll
+            total_tickets_closed: Total tickets closed across all payroll
+            period_start: Period start date (ISO format)
+            period_end: Period end date (ISO format)
+            project_id: Optional project ID
+            warnings: Optional list of warnings from export
+        """
+        service = NotificationService()
+
+        # Build summary message
+        payroll_count = len(payroll_records)
+        payroll_ids = [str(p.id) for p in payroll_records]
+
+        title = f"Payroll Export Complete: {payroll_count} records"
+
+        message = (
+            f"Successfully exported payroll for period {period_start} to {period_end}.\n\n"
+            f"📊 Summary:\n"
+            f"• {payroll_count} workers paid\n"
+            f"• {total_days_worked} total days worked\n"
+            f"• {total_tickets_closed} total tickets closed\n"
+            f"• {total_amount:,.2f} KES total payout"
+        )
+
+        if warnings:
+            message += f"\n\n⚠️ {len(warnings)} warnings - review CSV before uploading to Tende Pay"
+
+        metadata = {
+            'project_id': str(project_id) if project_id else None,
+            'payroll_ids': payroll_ids,
+            'payroll_count': payroll_count,
+            'total_amount': total_amount,
+            'total_days_worked': total_days_worked,
+            'total_tickets_closed': total_tickets_closed,
+            'period_start': period_start,
+            'period_end': period_end,
+            'warning_count': len(warnings) if warnings else 0,
+            'action_url': f'/projects/{project_id}/payroll' if project_id else '/payroll',
+            'export_timestamp': datetime.utcnow().isoformat()
+        }
+
+        await service.create_notification(
+            db=db,
+            user_id=exported_by.id,
+            title=title,
+            message=message,
+            source_type='payroll',
+            source_id=None,  # Bulk operation, no single source
+            notification_type='payroll_exported',
+            channel='in_app',
+            project_id=project_id,
+            additional_metadata=metadata
+        )
+
+        logger.info(f"Created payroll export notification for user {exported_by.id}")
+
+    @staticmethod
+    async def notify_payroll_payment(
+        db: Session,
+        payroll,
+        user: User,
+        project_id: Optional[UUID] = None
+    ):
+        """
+        Notify worker that their payroll has been exported for payment.
+
+        Args:
+            db: Database session
+            payroll: UserPayroll object
+            user: User receiving payment
+            project_id: Optional project ID
+        """
+        service = NotificationService()
+
+        # Build payment details message
+        title = f"💰 Payment Processed: {payroll.total_amount:,.2f} KES"
+
+        # Build breakdown
+        breakdown_parts = []
+        if payroll.days_worked:
+            breakdown_parts.append(f"{payroll.days_worked} days worked")
+        if payroll.tickets_closed:
+            breakdown_parts.append(f"{payroll.tickets_closed} tickets closed")
+
+        breakdown = ", ".join(breakdown_parts) if breakdown_parts else "work completed"
+
+        message = (
+            f"Your payment for {payroll.period_start_date.strftime('%b %d')} to "
+            f"{payroll.period_end_date.strftime('%b %d, %Y')} has been processed.\n\n"
+            f"📋 Work Summary:\n"
+            f"• {breakdown}\n"
+            f"• Base earnings: {payroll.base_earnings:,.2f} KES\n"
+        )
+
+        if payroll.bonus_amount and payroll.bonus_amount > 0:
+            message += f"• Bonus: {payroll.bonus_amount:,.2f} KES\n"
+
+        if payroll.deductions and payroll.deductions > 0:
+            message += f"• Deductions: -{payroll.deductions:,.2f} KES\n"
+
+        message += f"\n💵 Total Payment: {payroll.total_amount:,.2f} KES"
+        message += f"\n\nPayment will be sent to your registered account shortly."
+
+        metadata = {
+            'project_id': str(project_id) if project_id else None,
+            'payroll_id': str(payroll.id),
+            'period_start': payroll.period_start_date.isoformat(),
+            'period_end': payroll.period_end_date.isoformat(),
+            'days_worked': payroll.days_worked,
+            'tickets_closed': payroll.tickets_closed,
+            'base_earnings': float(payroll.base_earnings),
+            'bonus_amount': float(payroll.bonus_amount) if payroll.bonus_amount else 0,
+            'deductions': float(payroll.deductions) if payroll.deductions else 0,
+            'total_amount': float(payroll.total_amount),
+            'action_url': f'/payroll/{payroll.id}',
+            'payment_method': payroll.payment_method
+        }
+
+        # Send via WhatsApp for important payment notifications
+        await service.create_notification(
+            db=db,
+            user_id=user.id,
+            title=title,
+            message=message,
+            source_type='payroll',
+            source_id=payroll.id,
+            notification_type='payment',
+            channel='whatsapp',  # Use WhatsApp for payment notifications
+            project_id=project_id,
+            additional_metadata=metadata,
+            send_now=True  # Send immediately
+        )
+
+        logger.info(f"Created payment notification for user {user.id}, payroll {payroll.id}")
+
+    # ============================================
+    # TICKET DROP NOTIFICATIONS
+    # ============================================
+
+    @staticmethod
+    async def notify_ticket_dropped(
+        db: Session,
+        ticket,
+        assignment,
+        dropped_by: User,
+        drop_type: str,
+        reason: str
+    ):
+        """
+        Notify managers when agent drops a ticket (goes to PENDING_REVIEW).
+        Critical notification - ticket needs immediate manager attention.
+
+        Args:
+            db: Database session
+            ticket: Ticket that was dropped
+            assignment: TicketAssignment that was dropped
+            dropped_by: User who dropped the ticket
+            drop_type: Type of drop (reschedule, equipment_issue, customer_issue, etc.)
+            reason: Reason for dropping
+        """
+        service = NotificationService()
+
+        # Build notification message
+        title = f"⚠️ Ticket Dropped - Action Required"
+
+        # Format drop type for display
+        drop_type_display = drop_type.replace('_', ' ').title()
+
+        message = (
+            f"{dropped_by.name} dropped ticket: {ticket.ticket_name or ticket.ticket_type}\n\n"
+            f"🔴 Reason: {drop_type_display}\n"
+            f"💬 Details: {reason}\n\n"
+            f"⚡ This ticket is now in PENDING REVIEW and needs your immediate attention."
+        )
+
+        metadata = {
+            'project_id': str(ticket.project_id),
+            'ticket_id': str(ticket.id),
+            'assignment_id': str(assignment.id),
+            'dropped_by_user_id': str(dropped_by.id),
+            'dropped_by_name': dropped_by.name,
+            'drop_type': drop_type,
+            'reason': reason,
+            'ticket_name': ticket.ticket_name,
+            'ticket_type': ticket.ticket_type,
+            'ticket_status': ticket.status,
+            'action_url': f'/projects/{ticket.project_id}/tickets/{ticket.id}',
+            'requires_action': True,
+            'priority': 'high'
+        }
+
+        # Notify all managers and dispatchers in the project
+        await NotificationHelper.notify_users_by_role(
+            db=db,
+            project_id=ticket.project_id,
+            roles=[AppRole.PROJECT_MANAGER, AppRole.DISPATCHER],
+            title=title,
+            message=message,
+            source_type='ticket',
+            source_id=ticket.id,
+            notification_type='ticket_dropped',
+            channel='in_app',  # Could also use WhatsApp for urgent drops
+            additional_metadata=metadata
+        )
+
+        logger.info(f"Created ticket drop notification for ticket {ticket.id}, dropped by {dropped_by.id}")

src/app/services/payroll_service.py

@@ -172,9 +172,9 @@ class PayrollService:
     ) -> Dict[str, Any]:
         """
         Get compensation rates from project_team and project_role
-        
+
         Returns:
-            Dict with flat_rate, commission_percentage, base_amount, hourly_rate
+            Dict with compensation_type, base_rate, rate_period, per_unit_rate, commission_percentage
         """
         try:
             # Get project team member with role
@@ -185,34 +185,38 @@ class PayrollService:
                 ProjectTeam.project_id == project_id,
                 ProjectTeam.deleted_at.is_(None)
             ).first()
-            
+
             if not team_member:
                 logger.warning(f"No project team record found for user {user_id} in project {project_id}")
                 return {
-                    "flat_rate": Decimal('0'),
+                    "compensation_type": None,
+                    "base_rate": Decimal('0'),
+                    "rate_period": None,
+                    "per_unit_rate": Decimal('0'),
                     "commission_percentage": Decimal('0'),
-                    "base_amount": Decimal('0'),
-                    "hourly_rate": Decimal('0'),
-                    "project_team_id": None
+                    "project_team_id": None,
+                    "role_name": None
                 }
-            
+
             role = team_member.project_role
             if not role:
                 logger.warning(f"No role assigned for user {user_id} in project {project_id}")
                 return {
-                    "flat_rate": Decimal('0'),
+                    "compensation_type": None,
+                    "base_rate": Decimal('0'),
+                    "rate_period": None,
+                    "per_unit_rate": Decimal('0'),
                     "commission_percentage": Decimal('0'),
-                    "base_amount": Decimal('0'),
-                    "hourly_rate": Decimal('0'),
-                    "project_team_id": team_member.id
+                    "project_team_id": team_member.id,
+                    "role_name": None
                 }
-            
+
             return {
-                "flat_rate": Decimal(str(role.flat_rate_amount or 0)),
+                "compensation_type": role.compensation_type,
+                "base_rate": Decimal(str(role.base_rate or 0)),
+                "rate_period": role.rate_period,
+                "per_unit_rate": Decimal(str(role.per_unit_rate or 0)),
                 "commission_percentage": Decimal(str(role.commission_percentage or 0)),
-                "base_amount": Decimal(str(role.base_amount or 0)),
-                "hourly_rate": Decimal(str(role.hourly_rate or 0)),
-                "bonus_percentage": Decimal(str(role.bonus_percentage or 0)),
                 "project_team_id": team_member.id,
                 "role_name": role.role_name
             }
@@ -224,22 +228,82 @@ class PayrollService:
             )
     
     @staticmethod
-    def calculate_ticket_earnings(
+    def calculate_base_earnings(
+        compensation_type: str,
+        days_worked: int,
         tickets_closed: int,
-        base_amount: Decimal,
-        commission_percentage: Decimal
-    ) -> Decimal:
+        base_rate: Decimal,
+        rate_period: Optional[str],
+        per_unit_rate: Decimal,
+        commission_percentage: Decimal,
+        ticket_value_total: Decimal = Decimal('0')
+    ) -> tuple[Decimal, str]:
         """
-        Calculate earnings from tickets closed
-        
-        Formula: (base_amount * tickets_closed) + (base_amount * tickets_closed * commission_percentage / 100)
+        Calculate base earnings based on compensation type
+
+        Returns:
+            Tuple of (base_earnings, calculation_notes)
         """
-        if tickets_closed == 0:
-            return Decimal('0')
-        
-        base_earnings = base_amount * Decimal(tickets_closed)
-        commission = base_earnings * (commission_percentage / Decimal('100'))
-        return base_earnings + commission
+        if not compensation_type:
+            return Decimal('0'), "No compensation type defined"
+
+        if compensation_type == "FIXED_RATE":
+            # Time-based pay
+            if rate_period == "DAY":
+                earnings = base_rate * Decimal(days_worked)
+                notes = f"FIXED_RATE: {days_worked} days × {base_rate} KES/day = {earnings} KES"
+            elif rate_period == "WEEK":
+                # Weekly rate is flat regardless of days worked
+                earnings = base_rate
+                notes = f"FIXED_RATE: {base_rate} KES/week (flat)"
+            elif rate_period == "MONTH":
+                # Monthly rate is flat
+                earnings = base_rate
+                notes = f"FIXED_RATE: {base_rate} KES/month (flat)"
+            elif rate_period == "HOUR":
+                # Would need hours_worked from timesheets
+                # For now, assume 8 hours per day
+                hours = days_worked * 8
+                earnings = base_rate * Decimal(hours)
+                notes = f"FIXED_RATE: {hours} hours × {base_rate} KES/hour = {earnings} KES"
+            else:
+                earnings = Decimal('0')
+                notes = f"FIXED_RATE: Unknown rate_period '{rate_period}'"
+            return earnings, notes
+
+        elif compensation_type == "PER_UNIT":
+            # Work-based pay
+            earnings = per_unit_rate * Decimal(tickets_closed)
+            notes = f"PER_UNIT: {tickets_closed} tickets × {per_unit_rate} KES/ticket = {earnings} KES"
+            return earnings, notes
+
+        elif compensation_type == "COMMISSION":
+            # Percentage-based pay
+            earnings = ticket_value_total * (commission_percentage / Decimal('100'))
+            notes = f"COMMISSION: {ticket_value_total} KES × {commission_percentage}% = {earnings} KES"
+            return earnings, notes
+
+        elif compensation_type == "FIXED_PLUS_COMMISSION":
+            # Hybrid: base + commission
+            if rate_period == "DAY":
+                base_earnings = base_rate * Decimal(days_worked)
+            elif rate_period == "WEEK":
+                base_earnings = base_rate
+            elif rate_period == "MONTH":
+                base_earnings = base_rate
+            elif rate_period == "HOUR":
+                hours = days_worked * 8
+                base_earnings = base_rate * Decimal(hours)
+            else:
+                base_earnings = Decimal('0')
+
+            commission_earnings = ticket_value_total * (commission_percentage / Decimal('100'))
+            earnings = base_earnings + commission_earnings
+            notes = f"FIXED_PLUS_COMMISSION: Base {base_earnings} KES + Commission {commission_earnings} KES = {earnings} KES"
+            return earnings, notes
+
+        else:
+            return Decimal('0'), f"Unknown compensation type: {compensation_type}"
     
     # ============================================
     # PAYROLL GENERATION
@@ -314,15 +378,19 @@ class PayrollService:
             )
             
             compensation = PayrollService.get_compensation_rates(db, user_id, project_id)
-            
-            # Calculate earnings
-            flat_rate = compensation["flat_rate"]
-            ticket_earnings = PayrollService.calculate_ticket_earnings(
-                aggregated_data["tickets_closed"],
-                compensation["base_amount"],
-                compensation["commission_percentage"]
+
+            # Calculate base earnings
+            base_earnings, calc_notes = PayrollService.calculate_base_earnings(
+                compensation_type=compensation["compensation_type"],
+                days_worked=aggregated_data["days_worked"],
+                tickets_closed=aggregated_data["tickets_closed"],
+                base_rate=compensation["base_rate"],
+                rate_period=compensation["rate_period"],
+                per_unit_rate=compensation["per_unit_rate"],
+                commission_percentage=compensation["commission_percentage"],
+                ticket_value_total=Decimal('0')  # TODO: Add ticket value tracking if needed
             )
-            
+
             # Create payroll record
             payroll = UserPayroll(
                 user_id=user_id,
@@ -331,15 +399,14 @@ class PayrollService:
                 period_start_date=period_start_date,
                 period_end_date=period_end_date,
                 tickets_closed=aggregated_data["tickets_closed"],
-                hours_worked=aggregated_data["hours_worked"],
                 days_worked=aggregated_data["days_worked"],
-                flat_rate_amount=flat_rate,
-                ticket_earnings=ticket_earnings,
+                base_earnings=base_earnings,
                 bonus_amount=Decimal('0'),  # Can be added manually later
                 deductions=Decimal('0'),    # Can be added manually later
                 total_amount=Decimal('0'),  # Will be calculated
                 calculation_notes=f"Auto-generated for week {period_start_date} to {period_end_date}. "
                                  f"Role: {compensation.get('role_name', 'N/A')}. "
+                                 f"{calc_notes}. "
                                  f"Tickets: {aggregated_data['tickets_completed']} completed, "
                                  f"{aggregated_data['tickets_assigned']} assigned, "
                                  f"{aggregated_data['tickets_rejected']} rejected. "
@@ -537,25 +604,28 @@ class PayrollService:
         compensation = PayrollService.get_compensation_rates(
             db, payroll.user_id, payroll.project_id
         )
-        
-        # Calculate new earnings
-        flat_rate = compensation["flat_rate"]
-        ticket_earnings = PayrollService.calculate_ticket_earnings(
-            aggregated_data["tickets_closed"],
-            compensation["base_amount"],
-            compensation["commission_percentage"]
+
+        # Calculate new base earnings
+        base_earnings, calc_notes = PayrollService.calculate_base_earnings(
+            compensation_type=compensation["compensation_type"],
+            days_worked=aggregated_data["days_worked"],
+            tickets_closed=aggregated_data["tickets_closed"],
+            base_rate=compensation["base_rate"],
+            rate_period=compensation["rate_period"],
+            per_unit_rate=compensation["per_unit_rate"],
+            commission_percentage=compensation["commission_percentage"],
+            ticket_value_total=Decimal('0')  # TODO: Add ticket value tracking if needed
         )
-        
+
         # Recalculate (preserves manually added bonuses/deductions)
         payroll.recalculate_from_data(
             tickets_closed=aggregated_data["tickets_closed"],
-            hours_worked=aggregated_data["hours_worked"],
             days_worked=aggregated_data["days_worked"],
-            flat_rate=flat_rate,
-            ticket_earnings=ticket_earnings,
+            base_earnings=base_earnings,
             bonus=Decimal(str(payroll.bonus_amount or 0)),  # Keep existing bonus
             deductions=Decimal(str(payroll.deductions or 0)),  # Keep existing deductions
             calculation_notes=f"Recalculated at {datetime.utcnow().isoformat()} due to timesheet correction. "
+                            f"{calc_notes}. "
                             f"Tickets: {aggregated_data['tickets_completed']} completed, "
                             f"{aggregated_data['tickets_assigned']} assigned."
         )
@@ -738,10 +808,8 @@ class PayrollService:
             period_end_date=payroll.period_end_date,
             period_label=payroll.period_label,
             tickets_closed=payroll.tickets_closed,
-            hours_worked=payroll.hours_worked,
             days_worked=payroll.days_worked,
-            flat_rate_amount=payroll.flat_rate_amount,
-            ticket_earnings=payroll.ticket_earnings,
+            base_earnings=payroll.base_earnings,
             bonus_amount=payroll.bonus_amount,
             deductions=payroll.deductions,
             total_amount=payroll.total_amount,
@@ -763,3 +831,247 @@ class PayrollService:
             project_name=project.title if project else None,
             paid_by_name=f"{paid_by.first_name} {paid_by.last_name}" if paid_by else None
         )
+
+    # ============================================
+    # PAYROLL EXPORT FOR PAYMENT
+    # ============================================
+
+    @staticmethod
+    def export_for_payment(
+        db: Session,
+        from_date: date,
+        to_date: date,
+        current_user: User,
+        project_id: Optional[UUID] = None,
+        user_id: Optional[UUID] = None
+    ) -> Tuple[List[dict], List[str], List]:
+        """
+        Export unpaid payroll records in Tende Pay CSV format.
+        Marks all exported payroll as paid.
+
+        Args:
+            db: Database session
+            from_date: Start date (inclusive) - period_start_date
+            to_date: End date (inclusive) - period_end_date
+            current_user: User performing export (PM/Admin)
+            project_id: Optional project filter
+            user_id: Optional user filter
+
+        Returns:
+            Tuple of (csv_rows, warnings, exported_payroll_records)
+            - csv_rows: List of dicts with Tende Pay CSV columns
+            - warnings: List of warning messages
+            - exported_payroll_records: List of UserPayroll objects that were exported
+
+        Raises:
+            HTTPException: If user lacks permission
+        """
+        from app.models.user_financial_account import UserFinancialAccount
+        from app.services.tende_pay_formatter import TendePayFormatter
+        from collections import defaultdict
+
+        # Permission check
+        if not PayrollService.can_user_manage_payroll(current_user, project_id):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You don't have permission to export payroll"
+            )
+
+        # Build query for unpaid payroll
+        query = db.query(UserPayroll).filter(
+            UserPayroll.is_paid == False,
+            UserPayroll.deleted_at == None,
+            UserPayroll.period_start_date >= from_date,
+            UserPayroll.period_end_date <= to_date
+        )
+
+        # Apply filters
+        if project_id:
+            query = query.filter(UserPayroll.project_id == project_id)
+        if user_id:
+            query = query.filter(UserPayroll.user_id == user_id)
+
+        # Get payroll records
+        payroll_records = query.order_by(
+            UserPayroll.user_id,
+            UserPayroll.period_start_date
+        ).all()
+
+        if not payroll_records:
+            logger.info(f"No unpaid payroll found for period {from_date} to {to_date}")
+            return [], []
+
+        logger.info(f"Found {len(payroll_records)} unpaid payroll records to export")
+
+        # Build Tende Pay CSV rows
+        csv_rows = []
+        warnings = []
+        exported_payroll_ids = set()  # Track which payroll was successfully exported
+        payment_reference = f"PAYROLL_EXPORT_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}_{current_user.id}"
+
+        for payroll in payroll_records:
+            # Get user
+            user = db.query(User).filter(User.id == payroll.user_id).first()
+            if not user:
+                warnings.append(f"Payroll {payroll.id}: User not found - SKIPPED")
+                continue
+
+            # Get user's primary financial account (most recent version at export time)
+            financial_account = db.query(UserFinancialAccount).filter(
+                UserFinancialAccount.user_id == user.id,
+                UserFinancialAccount.is_primary == True,
+                UserFinancialAccount.is_active == True,
+                UserFinancialAccount.deleted_at == None
+            ).first()
+
+            if not financial_account:
+                # WARNING but still export with empty payment details
+                warnings.append(
+                    f"{user.name}: No active primary financial account - "
+                    f"exported with empty payment details. Please add payment details."
+                )
+                # Create minimal row with warning
+                csv_rows.append({
+                    "NAME": user.name,
+                    "ID NUMBER": user.id_number or "",
+                    "PHONE NUMBER": "",
+                    "AMOUNT": float(payroll.total_amount),
+                    "PAYMENT MODE": "",
+                    "BANK (Optional)": "",
+                    "BANK ACCOUNT NO (Optional)": "",
+                    "PAYBILL BUSINESS NO (Optional)": "",
+                    "PAYBILL ACCOUNT NO (Optional)": "",
+                    "BUY GOODS TILL NO (Optional)": "",
+                    "BILL PAYMENT BILLER CODE (Optional)": "",
+                    "BILL PAYMENT ACCOUNT NO (Optional)": "",
+                    "NARRATION (OPTIONAL)": TendePayFormatter.build_payroll_narration(payroll)
+                })
+                exported_payroll_ids.add(payroll.id)
+                continue
+
+            # Map payout_method to payment_method
+            payment_method = financial_account.payout_method
+
+            # Build payment_details dict from financial account
+            payment_details = {}
+
+            if payment_method == "mobile_money":
+                # Map to send_money for TendePayFormatter
+                payment_method = "send_money"
+                payment_details = {
+                    "phone_number": financial_account.mobile_money_phone,
+                    "recipient_name": financial_account.mobile_money_account_name or user.name
+                }
+            elif payment_method == "bank_transfer":
+                payment_details = {
+                    "bank_name": financial_account.bank_name,
+                    "account_number": financial_account.bank_account_number,
+                    "account_name": financial_account.bank_account_name or user.name,
+                    "branch": financial_account.bank_branch
+                }
+            else:
+                # WARNING but still export with empty payment details
+                warnings.append(
+                    f"{user.name}: Unsupported payout method '{payment_method}' - "
+                    f"exported with empty payment details. Supported: mobile_money, bank_transfer."
+                )
+                csv_rows.append({
+                    "NAME": user.name,
+                    "ID NUMBER": user.id_number or "",
+                    "PHONE NUMBER": "",
+                    "AMOUNT": float(payroll.total_amount),
+                    "PAYMENT MODE": "",
+                    "BANK (Optional)": "",
+                    "BANK ACCOUNT NO (Optional)": "",
+                    "PAYBILL BUSINESS NO (Optional)": "",
+                    "PAYBILL ACCOUNT NO (Optional)": "",
+                    "BUY GOODS TILL NO (Optional)": "",
+                    "BILL PAYMENT BILLER CODE (Optional)": "",
+                    "BILL PAYMENT ACCOUNT NO (Optional)": "",
+                    "NARRATION (OPTIONAL)": TendePayFormatter.build_payroll_narration(payroll)
+                })
+                exported_payroll_ids.add(payroll.id)
+                continue
+
+            # Validate payment details - generate warnings but don't skip
+            is_valid, error_msg = TendePayFormatter.validate_payment_details(
+                payment_method=payment_method,
+                payment_details=payment_details,
+                user_name=user.name
+            )
+
+            if not is_valid:
+                # WARNING - add to warnings but still export
+                warnings.append(error_msg)
+
+            # Format payroll row (always export, even with invalid details)
+            try:
+                row = TendePayFormatter.format_payroll_row(
+                    payroll=payroll,
+                    user=user,
+                    payment_method=payment_method,
+                    payment_details=payment_details,
+                    user_id_number=user.id_number
+                )
+                csv_rows.append(row)
+
+                # Track successful export
+                exported_payroll_ids.add(payroll.id)
+
+                # Warn if user has no ID number
+                if not user.id_number:
+                    warnings.append(f"{user.name}: No ID number - exported with empty ID field")
+
+            except Exception as e:
+                # Even formatting errors should not skip - create minimal row
+                logger.error(f"Failed to format payroll row for {user.name}: {str(e)}")
+                warnings.append(f"{user.name}: Formatting error - {str(e)}")
+                csv_rows.append({
+                    "NAME": user.name,
+                    "ID NUMBER": user.id_number or "",
+                    "PHONE NUMBER": "",
+                    "AMOUNT": float(payroll.total_amount),
+                    "PAYMENT MODE": "",
+                    "BANK (Optional)": "",
+                    "BANK ACCOUNT NO (Optional)": "",
+                    "PAYBILL BUSINESS NO (Optional)": "",
+                    "PAYBILL ACCOUNT NO (Optional)": "",
+                    "BUY GOODS TILL NO (Optional)": "",
+                    "BILL PAYMENT ACCOUNT NO (Optional)": "",
+                    "NARRATION (OPTIONAL)": f"Payroll {payroll.period_start_date} to {payroll.period_end_date}: {float(payroll.total_amount)} KES"
+                })
+                exported_payroll_ids.add(payroll.id)
+
+        # Mark all successfully exported payroll as paid
+        exported_payroll_records = []
+        if exported_payroll_ids:
+            try:
+                db.query(UserPayroll).filter(
+                    UserPayroll.id.in_(exported_payroll_ids)
+                ).update(
+                    {
+                        "is_paid": True,
+                        "paid_at": datetime.utcnow(),
+                        "payment_method": "tende_pay_export",
+                        "payment_reference": payment_reference,
+                        "paid_by_user_id": current_user.id
+                    },
+                    synchronize_session=False
+                )
+                db.commit()
+
+                # Fetch the exported payroll records for notifications
+                exported_payroll_records = db.query(UserPayroll).filter(
+                    UserPayroll.id.in_(exported_payroll_ids)
+                ).all()
+
+                logger.info(f"Marked {len(exported_payroll_ids)} payroll records as paid")
+            except Exception as e:
+                db.rollback()
+                logger.error(f"Failed to mark payroll as paid: {str(e)}")
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail=f"Failed to mark payroll as paid: {str(e)}"
+                )
+
+        return csv_rows, warnings, exported_payroll_records

src/app/services/project_service.py

@@ -7,7 +7,7 @@ from typing import Optional, Dict, Any, List, Tuple
 from datetime import datetime, date
 from sqlalchemy.orm import Session, joinedload
 from sqlalchemy import or_, and_, func, String
-from fastapi import HTTPException, status
+from fastapi import HTTPException, status, BackgroundTasks
 from uuid import UUID
 
 from app.models.project import Project, ProjectRegion, ProjectRole, ProjectSubcontractor
@@ -25,6 +25,8 @@ from app.schemas.project import (
 )
 from app.schemas.filters import ProjectFilters
 from app.services.base_filter_service import BaseFilterService
+from app.services.notification_creator import NotificationCreator
+from app.services.notification_delivery import NotificationDelivery
 
 logger = logging.getLogger(__name__)
 
@@ -645,7 +647,8 @@ class ProjectService(BaseFilterService):
         db: Session,
         project_id: UUID,
         setup_data: 'ProjectSetup',
-        current_user: User
+        current_user: User,
+        background_tasks: Optional[BackgroundTasks] = None
     ) -> Dict[str, Any]:
         """
         Complete project setup: Add regions, roles, subcontractors, and team members.
@@ -778,21 +781,34 @@ class ProjectService(BaseFilterService):
                     db.add(team_member)
                     team_members_added += 1
                     
-                    # Notify user about being added to project
+                    # Notify user about being added to project (Tier 1 - Synchronous)
                     try:
-                        from app.services.notification_helper import NotificationHelper
-                        import asyncio
-                        
-                        asyncio.create_task(
-                            NotificationHelper.notify_user_invited_to_project(
-                                db=db,
-                                user_id=team_data.user_id,
-                                project_id=project_id,
-                                project_name=project.project_name,
-                                invited_by=current_user,
-                                role_name=team_data.role
-                            )
+                        notification = NotificationCreator.create(
+                            db=db,
+                            user_id=team_data.user_id,
+                            title=f"🎯 Added to Project",
+                            message=f"You have been added to project '{project.project_name}' by {current_user.full_name}.\n\nYour role: {team_data.role}",
+                            source_type="project",
+                            source_id=project_id,
+                            notification_type="project_invitation",
+                            channel="in_app",
+                            project_id=project_id,
+                            metadata={
+                                "project_id": str(project_id),
+                                "project_name": project.project_name,
+                                "invited_by": current_user.full_name,
+                                "role": team_data.role,
+                                "action_url": f"/projects/{project_id}"
+                            }
                         )
+                        db.commit()
+
+                        # Queue delivery (Tier 2 - Asynchronous)
+                        if background_tasks:
+                            NotificationDelivery.queue_delivery(
+                                background_tasks=background_tasks,
+                                notification_id=notification.id
+                            )
                     except Exception as e:
                         logger.error(f"Failed to send project invitation notification: {str(e)}")
             
@@ -1234,16 +1250,11 @@ class ProjectService(BaseFilterService):
             role_name=data.role_name,
             description=data.description,
             compensation_type=data.compensation_type,
-            # NEW - Simple fields
-            daily_rate=data.daily_rate,
-            weekly_rate=data.weekly_rate,
-            per_ticket_rate=data.per_ticket_rate,
-            # OLD - Legacy fields
-            flat_rate_amount=data.flat_rate_amount,
+            # Compensation fields
+            base_rate=data.base_rate,
+            rate_period=data.rate_period,
+            per_unit_rate=data.per_unit_rate,
             commission_percentage=data.commission_percentage,
-            base_amount=data.base_amount,
-            bonus_percentage=data.bonus_percentage,
-            hourly_rate=data.hourly_rate,
             is_active=True  # Default to active for new roles
         )
         
@@ -1259,75 +1270,69 @@ class ProjectService(BaseFilterService):
         """
         Clear compensation fields that don't apply to the selected type.
         This prevents confusion and ensures only relevant fields have values.
-        
+
         World-class systems (Stripe, QuickBooks) clear irrelevant fields on type change.
         """
         # Clear ALL fields first
-        role.daily_rate = None
-        role.weekly_rate = None
-        role.per_ticket_rate = None
-        role.flat_rate_amount = None
+        role.base_rate = None
+        role.rate_period = None
+        role.per_unit_rate = None
         role.commission_percentage = None
-        role.base_amount = None
-        role.bonus_percentage = None
-        role.hourly_rate = None
-        
+
         # Note: The relevant field will be set by the caller after this function
         # This ensures clean state - only one payment method is active
     
     @staticmethod
     def _validate_compensation_structure(data):
-        """Validate compensation fields based on type"""
+        """
+        Validate compensation fields based on type
+
+        This validation is redundant with Pydantic schema validation,
+        but provides better error messages for API users.
+        """
         comp_type = data.compensation_type
-        
-        # NEW - Simple types
-        if comp_type == 'per_day':
-            if not data.daily_rate or data.daily_rate <= 0:
-                raise HTTPException(
-                    status_code=status.HTTP_400_BAD_REQUEST,
-                    detail="daily_rate is required for per_day compensation (e.g., 1000 KES/day)"
-                )
-        elif comp_type == 'per_week':
-            if not data.weekly_rate or data.weekly_rate <= 0:
+
+        if comp_type == 'FIXED_RATE':
+            if not data.base_rate or data.base_rate <= 0:
                 raise HTTPException(
                     status_code=status.HTTP_400_BAD_REQUEST,
-                    detail="weekly_rate is required for per_week compensation (e.g., 7000 KES/week)"
+                    detail="base_rate is required for FIXED_RATE compensation (e.g., 1000 KES/day, 25 USD/hour)"
                 )
-        elif comp_type == 'per_ticket':
-            if not data.per_ticket_rate or data.per_ticket_rate <= 0:
+            if not data.rate_period:
                 raise HTTPException(
                     status_code=status.HTTP_400_BAD_REQUEST,
-                    detail="per_ticket_rate is required for per_ticket compensation (e.g., 500 KES/ticket)"
+                    detail="rate_period is required for FIXED_RATE compensation (HOUR, DAY, WEEK, or MONTH)"
                 )
-        # OLD - Legacy types
-        elif comp_type == 'flat_rate':
-            if not data.flat_rate_amount or data.flat_rate_amount <= 0:
+
+        elif comp_type == 'PER_UNIT':
+            if not data.per_unit_rate or data.per_unit_rate <= 0:
                 raise HTTPException(
                     status_code=status.HTTP_400_BAD_REQUEST,
-                    detail="flat_rate_amount is required for flat_rate compensation"
+                    detail="per_unit_rate is required for PER_UNIT compensation (e.g., 500 KES/ticket)"
                 )
-        elif comp_type == 'commission':
+
+        elif comp_type == 'COMMISSION':
             if not data.commission_percentage or data.commission_percentage <= 0:
                 raise HTTPException(
                     status_code=status.HTTP_400_BAD_REQUEST,
-                    detail="commission_percentage is required for commission compensation"
+                    detail="commission_percentage is required for COMMISSION compensation (0-100)"
                 )
-        elif comp_type == 'hourly':
-            if not data.hourly_rate or data.hourly_rate <= 0:
+
+        elif comp_type == 'FIXED_PLUS_COMMISSION':
+            if not data.base_rate or data.base_rate <= 0:
                 raise HTTPException(
                     status_code=status.HTTP_400_BAD_REQUEST,
-                    detail="hourly_rate is required for hourly compensation"
+                    detail="base_rate is required for FIXED_PLUS_COMMISSION compensation"
                 )
-        elif comp_type == 'hybrid':
-            if not data.base_amount or data.base_amount < 0:
+            if not data.rate_period:
                 raise HTTPException(
                     status_code=status.HTTP_400_BAD_REQUEST,
-                    detail="base_amount is required for hybrid compensation"
+                    detail="rate_period is required for FIXED_PLUS_COMMISSION compensation"
                 )
             if not data.commission_percentage or data.commission_percentage <= 0:
                 raise HTTPException(
                     status_code=status.HTTP_400_BAD_REQUEST,
-                    detail="commission_percentage is required for hybrid compensation"
+                    detail="commission_percentage is required for FIXED_PLUS_COMMISSION compensation"
                 )
     
     @staticmethod
@@ -1398,16 +1403,10 @@ class ProjectService(BaseFilterService):
             from types import SimpleNamespace
             temp_data = SimpleNamespace(
                 compensation_type=data.compensation_type,
-                # NEW - Simple fields
-                daily_rate=data.daily_rate if data.daily_rate is not None else role.daily_rate,
-                weekly_rate=data.weekly_rate if data.weekly_rate is not None else role.weekly_rate,
-                per_ticket_rate=data.per_ticket_rate if data.per_ticket_rate is not None else role.per_ticket_rate,
-                # OLD - Legacy fields
-                flat_rate_amount=data.flat_rate_amount if data.flat_rate_amount is not None else role.flat_rate_amount,
-                commission_percentage=data.commission_percentage if data.commission_percentage is not None else role.commission_percentage,
-                hourly_rate=data.hourly_rate if data.hourly_rate is not None else role.hourly_rate,
-                base_amount=data.base_amount if data.base_amount is not None else role.base_amount,
-                bonus_percentage=data.bonus_percentage if data.bonus_percentage is not None else role.bonus_percentage
+                base_rate=data.base_rate if data.base_rate is not None else role.base_rate,
+                rate_period=data.rate_period if data.rate_period is not None else role.rate_period,
+                per_unit_rate=data.per_unit_rate if data.per_unit_rate is not None else role.per_unit_rate,
+                commission_percentage=data.commission_percentage if data.commission_percentage is not None else role.commission_percentage
             )
             ProjectService._validate_compensation_structure(temp_data)
         

src/app/services/sales_order_service.py

@@ -31,7 +31,7 @@ Authorization:
 """
 from sqlalchemy.orm import Session, joinedload
 from sqlalchemy import and_, or_, func, desc
-from fastapi import HTTPException, status, UploadFile
+from fastapi import HTTPException, status, UploadFile, BackgroundTasks
 from typing import List, Tuple, Optional, Dict, Any
 from uuid import UUID
 from datetime import datetime, date
@@ -47,6 +47,8 @@ from app.models.user import User
 from app.models.enums import AppRole, SalesOrderStatus
 from app.schemas.sales_order import *
 from app.utils.phone_utils import normalize_kenyan_phone
+from app.services.notification_creator import NotificationCreator
+from app.services.notification_delivery import NotificationDelivery
 
 logger = logging.getLogger(__name__)
 
@@ -796,7 +798,8 @@ class SalesOrderService:
     def bulk_create_from_csv(
         db: Session,
         data: SalesOrderCSVImport,
-        current_user: User
+        current_user: User,
+        background_tasks: Optional[BackgroundTasks] = None
     ) -> SalesOrderBulkImportResult:
         """
         Bulk create sales orders from CSV data with customer deduplication.
@@ -1001,22 +1004,35 @@ class SalesOrderService:
                 db.commit()
                 logger.info(f"Bulk import completed: {result.successful} successful, {result.failed} failed, {result.duplicates} duplicates")
                 
-                # Send notification to user about import results
+                # Send notification to user about import results (Tier 1 - Synchronous)
                 try:
-                    from app.services.notification_helper import NotificationHelper
-                    import asyncio
-                    asyncio.create_task(
-                        NotificationHelper.notify_bulk_import_complete(
-                            db=db,
-                            user_id=current_user.id,
-                            entity_type='sales_orders',
-                            total=result.total_rows,
-                            successful=result.successful,
-                            failed=result.failed,
-                            project_id=data.project_id,
-                            errors=result.errors[:5]  # First 5 errors only
-                        )
+                    notification = NotificationCreator.create(
+                        db=db,
+                        user_id=current_user.id,
+                        title=f"📦 Sales Orders Import Complete",
+                        message=f"Imported {result.successful} of {result.total_rows} sales orders successfully.\n\n✅ Successful: {result.successful}\n❌ Failed: {result.failed}\n🔄 Duplicates: {result.duplicates}",
+                        source_type="sales_order",
+                        source_id=None,
+                        notification_type="bulk_import_complete",
+                        channel="in_app",
+                        project_id=data.project_id,
+                        metadata={
+                            "entity_type": "sales_orders",
+                            "total": result.total_rows,
+                            "successful": result.successful,
+                            "failed": result.failed,
+                            "duplicates": result.duplicates,
+                            "errors": result.errors[:5]  # First 5 errors only
+                        }
                     )
+                    db.commit()
+
+                    # Queue delivery (Tier 2 - Asynchronous)
+                    if background_tasks:
+                        NotificationDelivery.queue_delivery(
+                            background_tasks=background_tasks,
+                            notification_id=notification.id
+                        )
                 except Exception as e:
                     logger.error(f"Failed to send bulk import notification: {str(e)}")
             else:
@@ -1025,22 +1041,35 @@ class SalesOrderService:
                 if result.duplicates > 0:
                     logger.info(f"Bulk import: All {result.duplicates} rows were duplicates")
                     
-                    # Still notify user about duplicates
+                    # Still notify user about duplicates (Tier 1 - Synchronous)
                     try:
-                        from app.services.notification_helper import NotificationHelper
-                        import asyncio
-                        asyncio.create_task(
-                            NotificationHelper.notify_bulk_import_complete(
-                                db=db,
-                                user_id=current_user.id,
-                                entity_type='sales_orders',
-                                total=result.total_rows,
-                                successful=0,
-                                failed=result.duplicates,
-                                project_id=data.project_id,
-                                errors=["All records were duplicates"]
-                            )
+                        notification = NotificationCreator.create(
+                            db=db,
+                            user_id=current_user.id,
+                            title=f"⚠️ Sales Orders Import - All Duplicates",
+                            message=f"All {result.duplicates} sales orders in the import were duplicates.\n\nNo new records were created.",
+                            source_type="sales_order",
+                            source_id=None,
+                            notification_type="bulk_import_complete",
+                            channel="in_app",
+                            project_id=data.project_id,
+                            metadata={
+                                "entity_type": "sales_orders",
+                                "total": result.total_rows,
+                                "successful": 0,
+                                "failed": 0,
+                                "duplicates": result.duplicates,
+                                "errors": ["All records were duplicates"]
+                            }
                         )
+                        db.commit()
+
+                        # Queue delivery (Tier 2 - Asynchronous)
+                        if background_tasks:
+                            NotificationDelivery.queue_delivery(
+                                background_tasks=background_tasks,
+                                notification_id=notification.id
+                            )
                     except Exception as e:
                         logger.error(f"Failed to send bulk import notification: {str(e)}")
                 else:
@@ -1198,7 +1227,8 @@ class SalesOrderService:
     def bulk_promote_to_tickets(
         db: Session,
         data: SalesOrderBulkPromote,
-        current_user: User
+        current_user: User,
+        background_tasks: Optional[BackgroundTasks] = None
     ) -> SalesOrderBulkPromoteResult:
         """Bulk promote sales orders to tickets"""
         result = SalesOrderBulkPromoteResult(
@@ -1230,31 +1260,43 @@ class SalesOrderService:
             
             logger.info(f"Bulk promote completed: {result.successful} successful, {result.failed} failed")
             
-            # Send notification to user about promotion results
+            # Send notification to user about promotion results (Tier 1 - Synchronous)
             try:
-                from app.services.notification_helper import NotificationHelper
                 from app.models.ticket import Ticket
-                import asyncio
-                
+
                 # Get project_id from first created ticket
                 project_id = None
                 if result.created_ticket_ids:
                     first_ticket = db.query(Ticket).filter(Ticket.id == result.created_ticket_ids[0]).first()
                     if first_ticket:
                         project_id = first_ticket.project_id
-                
-                asyncio.create_task(
-                    NotificationHelper.notify_bulk_promote_complete(
-                        db=db,
-                        user_id=current_user.id,
-                        total=result.total_orders,
-                        successful=result.successful,
-                        failed=result.failed,
-                        created_ticket_ids=result.created_ticket_ids,
-                        project_id=project_id,
-                        errors=result.errors[:5]  # First 5 errors only
-                    )
+
+                notification = NotificationCreator.create(
+                    db=db,
+                    user_id=current_user.id,
+                    title=f"🎫 Bulk Promote Complete",
+                    message=f"Promoted {result.successful} of {result.total_orders} sales orders to tickets.\n\n✅ Successful: {result.successful}\n❌ Failed: {result.failed}",
+                    source_type="sales_order",
+                    source_id=None,
+                    notification_type="bulk_promote_complete",
+                    channel="in_app",
+                    project_id=project_id,
+                    metadata={
+                        "total": result.total_orders,
+                        "successful": result.successful,
+                        "failed": result.failed,
+                        "created_ticket_ids": [str(tid) for tid in result.created_ticket_ids],
+                        "errors": result.errors[:5]  # First 5 errors only
+                    }
                 )
+                db.commit()
+
+                # Queue delivery (Tier 2 - Asynchronous)
+                if background_tasks:
+                    NotificationDelivery.queue_delivery(
+                        background_tasks=background_tasks,
+                        notification_id=notification.id
+                    )
             except Exception as e:
                 logger.error(f"Failed to send bulk promote notification: {str(e)}")
         

src/app/services/task_service.py

@@ -7,7 +7,7 @@ from typing import Optional, Dict, Any, List, Tuple
 from datetime import datetime, date
 from sqlalchemy.orm import Session, joinedload
 from sqlalchemy import or_, and_, func
-from fastapi import HTTPException, status
+from fastapi import HTTPException, status, BackgroundTasks
 from uuid import UUID
 
 from app.models.task import Task
@@ -15,6 +15,8 @@ from app.models.project import Project, ProjectRegion
 from app.models.user import User
 from app.models.enums import AppRole, TaskStatus, TicketPriority
 from app.schemas.task import TaskCreate, TaskUpdate, TaskStatusUpdate, TaskStart, TaskComplete, TaskCancel
+from app.services.notification_creator import NotificationCreator
+from app.services.notification_delivery import NotificationDelivery
 
 logger = logging.getLogger(__name__)
 
@@ -82,7 +84,8 @@ class TaskService:
     def create_task(
         db: Session,
         data: TaskCreate,
-        current_user: User
+        current_user: User,
+        background_tasks: Optional[BackgroundTasks] = None
     ) -> Task:
         """
         Create a new task for an infrastructure project
@@ -149,21 +152,34 @@ class TaskService:
         
         logger.info(f"Task created: {task.id} - {task.task_title} for project {project.id} by user {current_user.id}")
         
-        # Notify PMs/managers about new task
+        # Notify PMs/managers about new task (Tier 1 - Synchronous)
         try:
-            from app.services.notification_helper import NotificationHelper
-            import asyncio
-            
-            notify_users = NotificationHelper.get_project_managers_and_dispatchers(db, task.project_id)
-            
-            if notify_users:
-                asyncio.create_task(
-                    NotificationHelper.notify_task_created(
-                        db=db,
-                        task=task,
-                        created_by=current_user,
-                        notify_users=notify_users
-                    )
+            notification_ids = NotificationCreator.notify_project_team(
+                db=db,
+                project_id=task.project_id,
+                title=f"📋 New Task Created",
+                message=f"Task '{task.task_title}' was created by {current_user.full_name}.\n\nType: {task.task_type or 'General'}\nPriority: {task.priority.value if task.priority else 'Normal'}",
+                source_type="task",
+                source_id=task.id,
+                notification_type="task_created",
+                channel="in_app",
+                roles=["project_manager", "dispatcher"],
+                metadata={
+                    "task_id": str(task.id),
+                    "task_title": task.task_title,
+                    "task_type": task.task_type,
+                    "priority": task.priority.value if task.priority else None,
+                    "created_by": current_user.full_name,
+                    "action_url": f"/tasks/{task.id}"
+                }
+            )
+            db.commit()
+
+            # Queue delivery (Tier 2 - Asynchronous)
+            if background_tasks and notification_ids:
+                NotificationDelivery.queue_bulk_delivery(
+                    background_tasks=background_tasks,
+                    notification_ids=notification_ids
                 )
         except Exception as e:
             logger.error(f"Failed to send task creation notification: {str(e)}")
@@ -461,7 +477,8 @@ class TaskService:
         db: Session,
         task_id: UUID,
         data: TaskComplete,
-        current_user: User
+        current_user: User,
+        background_tasks: Optional[BackgroundTasks] = None
     ) -> Task:
         """Complete a task"""
         task = TaskService.get_task_by_id(db, task_id, current_user)
@@ -488,21 +505,34 @@ class TaskService:
         
         logger.info(f"Task completed: {task.id}")
         
-        # Notify PMs/managers about task completion
+        # Notify PMs/managers about task completion (Tier 1 - Synchronous)
         try:
-            from app.services.notification_helper import NotificationHelper
-            import asyncio
-            
-            notify_users = NotificationHelper.get_project_managers_and_dispatchers(db, task.project_id)
-            
-            if notify_users:
-                asyncio.create_task(
-                    NotificationHelper.notify_task_completed(
-                        db=db,
-                        task=task,
-                        completed_by=current_user,
-                        notify_users=notify_users
-                    )
+            notification_ids = NotificationCreator.notify_project_team(
+                db=db,
+                project_id=task.project_id,
+                title=f"✅ Task Completed",
+                message=f"Task '{task.task_title}' was completed by {current_user.full_name}.",
+                source_type="task",
+                source_id=task.id,
+                notification_type="task_completed",
+                channel="in_app",
+                roles=["project_manager", "dispatcher"],
+                metadata={
+                    "task_id": str(task.id),
+                    "task_title": task.task_title,
+                    "completed_by": current_user.full_name,
+                    "completed_at": str(task.completed_at),
+                    "completion_notes": data.completion_notes,
+                    "action_url": f"/tasks/{task.id}"
+                }
+            )
+            db.commit()
+
+            # Queue delivery (Tier 2 - Asynchronous)
+            if background_tasks and notification_ids:
+                NotificationDelivery.queue_bulk_delivery(
+                    background_tasks=background_tasks,
+                    notification_ids=notification_ids
                 )
         except Exception as e:
             logger.error(f"Failed to send task completion notification: {str(e)}")
@@ -514,7 +544,8 @@ class TaskService:
         db: Session,
         task_id: UUID,
         data: TaskCancel,
-        current_user: User
+        current_user: User,
+        background_tasks: Optional[BackgroundTasks] = None
     ) -> Task:
         """Cancel a task"""
         task = TaskService.get_task_by_id(db, task_id, current_user)
@@ -536,22 +567,33 @@ class TaskService:
         
         logger.info(f"Task cancelled: {task.id}")
         
-        # Notify PMs/managers about task cancellation
+        # Notify PMs/managers about task cancellation (Tier 1 - Synchronous)
         try:
-            from app.services.notification_helper import NotificationHelper
-            import asyncio
-            
-            notify_users = NotificationHelper.get_project_managers_and_dispatchers(db, task.project_id)
-            
-            if notify_users:
-                asyncio.create_task(
-                    NotificationHelper.notify_task_cancelled(
-                        db=db,
-                        task=task,
-                        cancelled_by=current_user,
-                        reason=data.cancellation_reason,
-                        notify_users=notify_users
-                    )
+            notification_ids = NotificationCreator.notify_project_team(
+                db=db,
+                project_id=task.project_id,
+                title=f"❌ Task Cancelled",
+                message=f"Task '{task.task_title}' was cancelled by {current_user.full_name}.\n\nReason: {data.cancellation_reason}",
+                source_type="task",
+                source_id=task.id,
+                notification_type="task_cancelled",
+                channel="in_app",
+                roles=["project_manager", "dispatcher"],
+                metadata={
+                    "task_id": str(task.id),
+                    "task_title": task.task_title,
+                    "cancelled_by": current_user.full_name,
+                    "cancellation_reason": data.cancellation_reason,
+                    "action_url": f"/tasks/{task.id}"
+                }
+            )
+            db.commit()
+
+            # Queue delivery (Tier 2 - Asynchronous)
+            if background_tasks and notification_ids:
+                NotificationDelivery.queue_bulk_delivery(
+                    background_tasks=background_tasks,
+                    notification_ids=notification_ids
                 )
         except Exception as e:
             logger.error(f"Failed to send task cancellation notification: {str(e)}")

src/app/services/tende_pay_formatter.py

@@ -390,5 +390,114 @@ class TendePayFormatter:
         
         elif payment_mode == "BUYGOODS":
             row["BUY GOODS TILL NO (Optional)"] = payment_details.get("till_number", "")
-        
+
         return row
+
+    @staticmethod
+    def format_payroll_row(
+        payroll,
+        user,
+        payment_method: str,
+        payment_details: Dict,
+        user_id_number: Optional[str] = None
+    ) -> Dict[str, str]:
+        """
+        Format a payroll record into a Tende Pay CSV row.
+
+        Args:
+            payroll: UserPayroll object
+            user: User object
+            payment_method: Payment method (send_money, bank_transfer, etc.)
+            payment_details: Payment details dict from user_financial_account
+            user_id_number: User's ID number (optional)
+
+        Returns:
+            Dict with Tende Pay CSV columns
+        """
+        # Build payroll narration
+        narration = TendePayFormatter.build_payroll_narration(payroll)
+
+        # Map payment mode
+        payment_mode = TendePayFormatter.PAYMENT_MODE_MAP.get(payment_method)
+        if not payment_mode:
+            raise ValueError(f"Unsupported payment method: {payment_method}")
+
+        # Base row structure (all Tende Pay columns)
+        row = {
+            "NAME": user.name,
+            "ID NUMBER": user_id_number or "",
+            "PHONE NUMBER": "",
+            "AMOUNT": float(payroll.total_amount),
+            "PAYMENT MODE": payment_mode,
+            "BANK (Optional)": "",
+            "BANK ACCOUNT NO (Optional)": "",
+            "PAYBILL BUSINESS NO (Optional)": "",
+            "PAYBILL ACCOUNT NO (Optional)": "",
+            "BUY GOODS TILL NO (Optional)": "",
+            "BILL PAYMENT BILLER CODE (Optional)": "",
+            "BILL PAYMENT ACCOUNT NO (Optional)": "",
+            "NARRATION (OPTIONAL)": narration
+        }
+
+        # Fill in method-specific fields
+        if payment_mode == "MPESA":
+            phone = payment_details.get("phone_number")
+            row["PHONE NUMBER"] = TendePayFormatter.normalize_phone(phone)
+
+        elif payment_mode == "BANK":
+            row["BANK (Optional)"] = payment_details.get("bank_name", "")
+            row["BANK ACCOUNT NO (Optional)"] = payment_details.get("account_number", "")
+
+        elif payment_mode == "PAYBILL":
+            row["PAYBILL BUSINESS NO (Optional)"] = payment_details.get("business_number", "")
+            row["PAYBILL ACCOUNT NO (Optional)"] = payment_details.get("account_number", "")
+
+        elif payment_mode == "BUYGOODS":
+            row["BUY GOODS TILL NO (Optional)"] = payment_details.get("till_number", "")
+
+        return row
+
+    @staticmethod
+    def build_payroll_narration(
+        payroll,
+        max_length: int = MAX_NARRATION_LENGTH
+    ) -> str:
+        """
+        Build narration for payroll payment.
+
+        Format: "Payroll {period}: {days} days, {tickets} tickets, {amount} KES"
+        Example: "Payroll 2024-12-02 to 2024-12-08: 5 days worked, 12 tickets closed, 5000 KES"
+
+        Args:
+            payroll: UserPayroll object
+            max_length: Maximum narration length
+
+        Returns:
+            Formatted narration string
+        """
+        # Build period string
+        period_str = f"{payroll.period_start_date.isoformat()} to {payroll.period_end_date.isoformat()}"
+
+        # Build work summary
+        work_parts = []
+        if payroll.days_worked:
+            work_parts.append(f"{payroll.days_worked} days worked")
+        if payroll.tickets_closed:
+            work_parts.append(f"{payroll.tickets_closed} tickets closed")
+
+        work_summary = ", ".join(work_parts) if work_parts else "No work recorded"
+
+        # Build full narration
+        narration = (
+            f"Payroll {period_str}: "
+            f"{work_summary}, "
+            f"{float(payroll.total_amount)} KES"
+        )
+
+        # Truncate if too long
+        if len(narration) > max_length:
+            truncated = narration[:max_length - 3] + "..."
+            logger.warning(f"Payroll narration truncated from {len(narration)} to {max_length} chars")
+            return truncated
+
+        return narration

src/app/services/ticket_assignment_service.py

@@ -130,13 +130,36 @@ class TicketAssignmentService:
         
         self.db.commit()
         self.db.refresh(assignment)
-        
+
+        # Real-time timesheet update (best-effort, don't block on failure)
+        try:
+            from app.services.timesheet_realtime_service import update_timesheet_for_event
+            from datetime import date
+
+            timesheet_id = update_timesheet_for_event(
+                db=self.db,
+                user_id=user_id,
+                project_id=ticket.project_id,
+                work_date=date.today(),
+                event_type='assignment_created',
+                entity_type='ticket_assignment',
+                entity_id=assignment.id
+            )
+
+            if timesheet_id:
+                logger.debug(f"Timesheet {timesheet_id} updated for assignment {assignment.id}")
+            else:
+                logger.warning(f"Failed to update timesheet for assignment {assignment.id}")
+
+        except Exception as e:
+            logger.error(f"Timesheet update error for assignment {assignment.id}: {e}", exc_info=True)
+
         # Send notification to agent (non-blocking)
         try:
             logger.info(f"Ticket {ticket.id} assigned to {agent.full_name} - notification queued")
         except Exception as e:
             logger.warning(f"Failed to queue assignment notification: {str(e)}")
-        
+
         return self._to_response(assignment)
     
     def assign_team(
@@ -418,21 +441,44 @@ class TicketAssignmentService:
         
         self.db.commit()
         self.db.refresh(assignment)
-        
+
+        # Real-time timesheet update (best-effort, don't block on failure)
+        try:
+            from app.services.timesheet_realtime_service import update_timesheet_for_event
+            from datetime import date
+
+            timesheet_id = update_timesheet_for_event(
+                db=self.db,
+                user_id=user_id,
+                project_id=ticket.project_id,
+                work_date=date.today(),
+                event_type='self_assignment_created',
+                entity_type='ticket_assignment',
+                entity_id=assignment.id
+            )
+
+            if timesheet_id:
+                logger.debug(f"Timesheet {timesheet_id} updated for self-assignment {assignment.id}")
+            else:
+                logger.warning(f"Failed to update timesheet for self-assignment {assignment.id}")
+
+        except Exception as e:
+            logger.error(f"Timesheet update error for self-assignment {assignment.id}: {e}", exc_info=True)
+
         # Notify PM/Dispatcher about self-assignment
         # Note: Notifications are non-blocking and failures don't affect the operation
         try:
             from app.services.notification_helper import NotificationHelper
-            
+
             notify_users = NotificationHelper.get_project_managers_and_dispatchers(self.db, ticket.project_id)
-            
+
             if notify_users:
                 # Use background task or queue for async notifications
                 # For now, we'll skip to avoid blocking the request
                 logger.info(f"Ticket {ticket.id} self-assigned by {agent.full_name} - notification queued")
         except Exception as e:
             logger.warning(f"Failed to queue self-assignment notification: {str(e)}")
-        
+
         return self._to_response(assignment)
     
     # ============================================
@@ -457,10 +503,33 @@ class TicketAssignmentService:
             )
         
         assignment.mark_accepted(data.notes)
-        
+
         self.db.commit()
         self.db.refresh(assignment)
-        
+
+        # Real-time timesheet update (best-effort, don't block on failure)
+        try:
+            from app.services.timesheet_realtime_service import update_timesheet_for_event
+            from datetime import date
+
+            timesheet_id = update_timesheet_for_event(
+                db=self.db,
+                user_id=user_id,
+                project_id=assignment.ticket.project_id,
+                work_date=date.today(),
+                event_type='assignment_accepted',
+                entity_type='ticket_assignment',
+                entity_id=assignment.id
+            )
+
+            if timesheet_id:
+                logger.debug(f"Timesheet {timesheet_id} updated for accepted assignment {assignment.id}")
+            else:
+                logger.warning(f"Failed to update timesheet for accepted assignment {assignment.id}")
+
+        except Exception as e:
+            logger.error(f"Timesheet update error for accepted assignment {assignment.id}: {e}", exc_info=True)
+
         return self._to_response(assignment)
     
     def reject_assignment(
@@ -507,13 +576,36 @@ class TicketAssignmentService:
         
         self.db.commit()
         self.db.refresh(assignment)
-        
+
+        # Real-time timesheet update (best-effort, don't block on failure)
+        try:
+            from app.services.timesheet_realtime_service import update_timesheet_for_event
+            from datetime import date
+
+            timesheet_id = update_timesheet_for_event(
+                db=self.db,
+                user_id=user_id,
+                project_id=ticket.project_id,
+                work_date=date.today(),
+                event_type='assignment_rejected',
+                entity_type='ticket_assignment',
+                entity_id=assignment.id
+            )
+
+            if timesheet_id:
+                logger.debug(f"Timesheet {timesheet_id} updated for rejected assignment {assignment.id}")
+            else:
+                logger.warning(f"Failed to update timesheet for rejected assignment {assignment.id}")
+
+        except Exception as e:
+            logger.error(f"Timesheet update error for rejected assignment {assignment.id}: {e}", exc_info=True)
+
         # Notify dispatcher/PM about rejection (non-blocking)
         try:
             logger.info(f"Assignment {assignment.id} rejected - notification queued")
         except Exception as e:
             logger.warning(f"Failed to queue rejection notification: {str(e)}")
-        
+
         return self._to_response(assignment)
     
     def start_journey(
@@ -784,13 +876,33 @@ class TicketAssignmentService:
         
         self.db.commit()
         self.db.refresh(assignment)
-        
-        # Notify PM/dispatcher about drop (non-blocking)
+
+        # Real-time timesheet update (best-effort, don't block on failure)
         try:
-            logger.info(f"Ticket {ticket.id} dropped by agent - notification queued")
+            from app.services.timesheet_realtime_service import update_timesheet_for_event
+            from datetime import date
+
+            timesheet_id = update_timesheet_for_event(
+                db=self.db,
+                user_id=user_id,
+                project_id=ticket.project_id,
+                work_date=date.today(),
+                event_type='assignment_dropped',
+                entity_type='ticket_assignment',
+                entity_id=assignment.id
+            )
+
+            if timesheet_id:
+                logger.debug(f"Timesheet {timesheet_id} updated for dropped assignment {assignment.id}")
+            else:
+                logger.warning(f"Failed to update timesheet for dropped assignment {assignment.id}")
+
         except Exception as e:
-            logger.warning(f"Failed to queue drop notification: {str(e)}")
-        
+            logger.error(f"Timesheet update error for dropped assignment {assignment.id}: {e}", exc_info=True)
+
+        # Notification is handled in the API endpoint (async context)
+        logger.info(f"Ticket {ticket.id} dropped by agent {user_id} - status set to PENDING_REVIEW")
+
         return self._to_response(assignment)
     
     def complete_assignment(
@@ -913,13 +1025,36 @@ class TicketAssignmentService:
         
         self.db.commit()
         self.db.refresh(assignment)
-        
+
+        # Real-time timesheet update (best-effort, don't block on failure)
+        try:
+            from app.services.timesheet_realtime_service import update_timesheet_for_event
+            from datetime import date
+
+            timesheet_id = update_timesheet_for_event(
+                db=self.db,
+                user_id=user_id,
+                project_id=ticket.project_id,
+                work_date=date.today(),
+                event_type='assignment_completed',
+                entity_type='ticket_assignment',
+                entity_id=assignment.id
+            )
+
+            if timesheet_id:
+                logger.debug(f"Timesheet {timesheet_id} updated for completed assignment {assignment.id}")
+            else:
+                logger.warning(f"Failed to update timesheet for completed assignment {assignment.id}")
+
+        except Exception as e:
+            logger.error(f"Timesheet update error for completed assignment {assignment.id}: {e}", exc_info=True)
+
         # Notify PM/Dispatcher about ticket completion (non-blocking)
         try:
             logger.info(f"Ticket {ticket.id} completed - notification queued")
         except Exception as e:
             logger.warning(f"Failed to queue completion notification: {str(e)}")
-        
+
         return self._to_response(assignment)
     
     # ============================================

src/app/services/ticket_completion_service.py

@@ -519,9 +519,38 @@ class TicketCompletionService:
         
         db.commit()
         db.refresh(ticket)
-        
+
+        # Real-time timesheet update for all agents who worked on this ticket (best-effort, don't block on failure)
+        try:
+            from app.services.timesheet_realtime_service import update_timesheet_for_event
+            from datetime import date
+
+            # Update timesheets for all agents who had assignments on this ticket
+            for assignment in active_assignments:
+                try:
+                    timesheet_id = update_timesheet_for_event(
+                        db=db,
+                        user_id=assignment.user_id,
+                        project_id=ticket.project_id,
+                        work_date=date.today(),
+                        event_type='ticket_completed',
+                        entity_type='ticket',
+                        entity_id=ticket.id
+                    )
+
+                    if timesheet_id:
+                        logger.debug(f"Timesheet {timesheet_id} updated for agent {assignment.user_id} on completed ticket {ticket.id}")
+                    else:
+                        logger.warning(f"Failed to update timesheet for agent {assignment.user_id} on completed ticket {ticket.id}")
+
+                except Exception as agent_error:
+                    logger.error(f"Timesheet update error for agent {assignment.user_id} on ticket {ticket.id}: {agent_error}", exc_info=True)
+
+        except Exception as e:
+            logger.error(f"Timesheet update error for completed ticket {ticket.id}: {e}", exc_info=True)
+
         logger.info(f"Ticket {ticket.id} completed successfully")
-        
+
         return {
             "success": True,
             "message": "Ticket completed successfully!",

src/app/services/ticket_expense_service.py

@@ -17,7 +17,7 @@ Business Rules:
 
 from sqlalchemy.orm import Session, joinedload
 from sqlalchemy import and_, or_, func, desc
-from fastapi import HTTPException, status
+from fastapi import HTTPException, status, BackgroundTasks
 from typing import List, Optional, Tuple
 from uuid import UUID
 from datetime import datetime, date
@@ -39,6 +39,8 @@ from app.schemas.ticket_expense import (
     TicketExpenseResponse,
     TicketExpenseStats,
 )
+from app.services.notification_creator import NotificationCreator
+from app.services.notification_delivery import NotificationDelivery
 
 logger = logging.getLogger(__name__)
 
@@ -189,13 +191,35 @@ class TicketExpenseService:
         db.add(expense)
         db.commit()
         db.refresh(expense)
-        
+
         logger.info(
             f"Expense created: {expense.id} by user {current_user.id} "
             f"for ticket {ticket.id}, amount: {expense.total_cost}, "
             f"location_verified: {location_verified}"
         )
-        
+
+        # Real-time timesheet update (best-effort, don't block on failure)
+        try:
+            from app.services.timesheet_realtime_service import update_timesheet_for_event
+
+            timesheet_id = update_timesheet_for_event(
+                db=db,
+                user_id=current_user.id,
+                project_id=ticket.project_id,
+                work_date=data.expense_date,
+                event_type='expense_created',
+                entity_type='ticket_expense',
+                entity_id=expense.id
+            )
+
+            if timesheet_id:
+                logger.debug(f"Timesheet {timesheet_id} updated for expense {expense.id}")
+            else:
+                logger.warning(f"Failed to update timesheet for expense {expense.id}")
+
+        except Exception as e:
+            logger.error(f"Timesheet update error for expense {expense.id}: {e}", exc_info=True)
+
         return expense
     
     # ============================================
@@ -300,12 +324,34 @@ class TicketExpenseService:
             expense.verification_notes = verification_notes
         
         expense.updated_at = datetime.utcnow()
-        
+
         db.commit()
         db.refresh(expense)
-        
+
         logger.info(f"Expense updated: {expense.id} by user {current_user.id}")
-        
+
+        # Real-time timesheet update (best-effort, don't block on failure)
+        try:
+            from app.services.timesheet_realtime_service import update_timesheet_for_event
+
+            timesheet_id = update_timesheet_for_event(
+                db=db,
+                user_id=expense.incurred_by_user_id,
+                project_id=expense.ticket.project_id,
+                work_date=expense.expense_date,
+                event_type='expense_updated',
+                entity_type='ticket_expense',
+                entity_id=expense.id
+            )
+
+            if timesheet_id:
+                logger.debug(f"Timesheet {timesheet_id} updated for expense {expense.id}")
+            else:
+                logger.warning(f"Failed to update timesheet for expense {expense.id}")
+
+        except Exception as e:
+            logger.error(f"Timesheet update error for expense {expense.id}: {e}", exc_info=True)
+
         return expense
     
     # ============================================
@@ -388,36 +434,87 @@ class TicketExpenseService:
         
         db.commit()
         db.refresh(expense)
-        
-        # Send notification to agent
-        if background_tasks:
-            try:
-                from app.services.notification_helper import NotificationHelper
-                
-                # Get the agent who submitted the expense
-                agent = db.query(User).filter(User.id == expense.incurred_by_user_id).first()
-                
-                if agent:
-                    if data.is_approved:
-                        background_tasks.add_task(
-                            NotificationHelper.notify_expense_approved,
-                            db=db,
-                            expense=expense,
-                            approved_by=current_user,
-                            agent=agent
-                        )
-                    else:
-                        background_tasks.add_task(
-                            NotificationHelper.notify_expense_rejected,
-                            db=db,
-                            expense=expense,
-                            rejected_by=current_user,
-                            agent=agent,
-                            reason=data.rejection_reason or "No reason provided"
-                        )
-            except Exception as e:
-                action = "approved" if data.is_approved else "rejected"
-                logger.error(f"Failed to queue expense {action} notification: {str(e)}")
+
+        # Real-time timesheet update (best-effort, don't block on failure)
+        try:
+            from app.services.timesheet_realtime_service import update_timesheet_for_event
+
+            event_type = 'expense_approved' if data.is_approved else 'expense_rejected'
+
+            timesheet_id = update_timesheet_for_event(
+                db=db,
+                user_id=expense.incurred_by_user_id,
+                project_id=expense.ticket.project_id,
+                work_date=expense.expense_date,
+                event_type=event_type,
+                entity_type='ticket_expense',
+                entity_id=expense.id
+            )
+
+            if timesheet_id:
+                logger.debug(f"Timesheet {timesheet_id} updated for {event_type} expense {expense.id}")
+            else:
+                logger.warning(f"Failed to update timesheet for {event_type} expense {expense.id}")
+
+        except Exception as e:
+            logger.error(f"Timesheet update error for expense {expense.id}: {e}", exc_info=True)
+
+        # Send notification to agent (Tier 1 - Synchronous)
+        try:
+            # Get the agent who submitted the expense
+            agent = db.query(User).filter(User.id == expense.incurred_by_user_id).first()
+
+            if agent:
+                if data.is_approved:
+                    notification = NotificationCreator.create(
+                        db=db,
+                        user_id=agent.id,
+                        title=f"✅ Expense Approved",
+                        message=f"Your expense of {expense.total_cost} {expense.currency} has been approved by {current_user.full_name}.",
+                        source_type="expense",
+                        source_id=expense.id,
+                        notification_type="expense_approved",
+                        channel="in_app",
+                        project_id=expense.ticket.project_id if expense.ticket else None,
+                        metadata={
+                            "expense_id": str(expense.id),
+                            "amount": str(expense.total_cost),
+                            "currency": expense.currency,
+                            "approved_by": current_user.full_name,
+                            "action_url": f"/expenses/{expense.id}"
+                        }
+                    )
+                else:
+                    notification = NotificationCreator.create(
+                        db=db,
+                        user_id=agent.id,
+                        title=f"❌ Expense Rejected",
+                        message=f"Your expense of {expense.total_cost} {expense.currency} was rejected by {current_user.full_name}.\n\nReason: {data.rejection_reason or 'No reason provided'}",
+                        source_type="expense",
+                        source_id=expense.id,
+                        notification_type="expense_rejected",
+                        channel="in_app",
+                        project_id=expense.ticket.project_id if expense.ticket else None,
+                        metadata={
+                            "expense_id": str(expense.id),
+                            "amount": str(expense.total_cost),
+                            "currency": expense.currency,
+                            "rejected_by": current_user.full_name,
+                            "rejection_reason": data.rejection_reason,
+                            "action_url": f"/expenses/{expense.id}"
+                        }
+                    )
+                db.commit()
+
+                # Queue delivery (Tier 2 - Asynchronous)
+                if background_tasks:
+                    NotificationDelivery.queue_delivery(
+                        background_tasks=background_tasks,
+                        notification_id=notification.id
+                    )
+        except Exception as e:
+            action = "approved" if data.is_approved else "rejected"
+            logger.error(f"Failed to send expense {action} notification: {str(e)}")
         
         return expense
     
@@ -1545,35 +1642,64 @@ class TicketExpenseService:
             for expense in updated_expenses:
                 db.refresh(expense)
             
-            # Send notifications to agents
-            if background_tasks:
-                try:
-                    from app.services.notification_helper import NotificationHelper
-                    
-                    for expense in updated_expenses:
-                        # Get the agent who submitted the expense
-                        agent = db.query(User).filter(User.id == expense.incurred_by_user_id).first()
-                        
-                        if agent:
-                            if is_approved:
-                                background_tasks.add_task(
-                                    NotificationHelper.notify_expense_approved,
-                                    db=db,
-                                    expense=expense,
-                                    approved_by=current_user,
-                                    agent=agent
-                                )
-                            else:
-                                background_tasks.add_task(
-                                    NotificationHelper.notify_expense_rejected,
-                                    db=db,
-                                    expense=expense,
-                                    rejected_by=current_user,
-                                    agent=agent,
-                                    reason=rejection_reason or "No reason provided"
-                                )
-                except Exception as e:
-                    logger.error(f"Failed to queue bulk {action} notifications: {str(e)}")
+            # Send notifications to agents (Tier 1 - Synchronous)
+            try:
+                notification_ids = []
+                for expense in updated_expenses:
+                    # Get the agent who submitted the expense
+                    agent = db.query(User).filter(User.id == expense.incurred_by_user_id).first()
+
+                    if agent:
+                        if is_approved:
+                            notification = NotificationCreator.create(
+                                db=db,
+                                user_id=agent.id,
+                                title=f"✅ Expense Approved",
+                                message=f"Your expense of {expense.total_cost} {expense.currency} has been approved by {current_user.full_name}.",
+                                source_type="expense",
+                                source_id=expense.id,
+                                notification_type="expense_approved",
+                                channel="in_app",
+                                project_id=expense.ticket.project_id if expense.ticket else None,
+                                metadata={
+                                    "expense_id": str(expense.id),
+                                    "amount": str(expense.total_cost),
+                                    "currency": expense.currency,
+                                    "approved_by": current_user.full_name,
+                                    "action_url": f"/expenses/{expense.id}"
+                                }
+                            )
+                        else:
+                            notification = NotificationCreator.create(
+                                db=db,
+                                user_id=agent.id,
+                                title=f"❌ Expense Rejected",
+                                message=f"Your expense of {expense.total_cost} {expense.currency} was rejected by {current_user.full_name}.\n\nReason: {rejection_reason or 'No reason provided'}",
+                                source_type="expense",
+                                source_id=expense.id,
+                                notification_type="expense_rejected",
+                                channel="in_app",
+                                project_id=expense.ticket.project_id if expense.ticket else None,
+                                metadata={
+                                    "expense_id": str(expense.id),
+                                    "amount": str(expense.total_cost),
+                                    "currency": expense.currency,
+                                    "rejected_by": current_user.full_name,
+                                    "rejection_reason": rejection_reason,
+                                    "action_url": f"/expenses/{expense.id}"
+                                }
+                            )
+                        notification_ids.append(notification.id)
+                db.commit()
+
+                # Queue delivery (Tier 2 - Asynchronous)
+                if background_tasks and notification_ids:
+                    NotificationDelivery.queue_bulk_delivery(
+                        background_tasks=background_tasks,
+                        notification_ids=notification_ids
+                    )
+            except Exception as e:
+                logger.error(f"Failed to send bulk {action} notifications: {str(e)}")
             
             # Notify the initiator (PM) about bulk operation completion
             if background_tasks and updated_expenses:

src/app/services/ticket_service.py

@@ -21,7 +21,7 @@ Authorization:
 """
 from sqlalchemy.orm import Session, joinedload
 from sqlalchemy import and_, or_, func, desc, case, select
-from fastapi import HTTPException, status
+from fastapi import HTTPException, status, BackgroundTasks
 from typing import List, Tuple, Optional
 from uuid import UUID
 from datetime import datetime, date, timedelta
@@ -37,6 +37,8 @@ from app.models.enums import AppRole, TicketSource, TicketType, TicketStatus, Ti
 from app.schemas.ticket import *
 from app.schemas.filters import TicketFilters
 from app.services.base_filter_service import BaseFilterService
+from app.services.notification_creator import NotificationCreator
+from app.services.notification_delivery import NotificationDelivery
 
 logger = logging.getLogger(__name__)
 
@@ -1006,7 +1008,8 @@ class TicketService(BaseFilterService):
         db: Session,
         ticket_id: UUID,
         data: TicketCancel,
-        current_user: User
+        current_user: User,
+        background_tasks: Optional[BackgroundTasks] = None
     ) -> Ticket:
         """Cancel ticket"""
         ticket = TicketService.get_ticket_by_id(db, ticket_id, current_user)
@@ -1043,23 +1046,34 @@ class TicketService(BaseFilterService):
         
         logger.info(f"Cancelled ticket {ticket_id}: {data.reason}")
         
-        # Notify PM/Dispatcher about cancellation
+        # Notify PM/Dispatcher about cancellation (Tier 1 - Synchronous)
         try:
-            from app.services.notification_helper import NotificationHelper
-            import asyncio
-            
-            notify_users = NotificationHelper.get_project_managers_and_dispatchers(db, ticket.project_id)
-            
-            if notify_users:
-                asyncio.create_task(
-                    NotificationHelper.notify_ticket_status_changed(
-                        db=db,
-                        ticket=ticket,
-                        old_status=old_status,
-                        new_status=ticket.status,
-                        changed_by=current_user,
-                        notify_users=notify_users
-                    )
+            notification_ids = NotificationCreator.notify_project_team(
+                db=db,
+                project_id=ticket.project_id,
+                title=f"🚫 Ticket Cancelled",
+                message=f"Ticket #{ticket.id} was cancelled by {current_user.full_name}.\n\nReason: {data.reason}\nPrevious Status: {old_status.value}",
+                source_type="ticket",
+                source_id=ticket.id,
+                notification_type="ticket_cancelled",
+                channel="in_app",
+                roles=["project_manager", "dispatcher"],
+                metadata={
+                    "ticket_id": str(ticket.id),
+                    "old_status": old_status.value,
+                    "new_status": ticket.status.value,
+                    "cancelled_by": current_user.full_name,
+                    "cancellation_reason": data.reason,
+                    "action_url": f"/tickets/{ticket.id}"
+                }
+            )
+            db.commit()
+
+            # Queue delivery (Tier 2 - Asynchronous)
+            if background_tasks and notification_ids:
+                NotificationDelivery.queue_bulk_delivery(
+                    background_tasks=background_tasks,
+                    notification_ids=notification_ids
                 )
         except Exception as e:
             logger.error(f"Failed to send ticket cancellation notification: {str(e)}")
@@ -1071,7 +1085,8 @@ class TicketService(BaseFilterService):
         db: Session,
         ticket_id: UUID,
         data: TicketReopen,
-        current_user: User
+        current_user: User,
+        background_tasks: Optional[BackgroundTasks] = None
     ) -> Ticket:
         """
         Reopen a cancelled, completed, or pending_review ticket.
@@ -1146,23 +1161,34 @@ class TicketService(BaseFilterService):
         
         logger.info(f"Reopened ticket {ticket_id} from {old_status} to {ticket.status}")
         
-        # Notify PM/Dispatcher about reopening
+        # Notify PM/Dispatcher about reopening (Tier 1 - Synchronous)
         try:
-            from app.services.notification_helper import NotificationHelper
-            import asyncio
-            
-            notify_users = NotificationHelper.get_project_managers_and_dispatchers(db, ticket.project_id)
-            
-            if notify_users:
-                asyncio.create_task(
-                    NotificationHelper.notify_ticket_status_changed(
-                        db=db,
-                        ticket=ticket,
-                        old_status=old_status,
-                        new_status=ticket.status,
-                        changed_by=current_user,
-                        notify_users=notify_users
-                    )
+            notification_ids = NotificationCreator.notify_project_team(
+                db=db,
+                project_id=ticket.project_id,
+                title=f"🔄 Ticket Reopened",
+                message=f"Ticket #{ticket.id} was reopened by {current_user.full_name}.\n\nPrevious Status: {old_status.value}\nReason: {data.reason or 'Not specified'}",
+                source_type="ticket",
+                source_id=ticket.id,
+                notification_type="ticket_reopened",
+                channel="in_app",
+                roles=["project_manager", "dispatcher"],
+                metadata={
+                    "ticket_id": str(ticket.id),
+                    "old_status": old_status.value,
+                    "new_status": ticket.status.value,
+                    "reopened_by": current_user.full_name,
+                    "reopen_reason": data.reason,
+                    "action_url": f"/tickets/{ticket.id}"
+                }
+            )
+            db.commit()
+
+            # Queue delivery (Tier 2 - Asynchronous)
+            if background_tasks and notification_ids:
+                NotificationDelivery.queue_bulk_delivery(
+                    background_tasks=background_tasks,
+                    notification_ids=notification_ids
                 )
         except Exception as e:
             logger.error(f"Failed to send ticket reopen notification: {str(e)}")

src/app/services/timesheet_realtime_service.py

@@ -0,0 +1,404 @@
+"""
+Timesheet Real-Time Update Service
+
+Handles real-time timesheet updates triggered by business events.
+Implements immutability rules, optimistic locking, and graceful degradation.
+
+Business Rules:
+- Timesheets are immutable (only update if work_date == today)
+- Multi-project support (one timesheet per user per project per day)
+- Optimistic locking prevents concurrent update conflicts
+- Failures don't block main operations (graceful degradation)
+"""
+from datetime import date, datetime
+from typing import Optional
+from uuid import UUID
+from sqlalchemy.orm import Session
+from sqlalchemy import func, case
+import logging
+
+from app.models.timesheet import Timesheet
+from app.models.ticket_assignment import TicketAssignment
+from app.models.ticket_expense import TicketExpense
+from app.models.ticket import Ticket
+from app.models.enums import TimesheetStatus
+
+logger = logging.getLogger(__name__)
+
+
+class TimesheetRealtimeService:
+    """
+    Service for real-time timesheet updates.
+
+    Key Features:
+    - Immutability enforcement (only update today's timesheets)
+    - Optimistic locking with retry
+    - Aggregation from source tables
+    - Sync tracking
+    """
+
+    def __init__(self, db: Session):
+        self.db = db
+
+    def update_timesheet_for_event(
+        self,
+        user_id: UUID,
+        project_id: UUID,
+        work_date: date,
+        event_type: str,
+        entity_type: str,
+        entity_id: UUID
+    ) -> Optional[UUID]:
+        """
+        Update timesheet for a business event.
+
+        Args:
+            user_id: User who performed the work
+            project_id: Project the work belongs to
+            work_date: Date of the work
+            event_type: Type of event (e.g., 'assignment_created', 'expense_approved')
+            entity_type: Type of entity ('ticket_assignment', 'ticket_expense', 'ticket')
+            entity_id: ID of the entity that triggered the update
+
+        Returns:
+            Timesheet ID if successful, None if failed or skipped
+        """
+        try:
+            # IMMUTABILITY RULE: Only update today's timesheet
+            if work_date < date.today():
+                logger.warning(
+                    f"Skipping timesheet update for past date: {work_date}. "
+                    f"Event: {event_type}, Entity: {entity_type}:{entity_id}"
+                )
+                return None
+
+            if work_date > date.today():
+                logger.warning(
+                    f"Skipping timesheet update for future date: {work_date}. "
+                    f"Event: {event_type}, Entity: {entity_type}:{entity_id}"
+                )
+                return None
+
+            # Aggregate metrics from source tables
+            ticket_metrics = self._aggregate_ticket_metrics(user_id, project_id, work_date)
+            expense_metrics = self._aggregate_expense_metrics(user_id, project_id, work_date)
+
+            # Merge all metrics
+            all_metrics = {**ticket_metrics, **expense_metrics}
+
+            # Upsert timesheet with optimistic locking
+            timesheet_id = self._upsert_timesheet_with_lock(
+                user_id=user_id,
+                project_id=project_id,
+                work_date=work_date,
+                metrics=all_metrics
+            )
+
+            if timesheet_id:
+                # Mark source entity as synced
+                self._mark_entity_synced(entity_type, entity_id)
+                logger.info(
+                    f"Timesheet {timesheet_id} updated for {event_type}. "
+                    f"Entity: {entity_type}:{entity_id}"
+                )
+            else:
+                logger.warning(
+                    f"Failed to update timesheet for {event_type}. "
+                    f"Entity: {entity_type}:{entity_id}"
+                )
+
+            return timesheet_id
+
+        except Exception as e:
+            logger.error(
+                f"Error updating timesheet for {event_type}: {e}",
+                exc_info=True
+            )
+            return None
+
+    def _aggregate_ticket_metrics(
+        self,
+        user_id: UUID,
+        project_id: UUID,
+        work_date: date
+    ) -> dict:
+        """
+        Aggregate ticket metrics for a specific day.
+
+        Uses MIN(journey_started_at) for check-in
+        Uses MAX(ended_at) for check-out
+
+        Returns:
+            Dict with ticket counts and check-in/out times
+        """
+        try:
+            # Query assignments for this day
+            query = self.db.query(
+                # Count by action type
+                func.count(
+                    case((TicketAssignment.action == 'assigned', 1))
+                ).label('tickets_assigned'),
+                func.count(
+                    case((TicketAssignment.action == 'completed', 1))
+                ).label('tickets_completed'),
+                func.count(
+                    case((TicketAssignment.action == 'rejected', 1))
+                ).label('tickets_rejected'),
+                func.count(
+                    case((TicketAssignment.action == 'dropped', 1))
+                ).label('tickets_cancelled'),
+
+
+            # Calculate hours worked
+            hours_worked = None
+            if result.check_in_time and result.check_out_time:
+                delta = result.check_out_time - result.check_in_time
+                hours_worked = round(delta.total_seconds() / 3600, 2)
+
+            return {
+                'tickets_assigned': result.tickets_assigned or 0,
+                'tickets_completed': result.tickets_completed or 0,
+                'tickets_rejected': result.tickets_rejected or 0,
+                'tickets_cancelled': result.tickets_cancelled or 0,
+                'tickets_rescheduled': 0,  # Not tracked yet
+                'check_in_time': result.check_in_time,
+                'check_out_time': result.check_out_time,
+                'hours_worked': hours_worked,
+                'status': TimesheetStatus.PRESENT  # Default to present if any activity
+            }
+
+        except Exception as e:
+            logger.error(f"Error aggregating ticket metrics: {e}", exc_info=True)
+            return {
+                'tickets_assigned': 0,
+                'tickets_completed': 0,
+                'tickets_rejected': 0,
+                'tickets_cancelled': 0,
+                'tickets_rescheduled': 0,
+                'check_in_time': None,
+                'check_out_time': None,
+                'hours_worked': None,
+                'status': TimesheetStatus.PRESENT
+            }
+
+    def _aggregate_expense_metrics(
+        self,
+        user_id: UUID,
+        project_id: UUID,
+        work_date: date
+    ) -> dict:
+        """
+        Aggregate expense metrics for a specific day.
+
+        Returns:
+            Dict with expense totals by approval status
+        """
+        try:
+            query = self.db.query(
+                func.count(TicketExpense.id).label('expense_claims_count'),
+                func.sum(TicketExpense.total_cost).label('total_expenses'),
+                func.sum(
+                    case((TicketExpense.is_approved == True, TicketExpense.total_cost), else_=0)
+                ).label('approved_expenses'),
+                func.sum(
+                    case((TicketExpense.is_approved.is_(None), TicketExpense.total_cost), else_=0)
+                ).label('pending_expenses'),
+                func.sum(
+                    case((TicketExpense.is_approved == False, TicketExpense.total_cost), else_=0)
+                ).label('rejected_expenses')
+            ).join(
+                Ticket, TicketExpense.ticket_id == Ticket.id
+            ).filter(
+                TicketExpense.incurred_by_user_id == user_id,
+                Ticket.project_id == project_id,
+                TicketExpense.expense_date == work_date,
+                TicketExpense.deleted_at.is_(None),
+                Ticket.deleted_at.is_(None)
+            )
+
+            result = query.first()
+
+            return {
+                'expense_claims_count': result.expense_claims_count or 0,
+                'total_expenses': float(result.total_expenses or 0),
+                'approved_expenses': float(result.approved_expenses or 0),
+                'pending_expenses': float(result.pending_expenses or 0),
+                'rejected_expenses': float(result.rejected_expenses or 0)
+            }
+
+        except Exception as e:
+            logger.error(f"Error aggregating expense metrics: {e}", exc_info=True)
+            return {
+                'expense_claims_count': 0,
+                'total_expenses': 0.0,
+                'approved_expenses': 0.0,
+                'pending_expenses': 0.0,
+                'rejected_expenses': 0.0
+            }
+
+    def _upsert_timesheet_with_lock(
+        self,
+        user_id: UUID,
+        project_id: UUID,
+        work_date: date,
+        metrics: dict,
+        max_retries: int = 3
+    ) -> Optional[UUID]:
+        """
+        Upsert timesheet with optimistic locking.
+        Retries on version conflict.
+
+        Args:
+            user_id: User ID
+            project_id: Project ID
+            work_date: Work date
+            metrics: Aggregated metrics to update
+            max_retries: Maximum number of retry attempts
+
+        Returns:
+            Timesheet ID if successful, None if failed
+        """
+        for attempt in range(max_retries):
+            try:
+                # Get existing timesheet
+                existing = self.db.query(Timesheet).filter(
+                    Timesheet.user_id == user_id,
+                    Timesheet.project_id == project_id,
+                    Timesheet.work_date == work_date,
+                    Timesheet.deleted_at.is_(None)
+                ).first()
+
+                if existing:
+                    # UPDATE with version check (optimistic locking)
+                    current_version = existing.version
+
+                    # Build update dict (exclude None values to preserve existing data)
+                    update_data = {k: v for k, v in metrics.items() if v is not None}
+
+                    result = self.db.query(Timesheet).filter(
+                        Timesheet.id == existing.id,
+                        Timesheet.version == current_version  # Optimistic lock
+                    ).update(update_data, synchronize_session=False)
+
+                    if result == 0:
+                        # Version conflict - another update happened
+                        logger.warning(
+                            f"Optimistic lock conflict on timesheet {existing.id}. "
+                            f"Retry {attempt + 1}/{max_retries}"
+                        )
+                        self.db.rollback()
+                        continue  # Retry
+
+                    self.db.commit()
+                    logger.debug(f"Updated timesheet {existing.id} (version {current_version} -> {current_version + 1})")
+                    return existing.id
+                else:
+                    # INSERT new timesheet
+                    new_timesheet = Timesheet(
+                        user_id=user_id,
+                        project_id=project_id,
+                        work_date=work_date,
+                        version=1,
+                        **metrics
+                    )
+                    self.db.add(new_timesheet)
+                    self.db.commit()
+                    self.db.refresh(new_timesheet)
+                    logger.debug(f"Created new timesheet {new_timesheet.id}")
+                    return new_timesheet.id
+
+            except Exception as e:
+                logger.error(f"Error upserting timesheet (attempt {attempt + 1}/{max_retries}): {e}")
+                self.db.rollback()
+                if attempt == max_retries - 1:
+                    return None
+                continue
+
+        return None
+
+    def _mark_entity_synced(
+        self,
+        entity_type: str,
+        entity_id: UUID
+    ) -> bool:
+        """
+        Mark source entity as synced to timesheet.
+
+        Args:
+            entity_type: Type of entity ('ticket_assignment', 'ticket_expense', 'ticket')
+            entity_id: ID of the entity
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            if entity_type == 'ticket_assignment':
+                self.db.query(TicketAssignment).filter(
+                    TicketAssignment.id == entity_id
+                ).update({
+                    'timesheet_synced': True,
+                    'timesheet_synced_at': func.now()
+                }, synchronize_session=False)
+            elif entity_type == 'ticket_expense':
+                self.db.query(TicketExpense).filter(
+                    TicketExpense.id == entity_id
+                ).update({
+                    'timesheet_synced': True,
+                    'timesheet_synced_at': func.now()
+                }, synchronize_session=False)
+            elif entity_type == 'ticket':
+                self.db.query(Ticket).filter(
+                    Ticket.id == entity_id
+                ).update({
+                    'timesheet_synced': True,
+                    'timesheet_synced_at': func.now()
+                }, synchronize_session=False)
+            else:
+                logger.warning(f"Unknown entity type: {entity_type}")
+                return False
+
+            self.db.commit()
+            return True
+        except Exception as e:
+            logger.error(f"Failed to mark {entity_type}:{entity_id} as synced: {e}")
+            self.db.rollback()
+            return False
+
+
+# Convenience function for use in API endpoints
+def update_timesheet_for_event(
+    db: Session,
+    user_id: UUID,
+    project_id: UUID,
+    work_date: date,
+    event_type: str,
+    entity_type: str,
+    entity_id: UUID
+) -> Optional[UUID]:
+    """
+    Convenience function to update timesheet for an event.
+
+    This is the main entry point for API endpoints.
+
+    Args:
+        db: Database session
+        user_id: User who performed the work
+        project_id: Project the work belongs to
+        work_date: Date of the work
+        event_type: Type of event (e.g., 'assignment_created')
+        entity_type: Type of entity ('ticket_assignment', 'ticket_expense', 'ticket')
+        entity_id: ID of the entity
+
+    Returns:
+        Timesheet ID if successful, None if failed
+    """
+    service = TimesheetRealtimeService(db)
+    return service.update_timesheet_for_event(
+        user_id=user_id,
+        project_id=project_id,
+        work_date=work_date,
+        event_type=event_type,
+        entity_type=entity_type,
+        entity_id=entity_id
+    )
+

supabase/migrations/20241212_realtime_timesheet_updates.sql

@@ -0,0 +1,162 @@
+-- =====================================================
+-- Real-Time Timesheet Updates - Database Migration
+-- Date: 2024-12-12
+-- Purpose: Add support for real-time timesheet updates
+-- =====================================================
+
+-- =====================================================
+-- PART 1: Add Version Column to Timesheets (Optimistic Locking)
+-- =====================================================
+
+-- Add version column for optimistic locking
+ALTER TABLE timesheets 
+ADD COLUMN IF NOT EXISTS version INTEGER NOT NULL DEFAULT 1;
+
+-- Create trigger function to auto-increment version on update
+CREATE OR REPLACE FUNCTION increment_timesheet_version()
+RETURNS TRIGGER AS $$
+BEGIN
+    -- Only increment if this is an UPDATE (not INSERT)
+    IF TG_OP = 'UPDATE' THEN
+        NEW.version = OLD.version + 1;
+    END IF;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Drop trigger if exists (for idempotency)
+DROP TRIGGER IF EXISTS trigger_increment_timesheet_version ON timesheets;
+
+-- Create trigger to auto-increment version on update
+CREATE TRIGGER trigger_increment_timesheet_version
+BEFORE UPDATE ON timesheets
+FOR EACH ROW
+EXECUTE FUNCTION increment_timesheet_version();
+
+-- Add index for version queries
+CREATE INDEX IF NOT EXISTS idx_timesheets_version ON timesheets(version);
+
+COMMENT ON COLUMN timesheets.version IS 'Optimistic locking version - auto-incremented on every update';
+
+-- =====================================================
+-- PART 2: Fix Unique Constraint (Multi-Project Support)
+-- =====================================================
+
+-- Drop old constraint (user_id, work_date)
+ALTER TABLE timesheets 
+DROP CONSTRAINT IF EXISTS uq_timesheets_user_date;
+
+-- Add new constraint (user_id, project_id, work_date)
+-- This allows one timesheet per user per project per day
+ALTER TABLE timesheets
+DROP CONSTRAINT IF EXISTS uq_timesheets_user_project_date;
+
+ALTER TABLE timesheets
+ADD CONSTRAINT uq_timesheets_user_project_date 
+UNIQUE (user_id, project_id, work_date);
+
+COMMENT ON CONSTRAINT uq_timesheets_user_project_date ON timesheets IS 'Allows multiple timesheets per day (one per project) - different projects pay different rates';
+
+-- =====================================================
+-- PART 3: Add Timesheet Sync Tracking to Source Tables
+-- =====================================================
+
+-- Add to ticket_assignments
+ALTER TABLE ticket_assignments
+ADD COLUMN IF NOT EXISTS timesheet_synced BOOLEAN NOT NULL DEFAULT FALSE,
+ADD COLUMN IF NOT EXISTS timesheet_synced_at TIMESTAMP WITH TIME ZONE;
+
+CREATE INDEX IF NOT EXISTS idx_ticket_assignments_timesheet_synced 
+ON ticket_assignments(timesheet_synced) 
+WHERE timesheet_synced = FALSE;
+
+COMMENT ON COLUMN ticket_assignments.timesheet_synced IS 'Tracks if this assignment has been synced to timesheets';
+COMMENT ON COLUMN ticket_assignments.timesheet_synced_at IS 'When this assignment was synced to timesheets';
+
+-- Add to ticket_expenses
+ALTER TABLE ticket_expenses
+ADD COLUMN IF NOT EXISTS timesheet_synced BOOLEAN NOT NULL DEFAULT FALSE,
+ADD COLUMN IF NOT EXISTS timesheet_synced_at TIMESTAMP WITH TIME ZONE;
+
+CREATE INDEX IF NOT EXISTS idx_ticket_expenses_timesheet_synced 
+ON ticket_expenses(timesheet_synced) 
+WHERE timesheet_synced = FALSE;
+
+COMMENT ON COLUMN ticket_expenses.timesheet_synced IS 'Tracks if this expense has been synced to timesheets';
+COMMENT ON COLUMN ticket_expenses.timesheet_synced_at IS 'When this expense was synced to timesheets';
+
+-- Add to tickets
+ALTER TABLE tickets
+ADD COLUMN IF NOT EXISTS timesheet_synced BOOLEAN NOT NULL DEFAULT FALSE,
+ADD COLUMN IF NOT EXISTS timesheet_synced_at TIMESTAMP WITH TIME ZONE;
+
+CREATE INDEX IF NOT EXISTS idx_tickets_timesheet_synced 
+ON tickets(timesheet_synced) 
+WHERE timesheet_synced = FALSE;
+
+COMMENT ON COLUMN tickets.timesheet_synced IS 'Tracks if this ticket completion has been synced to timesheets';
+COMMENT ON COLUMN tickets.timesheet_synced_at IS 'When this ticket was synced to timesheets';
+
+-- =====================================================
+-- PART 4: Add Missing Expense Columns to Timesheets
+-- =====================================================
+
+-- Check if expense columns exist, add if missing
+ALTER TABLE timesheets
+ADD COLUMN IF NOT EXISTS total_expenses NUMERIC(12, 2) DEFAULT 0 NOT NULL,
+ADD COLUMN IF NOT EXISTS approved_expenses NUMERIC(12, 2) DEFAULT 0 NOT NULL,
+ADD COLUMN IF NOT EXISTS pending_expenses NUMERIC(12, 2) DEFAULT 0 NOT NULL,
+ADD COLUMN IF NOT EXISTS rejected_expenses NUMERIC(12, 2) DEFAULT 0 NOT NULL,
+ADD COLUMN IF NOT EXISTS expense_claims_count INTEGER DEFAULT 0 NOT NULL;
+
+-- Add comments
+COMMENT ON COLUMN timesheets.total_expenses IS 'Total expense amount claimed this day';
+COMMENT ON COLUMN timesheets.approved_expenses IS 'Approved expense amount';
+COMMENT ON COLUMN timesheets.pending_expenses IS 'Pending approval amount';
+COMMENT ON COLUMN timesheets.rejected_expenses IS 'Rejected expense amount';
+COMMENT ON COLUMN timesheets.expense_claims_count IS 'Number of expense claims submitted';
+
+-- =====================================================
+-- PART 5: Add Indexes for Performance
+-- =====================================================
+
+-- Index for timesheet queries by user and date
+CREATE INDEX IF NOT EXISTS idx_timesheets_user_date ON timesheets(user_id, work_date);
+
+-- Index for timesheet queries by project and date
+CREATE INDEX IF NOT EXISTS idx_timesheets_project_date ON timesheets(project_id, work_date);
+
+-- Index for payroll queries (unpaid timesheets)
+CREATE INDEX IF NOT EXISTS idx_timesheets_payroll_pending 
+ON timesheets(is_payroll_generated, work_date) 
+WHERE is_payroll_generated = FALSE AND deleted_at IS NULL;
+
+-- =====================================================
+-- VERIFICATION QUERIES
+-- =====================================================
+
+-- Verify version column exists
+SELECT column_name, data_type, column_default 
+FROM information_schema.columns 
+WHERE table_name = 'timesheets' AND column_name = 'version';
+
+-- Verify unique constraint
+SELECT constraint_name, constraint_type 
+FROM information_schema.table_constraints 
+WHERE table_name = 'timesheets' AND constraint_name = 'uq_timesheets_user_project_date';
+
+-- Verify sync tracking columns on ticket_assignments
+SELECT column_name, data_type 
+FROM information_schema.columns 
+WHERE table_name = 'ticket_assignments' AND column_name IN ('timesheet_synced', 'timesheet_synced_at');
+
+-- Verify sync tracking columns on ticket_expenses
+SELECT column_name, data_type 
+FROM information_schema.columns 
+WHERE table_name = 'ticket_expenses' AND column_name IN ('timesheet_synced', 'timesheet_synced_at');
+
+-- Verify expense columns on timesheets
+SELECT column_name, data_type 
+FROM information_schema.columns 
+WHERE table_name = 'timesheets' AND column_name IN ('total_expenses', 'approved_expenses', 'pending_expenses', 'rejected_expenses', 'expense_claims_count');
+

supabase/migrations/20241212_simplify_compensation_structure.sql

@@ -0,0 +1,180 @@
+-- ============================================
+-- COMPENSATION STRUCTURE SIMPLIFICATION
+-- ============================================
+-- This migration simplifies the compensation structure for global use
+-- Removes redundant fields and creates a clean, simple system
+--
+-- Changes:
+-- 1. project_roles: Remove redundant fields, add new simplified fields
+-- 2. user_payroll: Remove redundant fields, add base_earnings
+-- 3. Update enums for compensation_type and add rate_period
+-- 4. Update constraints
+--
+-- Author: SwiftOps Team
+-- Date: 2024-12-12
+-- ============================================
+
+BEGIN;
+
+-- ============================================
+-- STEP 1: Update CompensationType Enum
+-- ============================================
+
+-- Rename old enum (it's called 'compensationtype' in Supabase, not 'compensation_type')
+ALTER TYPE compensationtype RENAME TO compensationtype_old;
+
+-- Create new enum with new values
+CREATE TYPE compensationtype AS ENUM (
+    'FIXED_RATE',              -- Time-based: hourly, daily, weekly, monthly
+    'PER_UNIT',                -- Work-based: per-ticket, per-job
+    'COMMISSION',              -- Percentage-based: sales commission
+    'FIXED_PLUS_COMMISSION'    -- Hybrid: base + commission
+);
+
+-- ============================================
+-- STEP 2: Create RatePeriod Enum
+-- ============================================
+
+CREATE TYPE rate_period AS ENUM (
+    'HOUR',
+    'DAY',
+    'WEEK',
+    'MONTH'
+);
+
+-- ============================================
+-- STEP 3: Update project_roles Table
+-- ============================================
+
+-- Add new simplified fields
+ALTER TABLE project_roles
+    ADD COLUMN base_rate NUMERIC(12, 2),
+    ADD COLUMN rate_period rate_period,
+    ADD COLUMN per_unit_rate NUMERIC(12, 2),
+    ADD COLUMN temp_compensation_type compensationtype;
+
+-- Migrate existing data to new structure
+-- This converts old compensation types to new ones
+-- Note: compensation_type column still exists with old enum type (compensationtype_old)
+UPDATE project_roles
+SET
+    temp_compensation_type = CASE
+        -- Map old per_day/per_week/per_ticket to new types
+        WHEN compensation_type::text = 'per_day' THEN 'FIXED_RATE'::compensationtype
+        WHEN compensation_type::text = 'per_week' THEN 'FIXED_RATE'::compensationtype
+        WHEN compensation_type::text = 'per_ticket' THEN 'PER_UNIT'::compensationtype
+
+        -- Map old legacy types
+        WHEN compensation_type::text = 'flat_rate' THEN 'FIXED_RATE'::compensationtype
+        WHEN compensation_type::text = 'hourly' THEN 'FIXED_RATE'::compensationtype
+        WHEN compensation_type::text = 'commission' THEN 'COMMISSION'::compensationtype
+        WHEN compensation_type::text = 'hybrid' THEN 'FIXED_PLUS_COMMISSION'::compensationtype
+
+        -- Default to FIXED_RATE for custom or unknown
+        ELSE 'FIXED_RATE'::compensationtype
+    END,
+
+    base_rate = CASE
+        WHEN compensation_type::text = 'per_day' THEN daily_rate
+        WHEN compensation_type::text = 'per_week' THEN weekly_rate
+        WHEN compensation_type::text = 'flat_rate' THEN flat_rate_amount
+        WHEN compensation_type::text = 'hourly' THEN hourly_rate
+        WHEN compensation_type::text = 'hybrid' THEN base_amount
+        ELSE NULL
+    END,
+
+    rate_period = CASE
+        WHEN compensation_type::text = 'per_day' THEN 'DAY'::rate_period
+        WHEN compensation_type::text = 'per_week' THEN 'WEEK'::rate_period
+        WHEN compensation_type::text = 'flat_rate' THEN 'WEEK'::rate_period
+        WHEN compensation_type::text = 'hourly' THEN 'HOUR'::rate_period
+        WHEN compensation_type::text = 'hybrid' THEN 'DAY'::rate_period
+        ELSE NULL
+    END,
+
+    per_unit_rate = CASE
+        WHEN compensation_type::text = 'per_ticket' THEN per_ticket_rate
+        ELSE NULL
+    END;
+
+-- Drop old compensation_type column and rename temp
+ALTER TABLE project_roles DROP COLUMN compensation_type;
+ALTER TABLE project_roles RENAME COLUMN temp_compensation_type TO compensation_type;
+ALTER TABLE project_roles ALTER COLUMN compensation_type SET NOT NULL;
+
+-- Drop old redundant fields
+ALTER TABLE project_roles
+    DROP COLUMN IF EXISTS flat_rate_amount,
+    DROP COLUMN IF EXISTS base_amount,
+    DROP COLUMN IF EXISTS bonus_percentage,
+    DROP COLUMN IF EXISTS hourly_rate,
+    DROP COLUMN IF EXISTS daily_rate,
+    DROP COLUMN IF EXISTS weekly_rate,
+    DROP COLUMN IF EXISTS per_ticket_rate;
+
+-- Add check constraints for field usage
+ALTER TABLE project_roles
+    ADD CONSTRAINT chk_fixed_rate_fields 
+        CHECK (
+            compensation_type != 'FIXED_RATE' OR 
+            (base_rate IS NOT NULL AND base_rate >= 0 AND rate_period IS NOT NULL)
+        ),
+    ADD CONSTRAINT chk_per_unit_fields
+        CHECK (
+            compensation_type != 'PER_UNIT' OR 
+            (per_unit_rate IS NOT NULL AND per_unit_rate >= 0)
+        ),
+    ADD CONSTRAINT chk_commission_fields
+        CHECK (
+            compensation_type != 'COMMISSION' OR 
+            (commission_percentage IS NOT NULL AND commission_percentage >= 0 AND commission_percentage <= 100)
+        ),
+    ADD CONSTRAINT chk_fixed_plus_commission_fields
+        CHECK (
+            compensation_type != 'FIXED_PLUS_COMMISSION' OR 
+            (base_rate IS NOT NULL AND base_rate >= 0 AND rate_period IS NOT NULL AND 
+             commission_percentage IS NOT NULL AND commission_percentage >= 0 AND commission_percentage <= 100)
+        );
+
+-- Drop old enum type
+DROP TYPE compensationtype_old;
+
+-- ============================================
+-- STEP 4: Update user_payroll Table
+-- ============================================
+
+-- Add new base_earnings field
+ALTER TABLE user_payroll
+    ADD COLUMN base_earnings NUMERIC(12, 2) DEFAULT 0 NOT NULL;
+
+-- Migrate existing data: base_earnings = flat_rate_amount + ticket_earnings
+UPDATE user_payroll
+SET base_earnings = COALESCE(flat_rate_amount, 0) + COALESCE(ticket_earnings, 0);
+
+-- Drop old redundant fields
+ALTER TABLE user_payroll
+    DROP COLUMN IF EXISTS hours_worked,
+    DROP COLUMN IF EXISTS flat_rate_amount,
+    DROP COLUMN IF EXISTS ticket_earnings;
+
+-- Drop old constraints that referenced removed columns
+ALTER TABLE user_payroll
+    DROP CONSTRAINT IF EXISTS chk_positive_hours,
+    DROP CONSTRAINT IF EXISTS chk_positive_flat_rate,
+    DROP CONSTRAINT IF EXISTS chk_positive_ticket_earnings;
+
+-- Add new constraint for base_earnings
+ALTER TABLE user_payroll
+    ADD CONSTRAINT chk_positive_base_earnings CHECK (base_earnings >= 0);
+
+COMMIT;
+
+-- ============================================
+-- VERIFICATION QUERIES
+-- ============================================
+-- Run these after migration to verify success:
+--
+-- SELECT compensation_type, COUNT(*) FROM project_roles GROUP BY compensation_type;
+-- SELECT * FROM project_roles LIMIT 5;
+-- SELECT * FROM user_payroll LIMIT 5;
+