Notifications

Responsibility

WhatsApp, Email, and SMS notifications. This support domain provides a unified notification delivery channel consumed by Workforce Management, Safety & Compliance, and Worker Monitoring.

Real-time in-app notifications are delivered via Server-Sent Events (SSE); external notifications go out via Email and SMS (Twilio).

Key Entities

Notification Records (persisted in PostgreSQL)
SSE Streams (per user)
Email Messages
SMS Messages

Tech Stack

The Notifications context is implemented within the Angelis Backend FastAPI service as a shared singleton:

Components:
    - NotificationService: Singleton service managing SSE connections
    - NotificationRepository: Database persistence (PostgreSQL)
    - SSE Endpoints: /notifications/stream, /notifications/adminstream

Features:
    - Real-time delivery via Server-Sent Events (SSE)
    - Persistent storage in PostgreSQL
    - Expired link filtering
    - Pagination support
    - User type separation (PROFILE vs INTERNAL_USER)

Flow:
    1. User connects to SSE endpoint
    2. Service creates asyncio.Queue for user
    3. Notifications sent to queue
    4. SSE stream delivers to frontend
    5. Notifications also persisted to database
    6. Frontend can retrieve historical notifications

External channels:

Email — via email_service
SMS — via sms_service (Twilio)

Integrations

Workforce Management — triggers notifications for key admin events
Safety & Compliance — Checkingmate Backend sends notifications via the Notifications API
Worker Monitoring — sends MIA alerts and presence events as notifications
Analytics & Reporting — notifies users when their generated reports are ready for download