docs/agent/thoughts/backend.md

Notification System Design Plan Current State Analysis ✅ Already Built:

Database schema with all necessary fields Notification model with polymorphic support (source_type, source_id) NotificationService with email/WhatsApp/in-app support Basic CRUD operations (create, read, mark as read, delete) User notification queries with filters ❌ Missing:

Integration hooks - No automatic notifications on events Event triggers - Not connected to business logic API endpoints - No REST API for frontend Real-time delivery - No WebSocket/SSE for live updates Notification Strategy

1. Notification Types & Triggers A. Ticket Lifecycle Notifications

✉️ Ticket Assigned → Field agent gets notified ✉️ Ticket Status Changed → PM/Dispatcher notified (in_progress, completed, cancelled) ✉️ Ticket Overdue → PM/Dispatcher gets daily reminder ✉️ Ticket Completed → PM gets completion notification ✉️ Assignment Rejected → Dispatcher notified when agent rejects B. Sales Order Notifications

✉️ Bulk Import Complete → User who uploaded gets summary (success/failed counts) ✉️ Bulk Promote Complete → User gets ticket creation summary ✉️ Sales Order Assigned to Region → Regional manager notified C. Expense Notifications

✉️ Expense Submitted → PM/Dispatcher notified for approval ✉️ Expense Approved → Agent notified ✉️ Expense Rejected → Agent notified with reason ✉️ Expense Paid → Agent notified D. Team & Project Notifications

✉️ User Invited to Project → Invitee gets invitation ✉️ User Added to Team → User notified of project assignment ✉️ Project Status Changed → Team members notified E. Financial Notifications

✉️ Payroll Generated → Worker notified ✉️ Payment Processed → Recipient notified ✉️ Invoice Created → Contractor notified F. System Notifications

✉️ Daily Summary → PM gets daily stats (tickets completed, pending, overdue) ✉️ Weekly Report → Platform admin gets usage metrics ✉️ SLA Violations → PM/Client admin notified 2. Notification Channels by Role | Role | In-App | WhatsApp | Email | SMS | |------|--------|----------|-------|-----| | Field Agent | ✓ | ✓ (urgent) | ✗ | ✗ | | Dispatcher | ✓ | ✓ | ✓ | ✗ | | PM | ✓ | ✗ | ✓ | ✗ | | Sales Manager | ✓ | ✗ | ✓ | ✗ | | Client Admin | ✓ | ✗ | ✓ | ✗ | | Platform Admin | ✓ | ✗ | ✓ | ✗ |

3. Implementation Approach Phase 1: Core Integration (Week 1)

Create notification helper functions in services Add notification triggers to existing services: ticket_service.py → ticket lifecycle events ticket_assignment_service.py → assignment events sales_order_service.py → bulk operation results ticket_expense_service.py → expense approval flow Phase 2: API Endpoints (Week 1) 3. Create /api/v1/notifications endpoints:

GET /notifications - List user notifications GET /notifications/stats - Get unread count PUT /notifications/{id}/read - Mark as read PUT /notifications/mark-all-read - Mark all as read DELETE /notifications/{id} - Delete notification Phase 3: Real-time (Week 2) 4. Add WebSocket/SSE for live notifications (optional) 5. Add background job for email/WhatsApp delivery

Phase 4: Advanced Features (Week 2) 6. User notification preferences (which events to receive) 7. Notification templates 8. Digest notifications (daily/weekly summaries)

4. Code Structure src/app/ ├── services/ │ ├── notification_service.py (✅ exists) │ └── notification_helper.py (NEW - convenience functions) ├── api/v1/ │ └── notifications.py (NEW - REST endpoints) ├── schemas/ │ └── notification.py (check if exists, add if needed) └── templates/ ├── emails/ │ ├── ticket_assigned.html │ ├── expense_approved.html │ └── bulk_import_complete.html └── whatsapp/ ├── ticket_assigned.txt └── expense_approved.txt
5. Example Integration Points A. Ticket Assignment (in ticket_assignment_service.py)

After assigning ticket

await NotificationHelper.notify_ticket_assigned( db=db, ticket=ticket, agent=agent, assigned_by=current_user ) B. Bulk Import Complete (in sales_order_service.py)

After bulk import

await NotificationHelper.notify_bulk_import_complete( db=db, user_id=current_user.id, total=result.total, successful=result.successful, failed=result.failed ) C. Expense Approved (in ticket_expense_service.py)

After approval

await NotificationHelper.notify_expense_approved( db=db, expense=expense, approved_by=current_user ) 6. Notification Priority Levels 🔴 Urgent (WhatsApp + In-App): Ticket assigned, SLA violation 🟡 High (Email + In-App): Expense needs approval, ticket overdue 🟢 Normal (In-App only): Status updates, bulk operation results ⚪ Low (In-App only): Daily summaries, informational Next Steps - What Should We Build First? I recommend this order:

Create notification_helper.py - Convenience functions for common notifications Add triggers to ticket assignment - Most critical for field operations Add bulk operation notifications - Your immediate need (sales order imports) Create API endpoints - So frontend can display notifications Add expense notifications - Complete the approval workflow Should I start implementing? Which part would you like me to build first? I suggest starting with:

Notification helper functions Bulk operation notifications (sales orders, ticket creation) Basic API endpoints This will give you immediate value and we can expand from there. What do you think?