System Design #10: Design a Notification System

NotificationProvider (Context)
├── NotificationBell         // Bell icon + unread badge
├── NotificationPanel        // Dropdown/slideover
│   ├── NotificationFilters  // "All" | "Unread" | by category
│   ├── NotificationGroup    // "John and 3 others liked your post"
│   │   └── NotificationItem // Individual notification
│   └── LoadMoreTrigger      // Infinite scroll
├── NotificationToast        // Ephemeral popup for new notifications
└── PushPermissionBanner     // "Enable push notifications?"

Event (comment, like, etc.)
    ↓
Backend creates notification row
    ↓
Pushes via SSE/WebSocket to connected clients
    ↓
NotificationProvider receives
    ↓
├── Update unread count (badge)
├── Show toast (if panel is closed)
├── Prepend to notification list (if panel is open)
└── Send browser push (if tab is background + user opted in)

interface Notification {
  id: string;
  type: NotificationType;
  recipient_id: string;
  actor_id: string;         // Who triggered this
  actor: { name: string; avatar: string };
  target_type: 'post' | 'comment' | 'article';
  target_id: string;
  target_preview: string;   // "Your post about React hooks..."
  group_key: string;        // For grouping: "like:post:123"
  is_read: boolean;
  created_at: string;
  action_url: string;       // Where to navigate on click
}

type NotificationType = 
  | 'like'
  | 'comment'
  | 'reply'
  | 'mention'
  | 'follow'
  | 'system';

// Grouped notification for display
interface NotificationGroup {
  group_key: string;
  type: NotificationType;
  actors: { id: string; name: string; avatar: string }[];
  latest_at: string;
  count: number;            // Total in group
  is_read: boolean;         // All read?
  target_preview: string;
  action_url: string;
  // Display: "Alice, Bob, and 3 others liked your post"
}

interface NotificationState {
  groups: NotificationGroup[];     // Grouped for display
  unreadCount: number;             // Badge number
  isOpen: boolean;                 // Panel visibility
  filter: 'all' | 'unread';
  hasMore: boolean;                // Pagination
  cursor: string | null;
  isConnected: boolean;            // SSE status
  
  // Optimistic state
  pendingReadIds: Set<string>;     // Marked read locally, awaiting server
}

function groupNotifications(notifications: Notification[]): NotificationGroup[] {
  const groups = new Map<string, Notification[]>();
  
  for (const notif of notifications) {
    const existing = groups.get(notif.group_key) || [];
    existing.push(notif);
    groups.set(notif.group_key, existing);
  }
  
  return Array.from(groups.entries()).map(([key, notifs]) => {
    // Dedupe actors
    const actorMap = new Map<string, Notification['actor']>();
    notifs.forEach(n => actorMap.set(n.actor_id, n.actor));
    const actors = Array.from(actorMap.values());
    
    return {
      group_key: key,
      type: notifs[0].type,
      actors: actors.slice(0, 3),  // Show max 3 avatars
      count: actors.length,
      latest_at: notifs[0].created_at,
      is_read: notifs.every(n => n.is_read),
      target_preview: notifs[0].target_preview,
      action_url: notifs[0].action_url,
    };
  }).sort((a, b) => 
    new Date(b.latest_at).getTime() - new Date(a.latest_at).getTime()
  );
}

// Display text generator
function getGroupText(group: NotificationGroup): string {
  const { actors, count, type } = group;
  const verb = { like: 'liked', comment: 'commented on', reply: 'replied to', mention: 'mentioned you in', follow: 'followed you' }[type];
  
  if (count === 1) return `${actors[0].name} ${verb} ${group.target_preview}`;
  if (count === 2) return `${actors[0].name} and ${actors[1].name} ${verb} ${group.target_preview}`;
  return `${actors[0].name}, ${actors[1].name}, and ${count - 2} others ${verb} ${group.target_preview}`;
}

function useNotificationStream(userId: string) {
  const [state, dispatch] = useReducer(notificationReducer, initialState);
  
  useEffect(() => {
    const eventSource = new EventSource(
      `/api/notifications/stream?userId=${userId}`,
      { withCredentials: true }
    );
    
    eventSource.addEventListener('notification', (e) => {
      const notification: Notification = JSON.parse(e.data);
      dispatch({ type: 'NEW_NOTIFICATION', notification });
      
      // Show toast if panel is closed
      if (!state.isOpen) {
        showNotificationToast(notification);
      }
    });
    
    eventSource.addEventListener('count_sync', (e) => {
      // Periodic sync to correct any drift
      const { unreadCount } = JSON.parse(e.data);
      dispatch({ type: 'SYNC_COUNT', unreadCount });
    });
    
    eventSource.onerror = () => {
      dispatch({ type: 'SET_CONNECTED', connected: false });
      // EventSource auto-reconnects — no manual retry needed!
    };
    
    eventSource.onopen = () => {
      dispatch({ type: 'SET_CONNECTED', connected: true });
    };
    
    return () => eventSource.close();
  }, [userId]);
  
  return state;
}

