MCM-14 — Real-Time In-App Notification Bell

← Back to Notification System overview

As an Enterprise Admin,
I want a notification bell in the top navigation bar that shows unread alerts in real time,
so that I am immediately aware of important events without leaving the current page.

Acceptance Criteria

• A bell icon in the global nav bar shows a badge count of unread notifications.
• Clicking the bell opens a notification drawer listing the 50 most recent notifications for the current user, sorted newest-first.
• Each notification entry shows: icon (by category), title, short description, relative timestamp ("2 minutes ago"), and read/unread state.
• Unread notifications are visually distinguished (bold title, accent dot).
• Clicking a notification marks it as read and navigates to the relevant resource page (deep link).
• A "Mark all as read" action clears the badge and marks all notifications read.
• The badge count and new entries update in real time via WebSocket — no page refresh needed (see MCM-15).
• The drawer supports infinite scroll or "Load more" to access older notifications beyond the initial 50.

---

Technical Design

The bell reads from two sources: a real-time push for new/unread state over the WebSocket stream (see MCM-15 — WebSocket Real-Time Delivery) layered on top of a paginated history query, GET /api/notifications?limit=50&before=<cursor>, for everything older than what's already in memory. Each notification is persisted server-side (category, severity, title, description, deep link, per-user read state) with a 7-day retention window, so the drawer's history is purely a query over existing records, not a new store. Marking notifications read (POST /api/notifications/{id}/read, or POST /api/notifications/mark-all-read) is a simple state update on those same records.

---

UI / Frontend Changes

• Global top navigation bar gains a bell icon with an unread-count badge, visible on every authenticated page.
• New notification drawer component, opened from the bell, listing the 50 most recent notifications (icon by category, title, short description, relative timestamp, read/unread styling).
• Unread entries are visually distinguished (bold title, accent dot); a "Mark all as read" action clears the badge.
• Clicking an entry marks it read and deep-links to the relevant resource page.
• Drawer supports infinite scroll / "Load more" for history beyond the initial 50, backed by the paginated GET /api/notifications endpoint.
• Badge count and new entries update live via the WebSocket stream with no page refresh.