fileverse/docs/yjs-vs-automerge.md

Y.js vs Automerge: Decision for rStack + Fileverse Integration

Current State

rSpace uses both frameworks in a layered architecture:

┌─────────────────────────────────────────┐
│  TipTap Editor                          │
│  ↕ y-prosemirror binding                │
│  ↕ Y.js (editor collaboration)          │  ← Fileverse integrates HERE
├─────────────────────────────────────────┤
│  Automerge (document state + sync)      │  ← State management stays HERE
│  ↕ WebSocket binary sync protocol       │
│  ↕ IndexedDB encrypted persistence      │
└─────────────────────────────────────────┘

Why This Dual Approach Works

Y.js Layer (Editor)

• y-prosemirror: Official TipTap/ProseMirror binding for real-time editing
• y-indexeddb: Client-side persistence for editor state
• Awareness protocol: Cursor positions, user presence
• This is what Fileverse's ddoc and collaboration-server use

Automerge Layer (State)

• Document metadata, permissions, notebook structure
• Binary sync protocol over WebSocket
• Encrypted storage with DocCrypto
• Migration path from PostgreSQL

Integration Surface

Fileverse components connect at the Y.js layer:

• collaboration-server speaks Y.js sync protocol over WebSocket
• @fileverse-dev/ddoc uses y-prosemirror internally
• @fileverse-dev/dsheet uses Y.js for cell sync

The Automerge layer is invisible to Fileverse — it handles higher-level state that Fileverse doesn't need to know about.

Decision

Keep the dual architecture. No migration needed.

Rationale

1. No conflict — Y.js and Automerge operate at different levels
2. Fileverse compatibility — Their components plug into the Y.js layer directly
3. Automerge strengths preserved — Better merge semantics for structured data, Rust/WASM performance for large documents
4. Migration cost: zero — No existing code needs to change

What This Means for Each Integration

Integration	CRDT Layer	Notes
E2E encryption	Neither (operates on raw bytes)	Encrypts before CRDT, decrypts after
IPFS storage	Neither (file blobs)	CIDs stored in Automerge metadata
Collab server	Y.js	Handles editor sync + awareness
dSheet	Y.js	Self-contained Y.js-based component
UCAN auth	Neither (auth layer)	Wraps transport, not CRDTs

Alternative Considered: Full Y.js Migration

If we were starting fresh, using Y.js for everything would be simpler. But the migration cost outweighs the benefit:

• Automerge schemas, storage, and sync code in rSpace would all need rewriting
• The PostgreSQL → Automerge migration tool would be wasted
• Automerge's typed document schemas are more ergonomic than Y.js's untyped maps/arrays

Conclusion

The existing architecture is already well-positioned for Fileverse integration. No CRDT migration needed. Focus integration efforts on the Y.js/TipTap layer where Fileverse components naturally connect.