Notification System (e.g. Facebook Notifications)

<App>
├── <Header>
│   └── <NotificationBell>              // Client: badge counter, opens panel
│       └── <UnreadBadge />             // Client: animated counter
├── <NotificationPanel>                 // Client: slide-over drawer
│   ├── <NotificationFilterBar />       // Client: All | Unread | Mentions
│   ├── <NotificationFeed>             // Client: virtualized list
│   │   ├── <NotificationGroup />       // Client: grouped items
│   │   │   └── <NotificationItem />   // Client: single notification
│   │   └── <NotificationItem />       // Client: ungrouped item
│   └── <MarkAllReadButton />          // Client: bulk action
├── <ToastContainer>                   // Client: positioned fixed
│   └── <ToastItem />                  // Client: individual toast
├── <NotificationPreferences>          // Route: /settings/notifications
│   ├── <CategoryToggleGrid />         // Client: per-category controls
│   ├── <ChannelToggleGrid />          // Client: per-channel controls
│   └── <QuietHoursConfig />           // Client: time picker
└── <ServiceWorkerRegistrar />         // Client: push subscription mgmt

/** Core notification entity as received from API */
interface Notification {
  id: string; // UUID v7 (time-sortable)
  type: NotificationType; // Discriminated union for rendering
  category: NotificationCategory; // For preference matching
  actorIds: string[]; // Users who triggered (supports grouping)
  primaryActor: ActorSummary; // First/most-recent actor for display
  additionalActorCount: number; // "and 5 others" — server-computed
  targetEntity: EntityReference; // What was acted upon
  message: NotificationMessage; // Structured message with template
  deepLink: string; // Relative URL for navigation
  imageUrl?: string; // Rich notification image
  actions?: NotificationAction[]; // CTA buttons (max 2)
  progress?: ProgressIndicator; // For long-running operations
  groupKey?: string; // Server-assigned grouping key
  isRead: boolean; // Read state
  isArchived: boolean; // Soft-deleted from feed
  createdAt: string; // ISO 8601 timestamp
  expiresAt?: string; // Auto-archive after this time
  channels: DeliveryChannel[]; // Which channels delivered this
}

type NotificationType =
  | "mention"
  | "reaction"
  | "comment"
  | "reply"
  | "share"
  | "follow"
  | "assignment"
  | "status_change"
  | "system"
  | "reminder";

type NotificationCategory =
  | "social" // reactions, follows, shares
  | "discussion" // comments, replies, mentions
  | "workflow" // assignments, status changes
  | "system" // platform announcements
  | "marketing"; // product updates (lowest priority)

type DeliveryChannel = "in_app" | "push" | "email" | "sms";

interface ActorSummary {
  id: string;
  displayName: string;
  avatarUrl: string;
  isVerified: boolean;
}

interface EntityReference {
  id: string;
  type: "post" | "comment" | "project" | "task" | "document" | "channel";
  title: string; // Truncated to 80 chars
  parentId?: string; // For nested entities (comment → post)
}

interface NotificationMessage {
  template: string; // "{{actor}} liked your {{entity}}"
  plainText: string; // Pre-rendered server-side for SR
  richText?: string; // HTML-safe markup (sanitized server-side)
}

interface NotificationAction {
  id: string;
  label: string; // "Approve" | "Reject" | "View"
  variant: "primary" | "secondary" | "destructive";
  endpoint: string; // API endpoint for action
  method: "POST" | "PUT" | "PATCH";
  confirmRequired: boolean; // Show confirmation dialog before executing
}

interface ProgressIndicator {
  current: number;
  total: number;
  label: string; // "Uploading 3 of 7 files"
  isIndeterminate: boolean;
}

/** Grouped notification (client-side aggregation of server groups) */
interface NotificationGroup {
  groupKey: string;
  notifications: Notification[];
  latestAt: string; // Most recent notification timestamp
  isExpanded: boolean; // UI state: show individual items
  summary: string; // "Alice and 4 others liked your post"
}

/** User notification preferences */
interface NotificationPreferences {
  userId: string;
  channels: Record<DeliveryChannel, ChannelConfig>;
  categories: Record<NotificationCategory, CategoryConfig>;
  quietHours: QuietHoursConfig;
  digestFrequency: "realtime" | "hourly" | "daily" | "weekly";
  updatedAt: string;
}

interface ChannelConfig {
  enabled: boolean;
  priority: number; // Lower = tried first in fallback chain
}

