OpenNoodl/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-002B-github-advanced-integration/GIT-008-notification-system

GIT-008: Notification System

Overview

Priority: High
Estimated Hours: 50-70
Dependencies: GIT-006 (Notification Server)
Status: 🔴 Not Started

Implement persistent cross-session notification system for collaboration invites, community events, mentions, and updates.

---

Strategic Context

Notifications bridge sessions - they ensure users don't miss:

• Collaboration invites - Someone wants to work with you
• Mentions - Someone referenced you in a discussion
• Session updates - Public session started by someone you follow
• Component updates - New component published in your community
• System messages - Important announcements

---

Technical Requirements

1. NotificationManager Service

File: packages/noodl-editor/src/editor/src/services/NotificationManager.ts

interface Notification {
  id: string;
  userId: string;
  fromUserId?: string;
  type: 'invite' | 'mention' | 'thread' | 'session' | 'component' | 'system';
  title: string;
  message: string;
  data?: Record<string, unknown>;
  read: boolean;
  createdAt: Date;
  expiresAt: Date;
  readAt?: Date;
  actions?: NotificationAction[];
}

interface NotificationAction {
  label: string;
  action: string;
  primary?: boolean;
}

Key Methods:

Method	Description
initialize(userId)	Connect to notification server
getNotifications()	Get all notifications
getUnreadCount()	Get unread count
markAsRead(id)	Mark notification as read
deleteNotification(id)	Delete a notification
sendNotification(userId, type, data)	Send to another user
destroy()	Disconnect and cleanup

2. Notification Types

Type	Trigger	Actions
invite	Someone invites you to collaborate	Join, Decline
mention	Someone mentions you in discussion	View Thread
thread	New reply in discussion you follow	View Thread
session	Public session started	Join Session
component	New component in your community	View Component
system	System announcement	Dismiss

3. Toast Notifications

Real-time toasts for new notifications:

// Toast component structure
interface ToastProps {
  notification: Notification;
  onAction: (action: string) => void;
  onDismiss: () => void;
}

// Toast behavior
- Appears bottom-right of editor
- Auto-dismisses after 10 seconds
- Can be clicked for quick action
- Can be swiped to dismiss
- Queue system for multiple notifications

4. Notification Center

Panel/popover for viewing all notifications:

┌─────────────────────────────────┐
│ Notifications               ✕   │
├─────────────────────────────────┤
│ ┌─────────────────────────────┐ │
│ │ 👥 Collaboration Invite     │ │
│ │ Alice invited you to        │ │
│ │ "Building a Dashboard"      │ │
│ │ [Join] [Decline]      2m ago│ │
│ └─────────────────────────────┘ │
│ ┌─────────────────────────────┐ │
│ │ 📦 New Component            │ │
│ │ Bob published "DataGrid"    │ │
│ │ [View]                 1h ago│ │
│ └─────────────────────────────┘ │
│ ┌─────────────────────────────┐ │
│ │ 💬 Discussion Reply         │ │
│ │ Charlie replied to your     │ │
│ │ question about routing      │ │
│ │ [View Thread]          3h ago│ │
│ └─────────────────────────────┘ │
├─────────────────────────────────┤
│ [Mark All Read]  [Clear All]    │
└─────────────────────────────────┘

5. Desktop Notifications

Leverage Electron's native notification API:

// Show native notification
new Notification('Collaboration Invite', {
  body: 'Alice invited you to collaborate',
  icon: '/path/to/icon.png',
  tag: notification.id, // Prevents duplicates
  requireInteraction: notification.type === 'invite' // Stay until clicked
});

notification.onclick = () => {
  // Focus app and handle action
};

---

User Flows

Receiving Notification (Online)

1. Notification arrives via WebSocket
2. Toast appears in editor
3. Badge updates on notification bell
4. Desktop notification shows (if enabled)
5. User can act on toast or dismiss

Receiving Notification (Offline)

1. Notification stored on server
2. User opens app
3. Notifications fetched on connect
4. Multiple notifications batch-displayed
5. Badge shows unread count

