Skip to content
pm-skills

Develop ADR: Workbench Blueprints

Scenario

Workbench is a Series B enterprise collaboration platform (~200 employees, ~500 enterprise customers [fictional]) building Blueprints. Following a 5-day CRDT spike that evaluated Yjs, Automerge, and ShareDB, Karen L. (Engineering Lead) recorded this ADR to formalize the decision to adopt Yjs as the CRDT library for Blueprint real-time co-editing. The ADR captures the technical rationale and consequences for James W. (VP Engineering) and future engineers who will maintain the integration. Because the spike surfaced significant trade-offs in bundle size, ProseMirror binding maturity, and offline-first capability, Karen wanted the decision documented before Sprint 1 planning so the team could commit engineering resources with full visibility into the downstream implications.

Source Notes:

  • Yjs documentation (docs.yjs.dev) describes the y-prosemirror binding as the recommended integration path for ProseMirror-based editors, with support for cursor awareness, undo management, and offline persistence.
  • Michael Kleppmann’s paper “A Conflict-Free Replicated JSON Datatype” (2017, University of Cambridge) provides the theoretical foundation for JSON CRDTs, which both Yjs and Automerge implement with different performance trade-offs.
  • The ProseMirror project documentation (prosemirror.net) describes its collaborative editing architecture as transport-agnostic, supporting both OT and CRDT backends.

Prompt

/adr


ADR: Use Yjs CRDTs for Blueprints real-time co-editing
Product: Workbench Blueprints
Stage: Post-CRDT spike; recording architecture decision


Context:
- Blueprints requires real-time co-editing (20+ concurrent editors [fictional])
- ProseMirror-based editor; no current collaboration layer
- Enterprise requirements: offline-first, conflict resolution, per-user audit trail
- Spike evaluated Yjs, Automerge, ShareDB


Decision: Yjs
- 2-day integration via y-prosemirror; 45ms merge latency at 20 users [fictional]; +38KB gzipped [fictional]; offline-first
- Automerge rejected: no ProseMirror binding (3-4 week custom build [fictional]); +120KB [fictional]
- ShareDB rejected: no offline support (disqualified)


Consequences:
- Positive: fast integration, offline-first, active community, sub-document support
- Negative: WebSocket provider TBD, audit trail requires custom middleware, binary document format
- Neutral: bundle size acceptable for enterprise


Stakeholders: James W. (VP Engineering), Karen L. (Eng Lead), Nate P. (Backend Engineer)

Output

ADR-012: Use Yjs CRDTs for Blueprints Real-Time Co-Editing

Status

Accepted, December 8, 2025

Participants: Karen L. (Engineering Lead), Nate P. (Backend Engineer), James W. (VP Engineering, reviewer)

Context

Blueprints requires real-time co-editing so that multiple enterprise authors can work simultaneously on the same document. The target performance requirement is 20+ concurrent editors per Blueprint with merge latency below 100ms [fictional]. Enterprise customers require offline-first capability (for field teams with unreliable connectivity), deterministic conflict resolution that preserves author intent, and per-user change attribution for audit trail compliance. These requirements reflect feedback from discovery interviews with six enterprise team leads (October 2025), where unreliable connectivity and compliance-driven change tracking emerged as non-negotiable constraints for any co-editing solution.

The current Workbench editor is built on ProseMirror with no collaboration layer. A 5-day CRDT spike (December 1-5, 2025) evaluated three libraries: Yjs, Automerge, and ShareDB. The spike produced functional prototypes for Yjs and ShareDB, and a partial prototype for Automerge (no ProseMirror binding available). Performance benchmarks were collected using a Playwright-based load test with 20 simulated concurrent editors. Nate P. led the spike and documented each prototype’s integration steps, performance results, and qualitative assessment of developer ergonomics.

Decision

Adopt Yjs (v13.6+, MIT license) as the CRDT library for Blueprints real-time co-editing. Use the y-prosemirror binding for ProseMirror integration. Deploy a WebSocket-based synchronization provider (specific provider to be determined in a follow-up decision). The production integration is estimated at 2 sprints, covering the WebSocket provider, persistence adapter, cursor awareness UI, and audit-trail middleware [fictional].

Consequences

