Collaboration — shared project editing
Collaboration lets several participants open the same project: you can see who is present, their cursors on the floor plan, diagram and panel, and comments pinned to a point or element. Edits are synchronised over WebSocket and a CRDT engine, and geometry conflicts are resolved automatically.
Participant roles
Access is granted with one of three roles. The role is set when a link is created or an invitation is sent by email, and it can be revoked by the owner.
| Role | What the participant can do |
|---|---|
| viewer | View the project without editing |
| checker | View and comment (review) |
| co-editor | Collaborative editing |
How to use: step by step
- Open the project and create a sharing link: choose the role (viewer / checker / co-editor) and, if needed, an expiry in hours. A link cannot be created without an open project.
- Invite participants — send the link or an email invitation for the required role.
- The participant opens the link and confirms the connection in the consent dialog (once per tab). The dialog is shown only for verified addresses (see “Link security”).
- Work together: colleagues' cursors are visible on the canvas, comments are discussed right on the plan, and a co-editor's changes are applied to your model automatically.
- End access — revoke the participant's access or disable the link once the review is done. The participant list is visible to the project owner.
Cursors and presence
- Each participant's cursor has its own colour and name; you can see which view they are on: floor plan, single-line diagram or panel.
- The presence list shows who is online right now.
- If the connection drops, the client reconnects automatically after about 3 seconds and requests the missing changes from the server.
Comments
- A comment is pinned to a point on the plan (coordinates) or to an element (for example a breaker or an outlet), and you can mention participants.
- A comment has two statuses: “open” and “resolved”. Replies are stored inside the comment.
- The list can be filtered by status and by element — handy for reviewing remarks on a specific panel or room.
How synchronisation and conflicts work
Every edit is performed as a command and converted into CRDT operations (LWW registers, OR-sets, vector clocks with Lamport timestamps). The client applies the operation locally and broadcasts it as a delta message; on connect it requests what is missing (sync_request → sync_response), and the full state can arrive as a snapshot. Remote operations are applied to local storage automatically.
- Simultaneous edits of the same object are resolved deterministically (the newer timestamp wins).
- Geometry conflicts of walls and routes are handled by a separate resolver: intersections and overlaps do not make the model “fall apart”.
- An object being edited can be locked; the lock is released automatically after about 30 seconds, so locks never get stuck.
Link security
- Only verified addresses are allowed over WebSocket: wss:// — only the gorkycad.pro host and its subdomains; ws:// — only localhost and 127.0.0.1 for local development (for example ws://localhost:3001/collab). Anything else (http/https, foreign hosts, garbage) is rejected.
- The consent dialog never expands this list: a user's confirmation only works for an address that is already allowed.
- Consent is remembered per tab (sessionStorage, key gorkycad:collab-consent) — a new tab asks again. In private mode without storage access the dialog may repeat.
- For local development the address is switched to the local server before connecting (port 3001 by default).
Common errors
- “Project is not open” when creating a link or invitation — open the project first, then share.
- The link does not connect and the consent dialog does not appear — the address was rejected by the check (foreign host or http/https instead of wss). Make sure the link points to gorkycad.pro.
- No cursors or colleague's edits — the connection is not established yet or was interrupted; wait for the automatic reconnect and check the network.
- A comment is not visible — check the status filter (open/resolved) and the attachment to the element.
Limitations
- Live synchronisation requires being online: a WebSocket connection to the collaboration server.
- A guest without the co-editor role cannot edit the model (viewer — view only, checker — view and comment).
- A link may have an expiry; an expired link does not connect.
See also
Frequently asked questions
How do the viewer, checker and co-editor roles differ?
Viewer only views the project, checker views and leaves comments, co-editor edits the model together with the team.
A colleague opened the link but I cannot see them. What should I do?
Check that they confirmed the consent dialog, that the link has not expired, and that the connection is established (on a drop the client reconnects by itself within a few seconds).
What happens if the same object is edited at the same time?
A CRDT rule applies: the newer operation wins by timestamp, wall and route geometry is additionally handled by a resolver, and data is never silently lost.
Is it safe to open a link from an email?
The client connects only to gorkycad.pro (wss) or to localhost (ws, development). A link to a foreign server is rejected before the dialog is shown, and a foreign host is never substituted into the interface.