Initial commit: nick docs
This commit is contained in:
moojttaba
155
04 - Flows/Notification Flow.md
Normal file
155
04 - Flows/Notification Flow.md
Normal file
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: Notification Flow
|
||||
tags: [flow, notification, socket-io, email]
|
||||
related_models: ["[[Notification]]", "[[User]]"]
|
||||
related_apis: ["GET /api/notifications", "PATCH /api/notifications/:id/read", "POST /api/notifications/read-all", "DELETE /api/notifications/:id"]
|
||||
---
|
||||
|
||||
# Notification Flow
|
||||
|
||||
Cross-cutting flow that powers the bell icon, toast pop-ups, badge counters, and (optionally) email digests. Notifications are created by many services and travel to the user via both **MongoDB persistence** and **Socket.IO push**.
|
||||
|
||||
## Trigger sources
|
||||
|
||||
- **Purchase request lifecycle** — created, status changed, cancelled (`PurchaseRequestService`).
|
||||
- **Offer lifecycle** — new offer, accepted, rejected, withdrawn (`SellerOfferService`).
|
||||
- **Payment lifecycle** — confirmed, refunded, payout sent (`shkeeperWebhook`, `PurchaseRequestService.notifyPaymentConfirmed`).
|
||||
- **Chat** — `chat-notification` events (see [[Chat Flow]]).
|
||||
- **Dispute** — created, assigned, resolved (TODO in `DisputeService`; the chat itself notifies).
|
||||
- **Delivery** — code generated, delivery confirmed (`DeliveryService`).
|
||||
- **Referral** — sign-up via referral code (`AuthController.verifyEmailWithCode`, `googleSignUp`).
|
||||
- **Points / levels** — `level-up` event when crossing a tier (`PointsService.addPoints:91-99`).
|
||||
- **Admin actions** — e.g. dispute resolution, manual payouts.
|
||||
|
||||
## Actors
|
||||
|
||||
- **System** — the various services calling `NotificationService.createNotification`.
|
||||
- **User** — the recipient.
|
||||
- **Frontend** — bell-icon dropdown and toast subscribers in `frontend/src/layouts/components/notifications-drawer/` and the global socket provider.
|
||||
- **Backend** — `NotificationService` (`backend/src/services/notification/NotificationService.ts`), routes at `/api/notifications`.
|
||||
- **MongoDB** — `notifications` collection (one document per notification).
|
||||
- **Socket.IO** — emits `new-notification` to `user-{userId}`.
|
||||
- **Email** (optional) — periodic digest worker (not implemented today; planned).
|
||||
|
||||
## Step-by-step narrative
|
||||
|
||||
### Creating a notification
|
||||
|
||||
1. Any service builds a `NotificationCreateData` object:
|
||||
```
|
||||
{
|
||||
userId, title, message,
|
||||
type: 'info' | 'success' | 'warning' | 'error',
|
||||
category: 'purchase_request' | 'offer' | 'payment' | 'delivery' | 'system',
|
||||
relatedId?, metadata?, actionUrl?
|
||||
}
|
||||
```
|
||||
2. Calls `await notificationService.createNotification(data)`.
|
||||
3. `NotificationService.createNotification` (`NotificationService.ts:18-37`):
|
||||
- `Notification.create({ ...data, isRead: false, createdAt: now })`.
|
||||
- Calls `this.emitRealTimeNotification(userId, saved)` which `global.io.to('user-${userId}').emit('new-notification', payload)`.
|
||||
4. The notification is persisted and pushed simultaneously.
|
||||
|
||||
### Frontend reception
|
||||
|
||||
5. The frontend's global Socket.IO provider listens for `new-notification` events on its `user-{me}` room (joined on app mount via `socket.emit('join-user-room', userId)`).
|
||||
6. On event: increment the bell-icon badge, optionally show a toast (`notistack`), and prepend the entry into the cached notifications list (React Query cache).
|
||||
7. The bell-icon dropdown also fetches `GET /api/notifications?page=1&limit=20` for paginated history.
|
||||
|
||||
### Reading
|
||||
|
||||
8. User opens the bell-icon dropdown — frontend calls `POST /api/notifications/mark-read` for each viewed entry (or `POST /api/notifications/read-all`).
|
||||
9. `NotificationService.markAsRead(notificationId, userId)` (`NotificationService.ts:74-90`):
|
||||
- `Notification.findOneAndUpdate({ _id, userId }, { isRead: true, readAt: now })`.
|
||||
- Emits `notification-read` (or recomputes unread count) so other open tabs sync.
|
||||
|
||||
### Preferences
|
||||
|
||||
- `User.preferences.notifications` (in the User schema) can hold per-category opt-outs (`emailNotifications`, `pushNotifications`, etc.). The current implementation does not enforce preferences at send-time — all enabled notifications fire. Add a check in `createNotification` to short-circuit when the user has opted out of a category.
|
||||
|
||||
### Email digest (planned)
|
||||
|
||||
- A scheduled worker should `Notification.find({ userId, emailDigested: false, createdAt: { $gte: yesterday } })`, batch by user, render a digest email via `emailService`, mark `emailDigested: true`. Not implemented today.
|
||||
|
||||
## Sequence diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant Svc as Originating Service<br/>(SellerOfferService / Webhook / ...)
|
||||
participant NS as NotificationService
|
||||
participant DB as MongoDB
|
||||
participant IO as Socket.IO
|
||||
participant FE as Frontend
|
||||
actor U as User
|
||||
|
||||
Svc->>NS: createNotification({userId, title, message, ...})
|
||||
NS->>DB: Notification.create
|
||||
NS->>IO: emit user-{userId} 'new-notification'
|
||||
IO-->>FE: 'new-notification' payload
|
||||
FE-->>U: badge++, toast, prepend to list
|
||||
|
||||
U->>FE: open bell dropdown
|
||||
FE->>NS: GET /api/notifications?page=1&limit=20
|
||||
NS->>DB: Notification.find({userId}).sort({createdAt:-1})
|
||||
NS-->>FE: { notifications, total, unreadCount }
|
||||
|
||||
U->>FE: click notification
|
||||
FE->>NS: PATCH /api/notifications/{id}/read
|
||||
NS->>DB: Notification.findOneAndUpdate(isRead:true)
|
||||
FE-->>U: badge--, mark item as read
|
||||
FE-->>U: navigate to notification.actionUrl
|
||||
```
|
||||
|
||||
## API calls
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/notifications` | Paginated list with `unreadCount` |
|
||||
| `GET` | `/api/notifications/unread-count` | Just the unread count for badge |
|
||||
| `PATCH` | `/api/notifications/:id/read` | Mark single notification read |
|
||||
| `POST` | `/api/notifications/read-all` | Mark all read |
|
||||
| `DELETE` | `/api/notifications/:id` | Remove from list |
|
||||
|
||||
## Database writes
|
||||
|
||||
- **`notifications`** — insert on create, update on read, delete on remove.
|
||||
|
||||
## Socket events emitted
|
||||
|
||||
- **`new-notification`** → `user-{userId}`. Payload includes the full notification document (so the frontend doesn't need to re-fetch).
|
||||
- **`level-up`** → `user-{userId}` from `PointsService.addPoints`.
|
||||
- **`referral-signup`** → `user-{referrerId}` from auth verify.
|
||||
- **`chat-notification`** → `user-{participantId}` from `ChatService.sendMessage` (these are not stored in the `notifications` collection — they live alongside but drive only the chat-list badge).
|
||||
|
||||
## Side effects
|
||||
|
||||
- Bell badge count is derived from `unreadCount` returned by the GET endpoint or computed client-side as items arrive.
|
||||
- Notification actions deep-link via `actionUrl` (e.g. `/dashboard/buyer/requests/{id}`).
|
||||
- Sentry breadcrumbs capture failed notification creations.
|
||||
|
||||
## Error / edge cases
|
||||
|
||||
- **User offline** → notification is persisted in MongoDB; the user sees it when they next sign in. The socket emit is lossy (no replay).
|
||||
- **Multiple tabs / devices** → the same `user-{id}` room receives the event in each socket; all tabs update.
|
||||
- **Disabled categories** (planned) → service should early-return without DB write if the user has opted out, otherwise persist but don't push (so it shows in history but not as a toast).
|
||||
- **High volume** (e.g. fan-out to thousands of sellers) → today every notification is a separate Mongo insert + socket emit. For mass announcements, consider `insertMany` + per-room broadcast. The 50ms stagger in [[Purchase Request Flow]] mitigates the worst case.
|
||||
- **Stale unread count** → if the frontend trusts a stale React Query cache, it can show wrong numbers; always reconcile against `unread-count` on bell-icon open.
|
||||
|
||||
> [!tip] Always set `actionUrl`
|
||||
> Every notification should have a deep-link target. Notifications without `actionUrl` lead to dead clicks. The factory methods in `NotificationService` (e.g. `notifyNewOfferReceived`) already enforce this — keep the pattern when adding new helpers.
|
||||
|
||||
## Linked flows
|
||||
|
||||
- Every other flow in this folder emits notifications via this service.
|
||||
- [[Chat Flow]] — separate `chat-notification` socket channel for chat badges.
|
||||
|
||||
## Source files
|
||||
|
||||
- Backend: `backend/src/services/notification/NotificationService.ts`
|
||||
- Backend: `backend/src/services/notification/notificationController.ts`
|
||||
- Backend: `backend/src/services/notification/notificationControllerRoutes.ts`
|
||||
- Backend: `backend/src/services/notification/routes.ts`
|
||||
- Backend: `backend/src/models/Notification.ts`
|
||||
- Frontend: `frontend/src/layouts/components/notifications-drawer/`
|
||||
- Frontend: socket provider (joins `user-{id}` and listens for `new-notification`)
|
||||
Reference in New Issue
Block a user