// Batch mark-as-read calls to avoid N API calls
class ReadBatcher {
  private queue: string[] = [];
  private timer: ReturnType<typeof setTimeout> | null = null;
  
  markRead(notificationId: string) {
    this.queue.push(notificationId);
    
    if (!this.timer) {
      this.timer = setTimeout(() => {
        this.flush();
      }, 500); // Batch within 500ms window
    }
  }
  
  markAllRead() {
    this.queue = [];
    if (this.timer) clearTimeout(this.timer);
    this.timer = null;
    
    return api.post('/notifications/mark-all-read');
  }
  
  private async flush() {
    const ids = [...this.queue];
    this.queue = [];
    this.timer = null;
    
    await api.post('/notifications/mark-read', { ids });
  }
}

// Auto-mark as read when notification is visible for 1.5s
function useAutoMarkRead(notificationId: string, isVisible: boolean) {
  useEffect(() => {
    if (!isVisible) return;
    
    const timer = setTimeout(() => {
      readBatcher.markRead(notificationId);
    }, 1500);
    
    return () => clearTimeout(timer);
  }, [notificationId, isVisible]);
}

// Use BroadcastChannel to sync state across tabs
const channel = new BroadcastChannel('notifications');

// When one tab marks notifications as read:
function markAsRead(ids: string[]) {
  dispatch({ type: 'MARK_READ', ids });
  channel.postMessage({ type: 'MARK_READ', ids });
  api.post('/notifications/mark-read', { ids });
}

// Other tabs receive:
channel.onmessage = (event) => {
  dispatch(event.data);
};

// Only one tab should maintain the SSE connection
// Use a "leader election" pattern
const leader = await navigator.locks.request(
  'notification-stream',
  { ifAvailable: true },
  (lock) => {
    if (lock) {
      // This tab is the leader — connect SSE
      connectSSE();
      return new Promise(() => {}); // Hold the lock
    }
    return false; // Another tab is leader
  }
);

if (!leader) {
  // This tab receives updates via BroadcastChannel from the leader tab
}

function NotificationBadge({ count }: { count: number }) {
  const prevCount = useRef(count);
  const [animate, setAnimate] = useState(false);
  
  useEffect(() => {
    if (count > prevCount.current) {
      setAnimate(true);
      const timer = setTimeout(() => setAnimate(false), 300);
      prevCount.current = count;
      return () => clearTimeout(timer);
    }
    prevCount.current = count;
  }, [count]);
  
  if (count === 0) return null;
  
  return (
    <span className={cn(
      "absolute -top-1 -right-1 flex items-center justify-center",
      "min-w-[18px] h-[18px] rounded-full bg-destructive text-destructive-foreground",
      "text-[10px] font-bold px-1",
      animate && "animate-bounce"
    )}>
      {count > 99 ? '99+' : count}
    </span>
  );
}

async function requestPushPermission(): Promise<boolean> {
  if (!("Notification" in window)) return false;
  
  const permission = await Notification.requestPermission();
  if (permission !== 'granted') return false;
  
  // Register service worker for background push
  const registration = await navigator.serviceWorker.register('/sw.js');
  const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: VAPID_PUBLIC_KEY,
  });
  
  // Send subscription to server
  await api.post('/push/subscribe', subscription.toJSON());
  return true;
}

// Service worker handler (sw.js)
self.addEventListener('push', (event) => {
  const data = event.data?.json();
  event.waitUntil(
    self.registration.showNotification(data.title, {
      body: data.body,
      icon: data.icon,
      badge: '/notification-badge.png',
      data: { url: data.action_url },
      tag: data.group_key, // Replaces previous notification with same tag
    })
  );
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  event.waitUntil(clients.openWindow(event.notification.data.url));
});

interface NotificationPreferences {
  channels: {
    in_app: boolean;   // Always true
    push: boolean;
    email: boolean;
  };
  categories: {
    likes: { in_app: boolean; push: boolean; email: boolean };
    comments: { in_app: boolean; push: boolean; email: boolean };
    mentions: { in_app: boolean; push: boolean; email: boolean };
    follows: { in_app: boolean; push: boolean; email: boolean };
    system: { in_app: boolean; push: boolean; email: boolean }; // Can't disable
  };
  quiet_hours: {
    enabled: boolean;
    start: string; // "22:00"
    end: string;   // "07:00"
    timezone: string;
  };
}