Skip to main content

Core Concepts

Before integrating collaboration into your application, it's important to understand how everything works and fits together.


In the examples below, we will be make parallels to a typical chat application, such as Slack.


There are 6 main entities / data types the collaboration modules work with:

  • User
  • Document
  • Annotation
  • Document Member
  • Annotation Member
  • Mention


A user entity represents a single user in the application. A user must be signed in in order to perform actions like creating documents or annotations.


A document entity contains information about a certain document. It does not store the actual PDF document itself, or even the location of it.


You can think of a document as a "channel" in a typical chat application.


An annotation represents a single annotation in a PDF document. Each annotation belongs to a single document, and stores info like the annotation's XFDF, who created it, etc. When you load a document, all annotations that belong to that document are also loaded.


You can think of an annotation as a "message" in a typical chat application. Each message belongs to a channel (or in our case, a document).

Document Member#

A document member represents a user's membership to a document. Without being a member of a document, the user is unable to see that document (unless it is public).

There are three ways to become a member of a document.

  1. If you created the document
  2. If you were invited to the document
  3. The document is public and you join it

In a chat application like Slack, in order to read a private channel, you must "join" it via an invite from someone else. This is exactly how document membership works.

Annotation Member#

An annotation member is very similar to document members, except for annotations.

If you are a member of the document, then by default, you are then a member of all annotations that belong to that document.

Annotation member entities are used to track if a user has read a message or not.


Annotation members are only created when an annotation has been viewed


A mention represents a user mentioned in a Note annotation.

A mention overrides the notification and email settings of the annotation that it belongs to.

Application Flow#

In this section we are going to walk through a typical collaboration flow and show how the above data types fit into it.

For this example, let us pretend that we have 3 users signed up for our app:

Now, User 1 creates a new document. When the document is created, all annotations are extracted from the document, and an annotation entity is created for each annotation. We also create a document member for the user who created the document, as well as an annotation member for each annotation.

In this example, let us pretend that the document had 2 annotations:


Matching colors means that entity is associated with that user

As you can see, there is a new Document entity that associated with the user who created it (the author). There is also 2 new Annotation entities, one for each annotation in the document the user uploaded.

There are also 3 new membership entities associated with that user (2 Annotation Member and 1 Document Member). These memberships represent the user's membership to these entities.

Now, User 1 wants to invite User 2 to collaborate on that document. Let's see what our data looks like after this operation:

As you can see, this operation created 3 new entities.

The new Document Member shows that User 2 is now a member of this document and is now allowed to view it.

Once a user views the annotation, we also create an Annotation Member entity for them. This let us keep track of unread count, etc.

Now, let us pretend that user 1 adds an annotation to the document. Our data turns into this:

All we did here was add a new Annotation entity (representing the annotation that was just created), and a membership to that annotation for every member of the document.