Real-time Collaboration

ArchDoc supports real-time collaboration, allowing multiple users to edit documents simultaneously.

How It Works

Technology Stack

• Yjs: Conflict-free replicated data type (CRDT)
• Hocuspocus: WebSocket server for synchronization
• TipTap Collaboration: Editor integration

What Happens

1. When you open a document, you connect to the collaboration server
2. Your edits are synchronized with other connected users
3. Changes appear in real-time for everyone
4. Conflicts are automatically resolved by the CRDT

Collaboration Features

Presence Indicators

See who's currently viewing the document:

• Avatars appear in the document header
• Shows all connected users
• Updates in real-time as people join/leave

Live Cursors

See where others are working:

• Each user has a colored cursor
• Cursor shows their name
• See their selections in real-time

Synchronized Content

All edits sync immediately:

• Typing appears for everyone
• Formatting changes sync
• No manual refresh needed

Using Collaboration

Joining a Document

Simply open a document—collaboration starts automatically:

1. Navigate to the document
2. You'll see a connection indicator
3. Other users will see you appear

Seeing Other Users

Look for:

• Avatar circles in the header
• Colored cursors in the content
• Selection highlights

Making Edits

Just edit normally:

• Your changes appear for others instantly
• Their changes appear for you instantly
• No conflicts or overwrites

Cursor Colors

Each user gets a unique color:

Colors are assigned randomly but consistently per session.

Connection Status

The editor shows your connection state:

If Disconnected

• Your edits are saved locally
• When reconnected, changes sync automatically
• No work is lost

Best Practices

Communicate

• Let team members know you're editing
• Coordinate on who's working on what section
• Use comments for discussions

Work in Different Sections

• Reduces cursor confusion
• Minimizes overlapping edits
• More efficient collaboration

Save Regularly

• While auto-sync handles content
• Manual saves create version history
• Good practice before major changes

Be Patient with Slow Connections

• Sync may take a moment on slow networks
• Wait for connection indicator
• Avoid rapid, conflicting edits

Offline Behavior

If you lose connection:

1. Keep Working: Edits are cached locally
2. Changes Preserved: Nothing is lost
3. Auto-Sync: When reconnected, changes merge
4. Conflict-Free: CRDT ensures no conflicts

Collaboration Permissions

All team members can collaborate on documents.

Troubleshooting

Not Seeing Other Users

• Check your network connection
• Ensure others are on the same document
• Try refreshing the page

Edits Not Syncing

• Check connection status indicator
• Verify WebSocket connection
• Clear browser cache and retry

Cursor Lag

• Normal on slow connections
• Edits still sync correctly
• May be slightly delayed

Too Many Collaborators

• Many simultaneous editors can be overwhelming
• Coordinate editing sessions
• Use comments for async collaboration

When to Use Collaboration

Good For

• Pair writing sessions
• Live review meetings
• Quick collaborative edits
• Real-time brainstorming

Consider Async Instead

• Deep focused writing
• Major restructuring
• When coordinating is difficult
• With very slow connections

Technical Notes

WebSocket Connection

• Connects to collaboration server
• Maintains persistent connection
• Handles reconnection automatically

Data Sync

• Uses Yjs CRDT for conflict resolution
• All operations commute (order doesn't matter)
• Guaranteed eventual consistency

Security

• Authenticated connections only
• Company isolation enforced
• Access validated per document