Handling Notification Actions

Invite:

1. Click "Join" on invite notification
2. Session preview dialog opens
3. Confirm join options
4. Connect to collaboration session

Mention/Thread:

1. Click "View Thread"
2. Opens discussion in browser (GitHub Discussions)

Component:

1. Click "View Component"
2. Opens component in community panel

---

Implementation Tasks

Phase 1: Core Service (15-20 hours)

• Create NotificationManager.ts service
• Implement WebSocket connection to notification server
• Implement authentication flow
• Implement notification fetching
• Implement notification parsing/typing
• Implement mark as read
• Implement delete notification
• Implement send notification
• Add reconnection logic
• Add offline support (local storage cache)

Phase 2: Toast UI (10-15 hours)

• Create NotificationToast.tsx component
• Create toast container/queue
• Implement auto-dismiss
• Implement action buttons
• Implement swipe-to-dismiss
• Add animations
• Style according to notification type

Phase 3: Notification Center (15-20 hours)

• Create NotificationCenter.tsx component
• Create NotificationItem.tsx component
• Implement notification list with grouping
• Implement "Mark All Read"
• Implement "Clear All"
• Add notification badge to header
• Implement search/filter (optional)

Phase 4: Desktop Notifications (5-10 hours)

• Implement Electron notification API
• Add notification settings (enable/disable)
• Handle notification click → focus app
• Add notification sound (optional)
• Test on Windows, Mac, Linux

Phase 5: Integration (5-10 hours)

• Connect to existing authentication
• Integrate with collaboration system
• Add to editor layout
• Test end-to-end flows
• Performance optimization

---

Verification Steps

• Notifications persist across sessions
• Toast appears when notification received
• Can mark notifications as read
• Can delete notifications
• Unread count displays correctly
• Actions trigger correct behavior
• Desktop notifications work (Electron)
• Reconnects after connection loss
• Offline notifications cached and shown on reconnect
• Expired notifications cleaned up

---

Files to Create

packages/noodl-editor/src/editor/src/services/
├── NotificationManager.ts           # Main notification service
├── NotificationTypes.ts             # TypeScript interfaces

packages/noodl-editor/src/editor/src/views/
├── NotificationCenter/
│   ├── NotificationCenter.tsx       # Main panel/popover
│   ├── NotificationCenter.module.scss
│   ├── NotificationItem.tsx         # Individual notification
│   ├── NotificationBadge.tsx        # Unread count badge
│   └── NotificationEmpty.tsx        # Empty state
├── NotificationToast/
│   ├── NotificationToast.tsx        # Toast component
│   ├── NotificationToast.module.scss
│   └── ToastContainer.tsx           # Toast queue manager

packages/noodl-editor/src/editor/src/hooks/
├── useNotifications.ts              # Hook for notification state
└── useNotificationActions.ts        # Hook for notification actions

---

Notification Message Format

// Incoming notification from server
interface ServerNotification {
  id: string;
  userId: string;
  fromUserId?: string;
  type: 'invite' | 'mention' | 'thread' | 'session' | 'component' | 'system';
  data: {
    // Type-specific data
    sessionId?: string;
    sessionTitle?: string;
    threadUrl?: string;
    componentId?: string;
    componentName?: string;
    message?: string;
    [key: string]: unknown;
  };
  read: boolean;
  createdAt: string; // ISO date
  expiresAt: string; // ISO date
}

---

Settings

Setting	Default	Description
notifications.enabled	true	Enable notifications
notifications.desktop	true	Enable desktop notifications
notifications.sound	true	Play sound on notification
notifications.invites	true	Show collaboration invites
notifications.mentions	true	Show mentions
notifications.sessions	true	Show public sessions
notifications.components	true	Show component updates

---

Related Tasks

• GIT-006: Server Infrastructure (notification server)
• GIT-007: WebRTC Collaboration Client (sends invites)
• GIT-009: Community Tab UI (displays community notifications)