Real-Time Collaboration

frontend/shared/src/realtime/
  WebSocketProvider.tsx     # WebSocket connection management
  EventSource.tsx           # Server-Sent Events for streaming
  LiveUpdates.tsx           # Live data update components
  Presence.tsx              # User presence tracking
  NotificationCenter.tsx    # Real-time notification delivery
  queryStatus.ts            # Query execution status tracking
  types.ts                  # TypeScript interfaces
  index.ts                  # Barrel exports

interface WebSocketConfig {
  url: string;                            // WebSocket server URL
  protocols?: string | string[];          // Sub-protocols
  autoReconnect?: boolean;                // Auto-reconnect on disconnect (default: true)
  maxReconnectAttempts?: number;          // Max reconnection attempts (default: 10)
  reconnectDelay?: number;               // Initial reconnect delay in ms (default: 1000)
  reconnectDelayMultiplier?: number;      // Backoff multiplier (default: 1.5)
  maxReconnectDelay?: number;             // Maximum backoff delay in ms (default: 30000)
  pingInterval?: number;                  // Heartbeat interval in ms (default: 30000)
  queueSize?: number;                     // Max queued messages when disconnected (default: 100)
  authToken?: string;                     // Authentication token for connection
  headers?: Record<string, string>;       // Additional headers as query params
  onOpen?: () => void;                    // Connection established callback
  onClose?: (event: CloseEvent) => void;  // Connection closed callback
  onError?: (event: Event) => void;       // Connection error callback
  onMessage?: (message: WebSocketMessage) => void; // Global message handler
}

              connect()
                 |
                 v
          [CONNECTING]
                 |
          WebSocket.onopen
                 |
                 v
          [CONNECTED] <-----+
                 |           |
            onclose      reconnect()
                 |           |
                 v           |
         [DISCONNECTED]      |
                 |           |
      autoReconnect?         |
                 |           |
                 v           |
         [RECONNECTING] ----+
                 |
          attempts > max?
                 |
                 v
         [DISCONNECTED] (final)

interface WebSocketMessage<T = unknown> {
  type: string;              // Message type (e.g., 'query.update', 'notification')
  channel?: string;          // Subscription channel
  payload?: T;               // Message payload
  id?: string;               // Unique message identifier
  timestamp?: number;        // Unix timestamp
}

import { useWebSocketChannel } from '@matih/shared/realtime';
 
function QueryStatusPanel({ queryId }: { queryId: string }) {
  const [status, setStatus] = useState<QueryStatus>('pending');
 
  useWebSocketChannel<QueryStatusUpdate>(
    `query.${queryId}`,
    (data) => {
      setStatus(data.status);
    },
    [queryId]
  );
 
  return <StatusBadge status={status} />;
}

Disconnected state:
  send(msg1) -> [Queue: msg1]
  send(msg2) -> [Queue: msg1, msg2]
  send(msg3) -> [Queue: msg1, msg2, msg3]

Reconnect:
  onopen -> flush queue
  WebSocket.send(msg1)
  WebSocket.send(msg2)
  WebSocket.send(msg3)
  [Queue: empty]

// Sent every pingInterval (default 30s)
{
  "type": "ping",
  "timestamp": 1707580800000
}
 
// Expected response from server
{
  "type": "pong",
  "timestamp": 1707580800050
}

import { WebSocketProvider } from '@matih/shared/realtime';
 
function App() {
  return (
    <WebSocketProvider
      config={{
        url: `${import.meta.env.VITE_WS_URL}/ws`,
        authToken: authContext.token,
        headers: {
          'X-Tenant-ID': tenantId,
        },
        onOpen: () => console.log('WebSocket connected'),
        onClose: () => console.log('WebSocket disconnected'),
        onError: (error) => telemetry.captureError('WebSocket error', error),
      }}
    >
      <RouterProvider router={router} />
    </WebSocketProvider>
  );
}

// Using SSE for AI response streaming
import { useEventSource } from '@matih/shared/realtime';
 
function StreamingResponse({ conversationId }: { conversationId: string }) {
  const { data, error, status } = useEventSource(
    `/api/ai/v1/chat/stream?conversationId=${conversationId}`,
    {
      onToken: (token) => appendToDisplay(token),
      onComplete: (response) => finalizeMessage(response),
      onError: (error) => showError(error),
    }
  );
 
  return (
    <div>
      {status === 'streaming' && <StreamingIndicator />}
      <div className="response-content">{data}</div>
    </div>
  );
}

Dashboard: Q4 Revenue Analysis
  Currently viewing: [Avatar: Alice] [Avatar: Bob] [Avatar: Carol] +2 more
  Editing: [Avatar: Alice] (filter panel)

// Join presence
send({
  type: 'presence.join',
  channel: `dashboard.${dashboardId}`,
  payload: {
    userId: currentUser.id,
    name: currentUser.name,
    avatar: currentUser.avatar,
    activity: 'viewing',
  },
});
 
// Update activity
send({
  type: 'presence.update',
  channel: `dashboard.${dashboardId}`,
  payload: {
    activity: 'editing',
    component: 'filter-panel',
  },
});
 
// Leave (sent automatically on component unmount)
send({
  type: 'presence.leave',
  channel: `dashboard.${dashboardId}`,
});

import { useLiveData } from '@matih/shared/realtime';
 
function RevenueWidget({ widgetId }: { widgetId: string }) {
  const { data, lastUpdated } = useLiveData({
    channel: `widget.${widgetId}`,
    fetchFn: () => api.get(`/widgets/${widgetId}/data`),
    pollInterval: 60000,       // Fallback poll every 60s
    enableWebSocket: true,     // Prefer WebSocket push
  });
 
  return (
    <div>
      <MetricDisplay value={data?.revenue} />
      <span className="last-updated">Updated {formatRelative(lastUpdated)}</span>
    </div>
  );
}

Backend Service emits event to Kafka
    |
    v
Notification Service consumes event
    |
    v
Notification Service pushes via WebSocket
    |
    v
WebSocketProvider receives message
    |
    v
NotificationCenter component updates:
  - Badge count incremented
  - Toast displayed (if enabled)
  - Sound played (if enabled)
  - Notification added to list

function ConnectionIndicator() {
  const wsStatus = useWebSocketStatus();
 
  const statusConfig = {
    connected: { label: 'Connected', color: 'green' },
    connecting: { label: 'Connecting...', color: 'yellow' },
    reconnecting: { label: 'Reconnecting...', color: 'yellow' },
    disconnected: { label: 'Disconnected', color: 'red' },
    error: { label: 'Connection Error', color: 'red' },
  };
 
  const config = statusConfig[wsStatus];
 
  return (
    <div className="connection-indicator">
      <span className={`dot dot-${config.color}`} />
      <span>{config.label}</span>
    </div>
  );
}