Real-Time Editing

How It Works

ERDHub uses Yjs CRDT (Conflict-free Replicated Data Type) for real-time text collaboration. Yjs is a high-performance library that enables multiple users to edit the same document simultaneously without conflicts.

When multiple users edit the same diagram:

• Every keystroke is synced instantly via Firebase -- there is no save button or manual sync step
• Conflicts are resolved automatically using CRDT algorithms -- no merge conflicts, ever
• Each user sees live cursors and selections from all other active collaborators
• The schema, canvas positions, and editor state are all kept in sync

Why CRDT?

Traditional real-time editing uses Operational Transformation (OT), which requires a central server to resolve conflicts. CRDTs are mathematically guaranteed to converge to the same state regardless of the order operations are received. This means:

• No central conflict resolution server needed
• Edits can be applied in any order and still produce the same result
• Network delays or reordering never cause inconsistencies

Presence Indicators

When collaborating, you'll see several visual indicators of other users' activity:

• Avatar stack -- profile pictures of everyone currently viewing the diagram, shown in the header
• Live cursors -- colored cursors in the code editor showing where each user's cursor is positioned
• Typing indicator -- shows who is actively typing in the editor
• Table selection -- on the ERD canvas, highlights which table each collaborator has selected with their assigned color

Each collaborator is assigned a unique color that is consistent across all presence indicators.

Connection States

The connection indicator in the header reflects your current sync status. ERDHub uses a state machine to manage the connection lifecycle:

State	Indicator	Duration	Behavior
Connected	Green dot	--	Full real-time sync active
Syncing	Yellow dot	Brief	Sending or receiving pending changes
Reconnecting	Orange dot	Up to 30 seconds	Temporary connection loss, auto-reconnecting
Offline	Red dot	After 30 seconds	Connection lost, working locally

Connection State Flow

Connected → (connection drops) → Reconnecting (≤30s) → Offline (>30s)
                                       ↓
                               (connection restores)
                                       ↓
                                  Connected

Reconnection Behavior

When the connection drops:

1. Immediate (0--30s): ERDHub enters the Reconnecting state. A banner appears below the header indicating the connection is being restored. Your edits continue to work locally and are queued for sync.

2. Extended (>30s): If reconnection fails after 30 seconds, the state transitions to Offline. The banner updates to indicate you are working offline. All edits are preserved in the local Yjs document.

3. Restored: When the connection comes back, all locally queued edits are synced automatically. A "Back online" toast notification confirms that sync is complete. No data is lost.

TIP

You can continue editing your diagram while offline. All changes are preserved locally in the browser and will sync automatically when connectivity is restored.

WARNING

If two users edit the same line while offline, Yjs will merge both edits when they reconnect. The result is deterministic (both users see the same outcome), but you should review the merged content to ensure it makes sense.

Requirements

Real-time collaboration requires:

1. A saved project -- click Save to persist your diagram before sharing
2. A signed-in account -- anonymous users cannot participate in real-time editing
3. At least one other collaborator -- either an invited collaborator on a personal project, or a fellow workspace member on a workspace project

Collaborator Limits

Plan	Collaborators per Project
Free	Up to 4
Pro	Unlimited
Team	All workspace members (managed via workspace settings)