Collaboration

Drawfinity supports real-time collaborative drawing. Multiple users can connect to the same room and see each other's strokes appear instantly. All synchronization is conflict-free — there are no merge conflicts, no locking, and no data loss.

How It Works

Collaboration is built on Yjs, a CRDT (Conflict-free Replicated Data Type) library. Every stroke on the canvas is stored in a shared Yjs document. When you draw, your strokes are encoded as Yjs updates and sent to other connected clients through a WebSocket relay server.

The key properties of CRDT sync:

• No conflicts — concurrent edits from different users are automatically merged.
• Offline-tolerant — if you lose connection, your local edits are preserved and synced when you reconnect.
• Order-independent — updates can arrive in any order and the final document state is the same for everyone.

Connecting to a Room

1. Press Ctrl+K to open the connection panel (or click the connection icon in the toolbar).
2. Enter the server URL — the address of a running Drawfinity collaboration server (e.g., ws://localhost:8080).
3. Enter a room name — any string that identifies the shared drawing session. Everyone who joins the same room sees the same canvas.
4. Click Connect.

The connection indicator in the toolbar shows your current status:

Status	Meaning
Connected	Live connection, strokes sync in real time
Connecting	Establishing the WebSocket connection
Reconnecting	Connection lost, automatically retrying with exponential backoff
Failed	Reconnection attempts exhausted — click to retry manually
Disconnected	Not connected to any room

What Syncs

Everything that is part of the drawing document syncs between collaborators:

• Brush strokes — including color, width, opacity, and pressure data
• Shape strokes — rectangles, ellipses, polygons, stars
• Eraser strokes — deletions propagate to all clients
• Undo/redo — each user has their own undo stack; undoing a stroke removes it for everyone
• Turtle graphics output — strokes generated by turtle scripts are regular document strokes and sync normally

What Does Not Sync

• Camera position — each user has their own pan/zoom view
• Tool selection — your current brush, color, and size are local
• Turtle scripts — the code you write in the turtle panel is local; only the resulting strokes sync
• Settings — dot grid, FPS counter, and other preferences are per-client

Room Management

Rooms are created on-demand when the first client connects. The server also provides a REST API for managing rooms:

Endpoint	Method	Description
/api/rooms	GET	List all active rooms with client counts
/api/rooms	POST	Create a named room (body: {"name": "...", "creator_name": "..."})
/api/rooms/:id	GET	Get details for a specific room

Room state is persisted to disk. If the server restarts, rooms are restored from their last saved state. Empty rooms are cleaned up after 30 seconds of inactivity.

Architecture Overview

┌──────────┐     WebSocket      ┌─────────────────┐     WebSocket      ┌──────────┐
│ Client A │ ◄────────────────► │  Drawfinity     │ ◄────────────────► │ Client B │
│ (Browser) │    Yjs updates     │  Server (Rust)  │    Yjs updates     │ (Browser) │
└──────────┘                    └────────┬────────┘                    └──────────┘
                                         │
                                         ▼
                                    ┌──────────┐
                                    │   Disk   │
                                    │ (.bin +  │
                                    │  .json)  │
                                    └──────────┘

The server is a stateless WebSocket relay:

1. A client connects to /ws/:room_id and receives the current document state.
2. When a client draws, the Yjs update is sent as a binary WebSocket message.
3. The server broadcasts the update to all other clients in the room.
4. The server accumulates document state in memory and persists it to disk with debounced writes (every 5 seconds).

See Server Setup for deployment instructions.

Tips

• Low latency matters — host the server close to your collaborators for the best experience.
• Works across networks — as long as all clients can reach the server, they can collaborate. Use a reverse proxy with TLS for production deployments.
• Large drawings — CRDT state grows with the number of operations. For very large collaborative sessions, the initial sync when joining may take a moment.