Skip to main content

​
Real-time Collaboration

Chronicle uses CRDTs (Conflict-free Replicated Data Types) via the fork-node engine to enable seamless real-time collaboration without a central authority.

​
How It Works

Every edit is transformed into a CRDT operation, sent to the relay, merged by fork-node, and broadcast to all connected clients. Because CRDTs are mathematically conflict-free, no operational transformation is needed.

​
Setting Up Collaboration

​
1. Start the Relay Service

cd chronicle-hq/relay
cargo run --release
The relay binds to ws://localhost:4000 by default.

​
2. Configure the Editor

import { Chronicle, CollaborationPlugin } from '@chronicle-hq/editor';

const editor = new Chronicle({
  plugins: [
    CollaborationPlugin({
      relayUrl: 'ws://localhost:4000',
      documentId: 'doc-abc-123',
      userId: 'user-1',
      displayName: 'Alice',
    }),
  ],
});

​
3. Presence Awareness

Connected users appear with colored cursors and selection highlights: 
// Listen for presence updates
editor.on('presence', (users) => {
  console.log('Active collaborators:', users);
  // [{ userId: 'user-2', displayName: 'Bob', color: '#818CF8', cursor: { line: 12, ch: 5 } }]
});

​
Conflict Resolution

fork-node uses Yjs-compatible CRDTs under the hood:
  • Text operations — character-level insertions and deletions merge automatically
  • Structural changes — heading levels, list nesting, and block moves use LWW (Last Writer Wins) with vector clocks
  • Concurrent edits — two users typing in the same paragraph see each other’s changes interleave naturally

​
Edge Cases

ScenarioResolution
Same character deleted by two usersIdempotent — delete applies once
Simultaneous heading changeLWW by vector clock timestamp
Offline edits synced laterCRDT merge on reconnection
Network partitionEach partition continues independently; merge on heal

​
Performance Considerations

  • Document size — CRDTs maintain a full operation log. For documents over 100K operations, enable compaction via compactionThreshold in relay config.
  • Concurrent users — relay supports up to 50 concurrent editors per document. Beyond that, consider sharding.
  • Bandwidth — operations are protobuf-encoded for minimal wire size (~40 bytes per character insert).

​
Security

All collaboration traffic is authenticated:
  1. Users connect with a JWT issued by aegis-node
  2. The relay validates the token and checks document-level permissions
  3. Every operation is signed and recorded in vest-node for audit
See the API Reference for WebSocket message formats.