> ## Documentation Index
> Fetch the complete documentation index at: https://system.muzemus.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

> In-app and email notification system for order lifecycle events

MUZE notifies users through two channels: **in-app notifications** and **email**. A WHATSAPP channel value exists in the schema but is reserved for future use. Notification dispatch runs in the background and never blocks or fails the primary operation — the order or status transition response returns as soon as the database transaction commits, while notifications and emails (including Sales Order PDF generation) are dispatched out-of-band.

## In-app notifications

In-app notifications are database records (`Notification` model) rendered by the notification bell in the navigation bar. The bell:

* Polls for unread notifications every 30 seconds
* Shows the unread count as a badge
* Pauses polling when the browser tab is hidden

The Notifications page lets users filter by read/unread, mark all as read, and delete notifications.

## Email notifications

Transactional emails are sent via Brevo in production (HTTPS REST API) and nodemailer SMTP (e.g. Gmail) in development. Every attempt is recorded in the `EmailLog` table with status and error details.

| Email                    | Recipients                     | Trigger                                                          |
| ------------------------ | ------------------------------ | ---------------------------------------------------------------- |
| "Requires your approval" | HR users for the client        | Order submitted with approval required; Sales Order PDF attached |
| "New order submitted"    | Administrators                 | Informational copy of any submission, with Sales Order PDF       |
| Order status update      | Submitter and associated staff | Every status change, including rejection reasons                 |
| Staff invite             | New staff members              | Account creation                                                 |
| Password reset           | Requesting user                | Forgot-password request                                          |

## Notification service

**File:** `backend/src/notifications/notifications.service.ts`

```mermaid theme={null}
sequenceDiagram
    participant Event as Business event
    participant Service as NotificationsService
    participant DB as Notification / EmailLog
    participant SMTP as Brevo / SMTP

    Event->>Service: Order created / approved / rejected / status changed
    Service->>DB: Create in-app notification
    Service->>DB: Create EmailLog record
    Service->>SMTP: sendEmail(to, subject, html)
    SMTP-->>Service: Delivery result
    Service->>DB: Update EmailLog status
```

## Resilience

* Send failures are logged in `EmailLog` but never block the order transition
* No retry queue for failed emails
* No delivery-status webhooks
* When orders are deleted, related notifications are cleaned up in the same transaction