[ROADMAP][2.4] Integrate PartyKit for Real-Time Document Collaboration

[MODSetter]

Feature Description

Integrate PartyKit with the document editor to enable real-time collaborative editing, Google Docs-style commenting, user tagging, and a notification system. This transforms SurfSense's document editor into a truly collaborative workspace.

Target Deployment

• SurfSense Cloud (hosted version)
• Self-hosted version

Problem Statement

Current document editing is single-user, lacking:

• Real-time collaboration
• Concurrent editing capabilities
• Inline commenting
• Team communication within documents
• Notification system for document activity

Proposed Solution

Architecture

┌─────────────────────────────────────────────────────────┐
│                     Clients                              │
│  [User A Editor]  [User B Editor]  [User C Viewer]      │
│         │               │               │                │
│         └───────────────┼───────────────┘                │
│                         │                                │
│                         ▼                                │
│         ┌─────────────────────────┐                     │
│         │   PartyKit Server       │                     │
│         │   (Document Room)       │                     │
│         │                         │                     │
│         │  - Y.js CRDT state      │                     │
│         │  - User presence        │                     │
│         │  - Comments sync        │                     │
│         │  - Selection awareness  │                     │
│         └─────────────────────────┘                     │
│                         │                                │
│                         ▼                                │
│         ┌─────────────────────────┐                     │
│         │   SurfSense Backend     │                     │
│         │   - Persistence         │                     │
│         │   - Notifications       │                     │
│         │   - Permissions         │                     │
│         └─────────────────────────┘                     │
└─────────────────────────────────────────────────────────┘

Features

1. Real-Time Collaborative Editing

• Multiple users editing simultaneously
• CRDT-based conflict resolution (Y.js)
• Cursor/selection sharing
• User presence indicators

2. Google Docs-Style Commenting

┌─────────────────────────────────────────────────────────┐
│  Document Content                    │  Comments        │
│  ─────────────────                   │  ────────        │
│  Lorem ipsum dolor sit amet,         │  ┌────────────┐  │
│  [highlighted: consectetur]          │  │ @Alice:    │  │
│  adipiscing elit. Sed do             │  │ Can we     │  │
│  eiusmod tempor...                   │  │ rephrase?  │  │
│                                      │  │            │  │
│                                      │  │ ↳ @Bob:    │  │
│                                      │  │   Done!    │  │
│                                      │  │            │  │
│                                      │  │ [Resolve]  │  │
│                                      │  └────────────┘  │
└─────────────────────────────────────────────────────────┘

• Select text and add comment
• Reply to comments (threads)
• Resolve/reopen comments
• Comment notifications

3. User Tagging

• @mention users in comments
• @mention in document content
• Autocomplete for user names
• Link to user profiles

4. Notification System

• In-app notification center
• Real-time notification delivery
• Email notifications (configurable)
• Notification preferences
• Batch digest options

Y.js Integration with TipTap

import { TiptapCollabProvider } from '@hocuspocus/provider'
import * as Y from 'yjs'

const provider = new TiptapCollabProvider({
  name: `document-${documentId}`,
  // PartyKit WebSocket URL
  baseUrl: 'wss://surfsense.partykit.dev',
  document: new Y.Doc(),
})

const editor = new Editor({
  extensions: [
    Collaboration.configure({ document: provider.document }),
    CollaborationCursor.configure({
      provider,
      user: currentUser,
    }),
    Comments, // Custom extension
  ],
})

Benefits

• Full Google Docs-style collaboration
• Real-time team communication
• Clear feedback loops via comments
• Engagement through notifications
• Professional collaboration UX

Use Case Examples

1. Team simultaneously edits research document
2. Reviewer adds comments, writer addresses them
3. @mentioned user gets instant notification
4. User reviews comment thread, marks resolved

Implementation Considerations

• This may require frontend changes (major editor update)
• This may require backend changes (PartyKit, notifications)
• This may require database changes (comments, notifications)
• This may affect existing features (editor, document model)

Files to Create/Modify

• party/document.ts - Document collaboration party
• party/comments.ts - Comments synchronization
• surfsense_web/components/editor/ - Collaborative editor
• surfsense_backend/app/routes/notifications.py - Notifications
• surfsense_backend/app/schemas/comment.py - Comment schemas

Acceptance Criteria

• Multiple users can edit simultaneously
• Changes sync in real-time
• User cursors visible to others
• Comments can be added to selections
• Comment threads work correctly
• @mentions trigger notifications
• Notification center shows all activity
• Email notifications work (optional)
• Offline editing with sync on reconnect
• Permissions enforced in real-time

Technical Notes

• Use Y.js for CRDT-based sync
• Implement provider with PartyKit backend
• Consider TipTap Collaboration extension
• Add conflict resolution UX
• Implement awareness protocol for presence
• Document self-hosting requirements

Related Issues

• Depends on: Issues 2.1-2.3 (connectors, version control, publish)