Collaborative Documents

Real-time collaborative code editing with Monaco, Yjs CRDTs, and room-based permissions.

Overview

collab_docs provides persistent, multi-user document editing. Documents are attached to chat rooms or standalone, edited with the Monaco code editor in the browser, and synchronized in real-time using Yjs CRDTs over Socket.IO. The server maintains in-memory Yjs documents with periodic persistence to SQLite. A full permission system controls access at owner/editor/viewer/room-member levels.

Architecture

collab_docs.doh.yaml
├── collab_docs_server    (nodejs)
│   ├── Yjs document lifecycle (in-memory + periodic persistence)
│   ├── Socket.IO sync protocol
│   ├── Permission system (4 groups)
│   ├── REST API (CRUD + page routes)
│   └── Programmatic API (createDoc, readDocContent, etc.)
└── collab_docs_client    (browser)
    ├── CollabDocManager         (full-page doc list + editor)
    ├── CollabDocManagerToolbar  (compact toolbar for chat rooms)
    ├── CollabDocManagerEditor   (Monaco + Yjs binding)
    └── collab_shared            (transport provider)

Depends on: express_router, user_host, collab_shared (browser) Loaded by: chat.doh.yaml Depended on by: collab_richtext

File Structure

Configuration

Database Schema

Document metadata shape:

{
  id: string,              // UUID
  title: string,
  room_id: string | null,  // Chat room ID or null for standalone
  owner: string,           // Username
  editors: string[],       // Usernames with write access
  viewers: string[],       // Usernames with read-only access
  type: string,            // 'plaintext' | 'richtext'
  language: string,        // Monaco language ID ('markdown', 'javascript', etc.)
  created_at: number,
  updated_at: number
}

Document state shape:

{
  id: string,      // Document ID (matches documents table)
  state: string    // Base64-encoded Yjs state
}

Permissions

Contexts

Groups

Permission Flow

1. Build context: { documentId, owner, editors, viewers, roomMembers }
2. Check Doh.permit(user, action, context) against groups
3. Cascade: owner → editor → room member → viewer

REST API Reference

POST /api/collab/docs

// Request
{ title: string, room_id?: string, editors?: string[], viewers?: string[], type?: string, language?: string }
// Response
{ doc: { id, title, room_id, owner, editors, viewers, type, language, created_at, updated_at } }

Page Routes

Socket Events Reference

Document Operations

collab:doc:open response detail:

{
  doc_meta: { id, title, room_id, owner, editors, viewers, type, language, created_at, updated_at },
  readOnly: boolean,          // User has read-only access
  syncStep1: number[],        // Yjs state vector (Uint8Array as array)
  syncStep2: number[],        // Full document state
  awarenessStates: number[],  // Remote cursor/presence states
  clientCount: number         // Active editors
}

Sync Protocol

Server Broadcasts

Lobby Events

For real-time document list updates on the /docs manager page.

IMPORTANT: Always use socket.emit('collab:doc:list', ...) for listing documents, not Doh.ajaxPromise(). The socket handler routes correctly to the list operation; ajaxPromise may trigger creation instead.

Programmatic API

Exported via Doh.Globals.CollabDocs for use by other modules (e.g., bot integrations):

Doh.Module('my_module', ['collab_docs_server'], function() {
  const docs = Doh.Globals.CollabDocs;

  // Create a document
  const doc = await docs.createDoc({
    title: 'Meeting Notes',
    content: '# Notes\n',
    room_id: 'room-123',
    owner: 'alice'
  });

  // Read/write content
  const content = docs.readDocContent(doc.id);
  const previous = docs.writeDocContent(doc.id, '# Updated\n');

  // Undo/redo
  docs.undoDocEdit(doc.id, 'system');
  docs.redoDocEdit(doc.id, 'system');

  // Query
  const roomDocs = docs.listRoomDocs('room-123');
  const single = docs.getDocById(doc.id);
  const canEdit = docs.canAccess(user, doc, 'write');
});

Exported Functions

Client Patterns

Usage in Chat

When a user enters a room:

1. chat_client.js calls docToolbar.loadDocs()
2. Client emits collab:doc:list with room_id
3. Server filters by room and permissions
4. Client renders doc tiles in toolbar
5. Clicking a tile opens the Monaco editor

Lobby Welcome Document

On server startup, a "Lobby Welcome" document is automatically created if it doesn't exist:

• ID: lobby-welcome-doc
• Room: lobby
• Owner: system
• Pre-populated with welcome markdown

All authenticated users can read and edit the lobby document.

Testing

1. Open /docs — verify document list loads
2. Create a new document — verify it appears in the list
3. Open document in two browsers — verify real-time sync (typing appears in both)
4. Verify cursor awareness (colored cursors from other users)
5. Test permissions: share doc with viewer, verify read-only mode
6. Open /collab/<doc-id> — verify fullscreen editor loads
7. In chat room, verify doc toolbar shows room documents