interface CategoryConfig {
  channels: Partial<Record<DeliveryChannel, boolean>>; // Per-category channel overrides
  muted: boolean; // Suppress all for this category
  muteUntil?: string; // Temporary mute (ISO timestamp)
}

interface QuietHoursConfig {
  enabled: boolean;
  startTime: string; // "22:00" (local time)
  endTime: string; // "08:00" (local time)
  timezone: string; // IANA timezone identifier
  allowUrgent: boolean; // Let 'urgent' priority through
  daysOfWeek: number[]; // 0=Sun, 6=Sat
}

/** WebSocket message types */
type WSInboundMessage =
  | { type: "notification:new"; payload: Notification }
  | {
      type: "notification:updated";
      payload: Partial<Notification> & { id: string };
    }
  | { type: "notification:read"; payload: { ids: string[] } }
  | { type: "badge:sync"; payload: { unreadCount: number } }
  | { type: "preferences:changed"; payload: Partial<NotificationPreferences> }
  | {
      type: "connection:ack";
      payload: { connectionId: string; serverTime: string };
    };

type WSOutboundMessage =
  | { type: "subscribe"; payload: { channels: string[] } }
  | { type: "mark_read"; payload: { notificationIds: string[] } }
  | { type: "mark_all_read"; payload: { before: string } }
  | { type: "ping" };

/** Zustand store shape */
interface NotificationStore {
  // Feed state
  notifications: Map<string, Notification>;
  groups: Map<string, NotificationGroup>;
  feedOrder: string[]; // Ordered IDs for rendering
  cursor: string | null; // Pagination cursor
  hasMore: boolean;
  isLoading: boolean;

  // Unread state
  unreadCount: number;
  unreadByCategory: Record<NotificationCategory, number>;

  // Connection state
  wsStatus: "connecting" | "connected" | "reconnecting" | "disconnected";
  lastSyncTimestamp: string;

  // Toast state
  toastQueue: ToastItem[];
  visibleToasts: ToastItem[]; // Max 3

  // Actions
  addNotification: (notification: Notification) => void;
  markAsRead: (ids: string[]) => void;
  markAllAsRead: () => void;
  loadMore: () => Promise<void>;
  dismissToast: (id: string) => void;
}

interface ToastItem {
  id: string;
  notification: Notification;
  priority: "low" | "medium" | "high" | "urgent";
  autoDismissMs: number; // 5000 default, 0 for persistent
  enteredAt: number; // Date.now() for animation timing
  actions?: NotificationAction[];
}

/** Push subscription stored in IndexedDB */
interface PushSubscriptionRecord {
  endpoint: string;
  expirationTime: number | null;
  keys: {
    p256dh: string;
    auth: string;
  };
  registeredAt: string;
  lastRefreshedAt: string;
  userAgent: string; // For debugging stale subscriptions
}

/** GET /api/notifications — Paginated feed */
interface GetNotificationsRequest {
  cursor?: string; // Opaque cursor from previous response
  limit?: number; // Default: 50, max: 100
  filter?: "all" | "unread" | "mentions";
  category?: NotificationCategory;
}

interface GetNotificationsResponse {
  notifications: Notification[];
  nextCursor: string | null; // null = no more pages
  unreadCount: number; // Always returned for badge sync
  serverTime: string; // For clock drift compensation
}
// Cache-Control: private, no-cache (always revalidate — personalized data)

/** PATCH /api/notifications/read — Mark notifications as read */
interface MarkReadRequest {
  notificationIds: string[]; // Max 100 per request
}

interface MarkReadResponse {
  updated: number;
  unreadCount: number; // New total after update
}

/** POST /api/notifications/read-all — Mark all as read */
interface MarkAllReadRequest {
  before: string; // ISO timestamp — only mark items before this
  category?: NotificationCategory; // Optional category scope
}

interface MarkAllReadResponse {
  updated: number;
  unreadCount: number;
}

/** POST /api/notifications/:id/action — Execute notification action */
interface ExecuteActionRequest {
  actionId: string;
  idempotencyKey: string; // Client-generated UUID for safe retries
}

interface ExecuteActionResponse {
  success: boolean;
  notification: Notification; // Updated notification state
}

/** GET /api/notifications/preferences — User preferences */
interface GetPreferencesResponse {
  preferences: NotificationPreferences;
}
// Cache-Control: private, max-age=60

