penpot/docs/99-Collaborative-Edition.md

Collaborative Edition & Persistence protocol

This is a collection of design notes for collaborative edition feature and persistence protocol.

Persistence Operations

This is a page data structure:

{:version 2
 :options {}

 :rmap
 {:id1 :default
  :id2 :default
  :id3 :id1}

 :objects
 {:root
  {:type :root
   :shapes [:id1 :id2]}

  :id1
  {:type :canvas
   :shapes [:id3]}

  :id2 {:type :rect}
  :id3 {:type :circle}}}

This is a potential list of persistent ops:

{:type :mod-opts
 :operations [<op>, ...]

{:type :add-obj
 :id <uuid>
 :parent <uuid>
 :obj <shape-object>}

{:type :mod-obj
 :id   <uuid>
 :operations [<op>, ...]}

{:type :mov-obj
 :id <uuid>
 :dest <uuid>}

{:type :del-obj
 :id   <uuid>}

This is a potential list of operations:

{:type :set
 :attr <any>
 :val  <any>}

{:type :mov
 :id <uuid>
 :index <int>}

Ephemeral communication (Websocket protocol)

join

Sent by clients for notify joining a concrete page-id inside a file.

{:type :join
 :page-id <id>
 :version <number>
 }

Will cause:

• A posible :page-changes.
• Broadcast :joined message to all users of the file.

The joined message has this aspect:

{:type :joined
 :page-id <id>
 :user-id <id>
 }

who

Sent by clients for request the list of users in the channel.

{:type :who}

Will cause:

• Reply to the client with the current users list:

{:type :who
 :users #{<id>,...}}

This will be sent all the time user joins or leaves the channel for maintain the frontend updated with the lates participants. This message is also sent at the beggining of connection from server to client.

pointer-update

This is sent by client to server and then, broadcasted to the rest of channel participants.

{:type :pointer-update
 :page-id <id>
 :x <number>
 :y <number>
 }

The server broadcast message will look like:

{:type :pointer-update
 :user-id <id>
 :page-id <id>
 :x <number>
 :y <number>
 }

:page-snapshot

A message that server sends to client for notify page changes. It can be sent on join and when a page change is commited to the database.

{:type :page-snapshot
 :user-id <id>
 :page-id <id>
 :version <number>
 :operations [<op>, ...]
 }

This message is only sent to users that does not perform this change.