Positive

  • 2-day integration baseline: The y-prosemirror binding provides cursor awareness, undo/redo per user, and document synchronization out of the box, reducing initial integration effort to an estimated 2 sprints for production-grade deployment [fictional]. This fast prototyping cycle also means the team can iterate on the collaboration UX without building foundational plumbing from scratch.
  • Offline-first by default: Yjs queues edits locally when disconnected and merges them automatically on reconnect, satisfying the enterprise offline-first requirement without additional engineering work. This is particularly important for field teams at customers like those in the logistics and healthcare verticals, where connectivity gaps are common.
  • Sub-document support: Yjs allows independent synchronization of document sections, reducing merge payloads for large Blueprints and enabling section-level lazy loading. For Blueprints with 10+ sections, this keeps merge payloads proportional to the section being edited rather than the full document.
  • Active community: 15K+ GitHub stars, weekly maintenance commits, and production adoption by Liveblocks, BlockSuite, and other ProseMirror-based editors. The y-prosemirror binding is maintained by the Yjs author.
  • Performance within target: 45ms median merge latency at 20 concurrent editors [fictional], well within the 100ms requirement. The 95th percentile latency measured during the spike was 72ms [fictional], still comfortably under the threshold.

Negative

  • WebSocket provider decision deferred: Yjs is transport-agnostic. The team must separately evaluate y-websocket (reference implementation), Hocuspocus (Tiptap’s managed Yjs server), or a custom WebSocket provider on existing infrastructure. This affects deployment architecture, operational cost, and scaling. Until the provider is selected, the team cannot finalize the production infrastructure topology.
  • Per-user audit trail requires custom middleware: Yjs tracks user awareness (cursor position, identity) but does not natively produce a per-edit attribution log. Building audit trail compliance requires a custom middleware layer that intercepts Yjs updates and records author identity per change. Nate P. estimated this middleware at approximately 1 week of engineering effort [fictional].
  • Opaque document format: Yjs documents are stored as binary (Uint8Array), not human-readable JSON. Debugging document state, running database queries against document content, or migrating to a different CRDT library will require conversion tooling. This also means that data export features must decode Yjs state into a readable format before serving it to customers.
  • Vendor concentration risk: The y-prosemirror binding is maintained by a single author (Kevin Jahns). If the maintainer reduces involvement, Workbench would need to fork and maintain the binding. To mitigate this, the team will pin the binding version and maintain a shallow fork for critical patches.

Neutral

  • Bundle size (+38KB gzipped [fictional]) is acceptable for enterprise web applications where load time sensitivity is lower than consumer apps. The combined bundle (Yjs core + y-prosemirror) brings the total client payload to approximately 458KB gzipped [fictional], which remains within the 500KB performance budget. May need revisiting for a future mobile authoring experience.
  • CRDT merge semantics differ from OT. Team members familiar with OT-based editors (Google Docs, ShareDB) will need to adjust mental models. CRDTs guarantee eventual consistency without a central authority, which means conflict resolution is deterministic but may produce unexpected merges when two users restructure the same section simultaneously. Karen L. plans a 1-hour internal workshop to align the team on CRDT fundamentals before Sprint 1.

Alternatives Considered

Automerge

Automerge offers a theoretically cleaner CRDT model (JSON-like document structure) and the strongest offline-first story via its Rust core with WASM bindings. However, Automerge has no first-party ProseMirror binding. Building a custom binding was estimated at 3-4 weeks of dedicated engineering effort [fictional], and the WASM binary adds +120KB gzipped to the bundle [fictional] (3x the Yjs footprint). Enterprise CSP configurations may require additional IT approval for WASM loading, which introduces a deployment friction point for security-conscious customers.

Rejected: Integration cost (3-4 weeks custom binding + ongoing maintenance) exceeds the benefit. The team would carry first-mover maintenance risk without proportional advantage. If Automerge releases a first-party ProseMirror binding in the future, the team may revisit this decision.

ShareDB

ShareDB is an OT-based library that integrated with ProseMirror in 1.5 days (fastest of the three). Performance was acceptable (62ms merge latency at 20 concurrent editors [fictional]) and bundle size was the smallest (+22KB gzipped [fictional]).

Rejected: ShareDB requires a central server for conflict resolution and has no offline support. Edits made while disconnected are lost. This is a hard failure against the enterprise offline-first requirement and introduces a single point of failure. Even if offline support were not required, the central-server dependency means that a server outage would freeze all active editing sessions, an unacceptable risk for enterprise reliability expectations.

References