Real-Time Collaboration
The canvas editor supports multiple simultaneous editors with live cursors and conflict-free merging, built on TipTap + Yjs (a CRDT) transported over an API Gateway WebSocket API.
WebSocket API
The WebSocket API has three routes:
| Route | Purpose |
|---|---|
$connect | Authenticates the user (JWT) and joins them to a post's collaboration room. |
$disconnect | Removes the connection when the client leaves or times out. |
$default | Carries Yjs document updates, awareness (cursors/presence), and heartbeats. |
Connection flow
- The client opens a WebSocket connection, authenticating with its Cognito token.
- On
$connect, the Collab Lambda validates the token and records the connection in the connections table (with a TTL for automatic cleanup of stale sockets). - Clients exchange Yjs updates through
$default; the Lambda broadcasts each update to the other connections in the same room and persists document state. - On
$disconnect, the connection record is removed.
Yjs state persistence
The Yjs document for each post is persisted in the DynamoDB main table so that editing can resume after all clients disconnect and new joiners receive the current state. To keep document size bounded, update history is periodically compacted into a single consolidated state.
Frontend integration
The frontend binds the TipTap editor to a Yjs document and syncs it over the WebSocket. A custom hook manages the connection lifecycle, awareness (who is editing, where their cursor is), and reconnection, so authors get a smooth, Google-Docs-style editing experience.