/** PUT /api/notifications/preferences — Update preferences */
interface UpdatePreferencesRequest {
  preferences: Partial<NotificationPreferences>;
}

interface UpdatePreferencesResponse {
  preferences: NotificationPreferences;
}

/** POST /api/push/subscribe — Register push subscription */
interface PushSubscribeRequest {
  subscription: PushSubscriptionJSON; // From PushSubscription.toJSON()
  deviceName?: string;
  userAgent: string;
}

interface PushSubscribeResponse {
  subscriptionId: string;
  expiresAt: string | null;
}

/** DELETE /api/push/subscribe/:subscriptionId — Unregister */
// No request body, 204 on success

// Connection: wss://api.example.com/ws/notifications
// Auth: Bearer token in first message after connection

// Client → Server: Authentication
{ type: 'auth', payload: { token: string; tabId: string } }

// Server → Client: Connection acknowledged
{ type: 'connection:ack', payload: { connectionId: string; serverTime: string } }

// Client → Server: Heartbeat (every 30s)
{ type: 'ping' }

// Server → Client: Heartbeat response
{ type: 'pong', payload: { serverTime: string } }

// Server → Client: New notification
{ type: 'notification:new', payload: Notification }

// Client → Server: Mark as read (fire-and-forget with optimistic UI)
{ type: 'mark_read', payload: { notificationIds: string[] } }

interface ApiError {
  code: string; // Machine-readable: 'RATE_LIMITED'
  message: string; // Human-readable description
  retryAfter?: number; // Seconds (for rate limiting)
  details?: Record<string, unknown>;
}

// Rate limits:
// - GET /notifications: 60 req/min per user
// - PATCH /notifications/read: 30 req/min per user
// - POST /notifications/read-all: 5 req/min per user
// - POST /push/subscribe: 10 req/hour per user

// Schema: notifications-db v1
interface NotificationDB {
  notifications: {
    key: string; // notification.id
    value: Notification;
    indexes: {
      "by-created": string; // createdAt for range queries
      "by-read": [boolean, string]; // [isRead, createdAt] compound index
      "by-category": string;
    };
  };
  metadata: {
    key: string; // 'lastSync' | 'cursor' | 'unreadCount'
    value: unknown;
  };
  pushSubscription: {
    key: string; // 'active'
    value: PushSubscriptionRecord;
  };
}

const channel = new BroadcastChannel("notifications-sync");

// Tab A marks notification as read:
channel.postMessage({
  type: "MARK_READ",
  payload: { ids: ["notif-123"], unreadCount: 7 },
});

// All other tabs receive and update their local store:
channel.onmessage = (event) => {
  if (event.data.type === "MARK_READ") {
    store.getState().syncReadState(event.data.payload);
  }
};

const virtualizer = useVirtualizer({
  count: feedOrder.length,
  getScrollElement: () => scrollRef.current,
  estimateSize: (index) => {
    const id = feedOrder[index];
    const group = groups.get(id);
    return group?.isExpanded ? group.notifications.length * 72 + 48 : 72;
  },
  overscan: 5,
});

// Service Worker: Validate push event origin
self.addEventListener("push", (event) => {
  // Only process if the push came from our application server
  // The browser validates VAPID signature automatically
  const payload = event.data?.json();
  if (!payload || !payload.notificationId) {
    return; // Discard malformed payloads
  }

  // Validate payload structure before displaying
  if (!isValidNotificationPayload(payload)) {
    console.error("Invalid push payload structure");
    return;
  }

  event.waitUntil(
    self.registration.showNotification(payload.title, {
      body: payload.body,
      icon: payload.icon,
      data: { deepLink: sanitizeDeepLink(payload.deepLink) },
      tag: payload.groupKey, // Replaces existing notification with same tag
    }),
  );
});

function sanitizeDeepLink(link: string): string {
  // Only allow relative paths starting with /
  if (!link.startsWith("/") || link.includes("//")) {
    return "/notifications"; // Fallback to notification feed
  }
  return link;
}

// SAFE: Structured template rendering
function renderNotificationMessage(message: NotificationMessage): ReactNode {
  // Use plainText for screen readers, structured rendering for visual
  return (
    <span aria-label={message.plainText}>
      {parseTemplate(message.template, {
        actor: <strong>{actor.displayName}</strong>,
        entity: <span className="text-muted">{entity.title}</span>,
      })}
    </span>
  );
}

// NEVER: Raw HTML injection
// ❌ <div dangerouslySetInnerHTML={{ __html: message.richText }} />

