Skip to main content

​
Notification System Architecture

In-app notifications are easy to build badly. The hard part is signal quality.

​
Scope model in your stack

Your frontend notification APIs and hooks support scope filtering with:
  • user
  • organization
  • workspace
  • broader filtered views (all, current) in hook usage

​
Scope design guidance

  1. Use user for personal/account/security changes.
  2. Use organization for team-level operational events.
  3. Use workspace for project-level activity.
  4. Avoid broadcasting org-wide when workspace scope is enough.

​
Severity usage

Keep severity semantic:
  • info: neutral updates
  • success: completed actions
  • warning: attention required soon
  • error: action required now
Do not use severity as category taxonomy.

​
Lifecycle model

  1. Create notification.
  2. Deliver to inbox.
  3. Mark read/unread.
  4. Star/archive as needed.
  5. Expire when stale.
  1. React Router useNotifications
  2. React Router useNotificationStream
  3. Frontend API Notifications Reference
  4. Backend API Notifications Reference

​
Go-live checklist

  1. Scope and severity conventions are documented.
  2. Inbox read/archive/star flows are tested.
  3. Realtime reconnection behavior is verified.
  4. Noisy template monitoring is in place.
  5. Expiry strategy is applied for stale notifications.