Notifications Module Specification

1. Purpose & Overview

notifications

2. Responsibilities

• Maintain

  Notification

  domain model.
• Provide unread counter APIs (

  GET /api/notifications/unread-count/

  ).
• Broadcast realtime alert updates via WebSockets.

3. Directory Structure

services/api/notifications/
├── admin.py
├── apps.py
├── migrations/
├── models.py
├── serializers.py
└── views.py

4. Models & Database Schemas

class Notification(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    tenant = models.ForeignKey('tenants.Tenant', on_delete=models.CASCADE)
    user = models.ForeignKey('users.User', on_delete=models.CASCADE, null=True, blank=True)
    title = models.CharField(max_length=255)
    message = models.TextField()
    is_read = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

5. Services & Business Logic

• NotificationService.create_notification(...)

  : Creates record and updates unread badge counter.

6. Serializers & Data Transfer Objects

• NotificationSerializer

  : Serializes notification items and read flags.

7. Views & API Endpoints

• GET /api/notifications/

  : List user notifications.

• GET /api/notifications/unread-count/

  : Returns

  { "unread_count": 11 }

  .

• POST /api/notifications/{id}/mark-read/

  : Marks notification as read.

8. Permissions & Role Rules

• IsAuthenticated

  : Scoped to active tenant and current user.

9. Signals & Event Listeners

• Triggered when campaigns complete, fail, or new system alerts occur.

10. Background Tasks & Celery Jobs

• Bulk notification cleanup executed periodically.

11. Data Flow & External Dependencies

• Integrates with

  inbox

  module to publish realtime unread badge frames to agent WebSockets.

12. Business Rules & Validations

• Notifications belong to either a specific user or all operators within a tenant.

13. Sequence Diagram (Mermaid)

14. Known Limitations & Technical Debt

• Local memory cache for unread counters in dev mode.

15. Future Improvements

• Add Push Notification support (Web Push / FCM) for mobile browser support.