default-src 'self';
connect-src 'self' wss://api.example.com;
img-src 'self' https://cdn.example.com https://avatars.example.com;
script-src 'self' 'nonce-{random}';
worker-src 'self';

function groupNotifications(
  items: Notification[],
): (Notification | NotificationGroup)[] {
  const groups = new Map<string, Notification[]>();

  for (const item of items) {
    if (item.groupKey) {
      const existing = groups.get(item.groupKey) ?? [];
      existing.push(item);
      groups.set(item.groupKey, existing);
    }
  }

  // Server provides groupKey — client merely renders the grouping
  // This avoids expensive client-side deduplication logic
  return items.reduce(
    (acc, item) => {
      if (item.groupKey && groups.get(item.groupKey)!.length > 1) {
        if (!acc.some((x) => "groupKey" in x && x.groupKey === item.groupKey)) {
          acc.push({
            groupKey: item.groupKey,
            notifications: groups.get(item.groupKey)!,
            latestAt: groups.get(item.groupKey)![0].createdAt,
            isExpanded: false,
            summary: buildGroupSummary(groups.get(item.groupKey)!),
          });
        }
      } else {
        acc.push(item);
      }
      return acc;
    },
    [] as (Notification | NotificationGroup)[],
  );
}

class NotificationOutbox {
  private queue: QueuedAction[] = [];

  async enqueue(action: QueuedAction): Promise<void> {
    this.queue.push({ ...action, enqueuedAt: Date.now(), retries: 0 });
    await this.persistToIndexedDB();
    this.flush(); // Attempt immediate delivery
  }

  async flush(): Promise<void> {
    if (!navigator.onLine) return;

    const pending = this.queue.filter((a) => a.retries < 3);
    for (const action of pending) {
      try {
        await this.execute(action);
        this.queue = this.queue.filter((a) => a.id !== action.id);
      } catch (err) {
        action.retries++;
        action.lastError = err.message;
      }
    }
    await this.persistToIndexedDB();
  }
}

// Notification announcer — announces new notifications to screen readers
<div
  role="status"
  aria-live="polite"
  aria-atomic="false"
  className="sr-only"
>
  {latestNotification && (
    <span>{latestNotification.message.plainText}</span>
  )}
</div>

// Toast announcer — uses assertive for time-sensitive toasts
<div
  role="alert"
  aria-live="assertive"
  className="sr-only"
>
  {urgentToast && <span>{urgentToast.notification.message.plainText}</span>}
</div>

<section aria-label="Notifications" role="feed" aria-busy={isLoading}>
  {notifications.map((notification, index) => (
    <article
      key={notification.id}
      role="article"
      aria-setsize={-1} // Unknown total (infinite scroll)
      aria-posinset={index + 1}
      aria-label={notification.message.plainText}
      aria-describedby={`notif-time-${notification.id}`}
      data-read={notification.isRead}
      tabIndex={0}
    >
      {/* Notification content */}
      <time
        id={`notif-time-${notification.id}`}
        dateTime={notification.createdAt}
      >
        {relativeTime(notification.createdAt)}
      </time>
    </article>
  ))}
</section>

const prefersReducedMotion = window.matchMedia(
  "(prefers-reduced-motion: reduce)",
).matches;

// Toast animations
const toastAnimation = prefersReducedMotion
  ? { enter: "opacity-0 → opacity-100", duration: "0ms" } // Instant appear
  : { enter: "translateX(100%) → translateX(0)", duration: "200ms" };

// Badge counter
const badgeAnimation = prefersReducedMotion
  ? "none"
  : "scale(1.2) → scale(1) over 150ms"; // Subtle bounce on increment

// WebSocket-specific error tracking
wsManager.on("error", (error) => {
  errorTracker.capture({
    category: "websocket",
    error,
    context: {
      readyState: ws.readyState,
      reconnectAttempts: wsManager.reconnectCount,
      lastPongAt: wsManager.lastPongTimestamp,
      tabId: sessionTabId,
    },
  });
});

// Push subscription error tracking
async function registerPush(): Promise<void> {
  try {
    const subscription = await registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
    });
    await sendSubscriptionToServer(subscription);
  } catch (error) {
    errorTracker.capture({
      category: "push_registration",
      error,
      context: {
        permissionState: Notification.permission,
        serviceWorkerState: registration.active?.state,
      },
    });
  }
}