Arg0/Docs

Real-time Collaborative Editing

CRDT live editing — multiple people and AI agents edit the same document at once, across web, desktop, and mobile.

Every cloud-linked document in Arg0 can be edited by several clients at the same time. The sync engine combines Yjs CRDTs with a realtime broadcast channel — no dedicated collaboration server is required. Edits merge automatically, cursors and presence are shared live, and the converged result is persisted back to the database with full version history.

Architecture

Each open document maps to one Y.Doc and one realtime channel named collab-doc:<document id>:

text
┌──────────┐      yjs-update / awareness      ┌─────────────────────┐
│  Editor  │ ◄──────────────────────────────► │   Realtime service  │
│  (Y.Doc) │        broadcast channel         │   collab-doc:<id>   │
└──────────┘                                  └──────────┬──────────┘
     │ debounced persist (~1.5s)                         │ change events
     ▼                                                   ▼
┌─────────────────────────────────────────────────────────────────┐
│        Database:  document row  +  automatic version history    │
└─────────────────────────────────────────────────────────────────┘

Sync protocol

MessageTransportPurpose
yjs-updatebroadcastIncremental Yjs update (base64) sent on every local change
sync-request / sync-statebroadcastState-vector handshake when a peer joins — the joiner sends its state vector and peers reply with the missing diff
awarenessbroadcastAwareness frames — remote cursors, selections, and the "editing" flag
trackpresenceOnline user list (name, color, client) powering the avatar row
change eventsdatabaseSnapshots written by non-collab writers (REST API, MCP/AI agents, mobile sync), folded into the live doc

Persistence

The provider debounces document updates (~1.5s), serializes the converged Y.Doc, and writes it to the document row. A database trigger bumps version and records a new version snapshot, so version history and restore keep working exactly as they do for manual saves. A lastPersisted marker suppresses echo when our own write comes back over the change feed.

Non-collab writers

A document can also be edited outside the collab session — via the REST API, MCP tools / AI agents, or mobile sync. Those writes arrive on the same channel as change events. To prevent every client folding the snapshot into its own doc independently (Yjs treats identical inserts as distinct items, which would duplicate content), the snapshot leader — the client holding the smallest presence key — merges it via a three-way merge and rebroadcasts the result as a normal yjs-update. Other clients' folds then become no-ops.

Conflict handling and reconnects

  • Concurrent edits merge automatically at the CRDT level — no locking and no last-write-wins.
  • Join seeding: a sole peer seeds the shared text from the persisted row; simultaneous joiners elect the smallest presence key to seed. A seed + seed dedupe pass covers the rare double-seed race.
  • Reconnects: channel errors and timeouts trigger a channel rebuild, and returning to the foreground probes the socket and force-rejoins if it died while suspended. After rejoining, the sync-request handshake catches up on missed updates.
  • Fallback: when collab is unavailable, editors fall back to version-checked saves with a conflict-resolution UI (word-level three-way merge).

Security

  • Authorization policies scope broadcast and presence to collab-doc: topics, so only a document's members can join its session.
  • Change events carry the complete row so the snapshot watcher sees full document state.
  • Document ids are unguessable UUIDs, and row-level access stays enforced on all reads and writes through the database.

Where it runs

SurfaceBinding
Web — workspace documents editorY.Text ↔ text bridge
Desktop — Plan page (raw view)MonacoBinding on Y.Text('content')
Desktop — Docs pageBlockNote collaboration on Y.XmlFragment('doc')
Desktop — Workflow local viewstring bridge on .workflow.md

Web, desktop, and mobile share the same wire protocol, so a document open on several devices stays live on all of them.