# Notifications System

## Overview

In-app notifications are stored in the `Notification` table and fetched by role. Super admins, DB admins, and account admins all receive the same notification feed.

---

## Notification Model

```
Notification
  ├── id
  ├── recipientRole               -- Which role this notification targets (Role enum)
  ├── type                        -- e.g. "NEW_REGISTRATION", "PAYMENT_RECEIVED"
  ├── title
  ├── message
  ├── isRead / readAt
  ├── transactionId               -- Optional link to Transaction
  ├── registrationId              -- Optional link to Registration
  ├── actorUserId                 -- Optional link to User who triggered the action
  ├── metadata (JSON)             -- Arbitrary extra context
  ├── createdAt
  └── updatedAt
```

Indexed on `(recipientRole, isRead, createdAt)` and `(recipientRole, createdAt)`.

---

## API

`GET /api/notifications?page=1&limit=15&isRead=all`

Query params:
- `page` — page number (1-based)
- `limit` — records per page
- `isRead` — `all` | `true` | `false`

---

## Authorization

- `SUPER_ADMIN`, `DB_ADMIN`, `ACCOUNT_ADMIN` all receive super-admin-level notifications.
- `PRADESH_ADMIN` and `MANDAL_ADMIN` receive their scoped notifications.
- 403 returned for `DB_ADMIN` / `ACCOUNT_ADMIN` indicates stale backend code or the backend process was not restarted after deploy.

---

## Known Pitfalls

### Enum field with null in where-clause
Querying `recipientRole` with `null` in a Prisma `where` clause throws a runtime 500 in this backend. Always provide a valid `Role` enum value.

```js
// WRONG — will throw 500
where: { recipientRole: null }

// CORRECT
where: { recipientRole: "SUPER_ADMIN" }
```

### UI: Error vs Empty State
The notifications UI must **not** treat API errors (401/403/500) as empty state. Show explicit error text for these cases. A "No notifications" message should only appear when the API returns 200 with zero records.

---

## Notification Service

`src/services/notificationService.js` handles:
- Creating new notification records
- Slack notifications (via `slackService.js`)
- WhatsApp template messages (via `whatsappTemplateService.js`)

All three channels can be triggered from a single service call depending on the notification type.