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>:
┌──────────┐ 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
| Message | Transport | Purpose |
|---|---|---|
yjs-update | broadcast | Incremental Yjs update (base64) sent on every local change |
sync-request / sync-state | broadcast | State-vector handshake when a peer joins — the joiner sends its state vector and peers reply with the missing diff |
awareness | broadcast | Awareness frames — remote cursors, selections, and the "editing" flag |
track | presence | Online user list (name, color, client) powering the avatar row |
| change events | database | Snapshots 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 + seeddedupe 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-requesthandshake 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
| Surface | Binding |
|---|---|
| Web — workspace documents editor | Y.Text ↔ text bridge |
| Desktop — Plan page (raw view) | MonacoBinding on Y.Text('content') |
| Desktop — Docs page | BlockNote collaboration on Y.XmlFragment('doc') |
| Desktop — Workflow local view | string 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.
Related Documentation
- Docs & Plan — document workspaces
- Workflows —
.workflow.mdautomation - Prompts —
.prompt.mdlibrary