​
Overview

Velt uses Organizations, Documents, and Locations to organize data and users into the same shared spaces and subspaces, enabling granular access controls. The data hierarchy in Velt follows this structure: Organization -> Documents -> Locations.

​
Organizations

An Organization is the top-level entity.
  • It contains documents, locations, and users.
  • Within an organization, you can create multiple documents, and each document can contain several locations.
Think of an organization as a Google Account belonging to a company (e.g., Company A). This account may have several users (Company A employees). A document will be any file created within the organization (e.g., document, spreadsheet, slides, etc.). A location will be any child section within the document (e.g., slide within a presentation).

​
Documents

A Document represents a shared collaborative space where users can interact. Documents live inside the Organization. Documents contain:
  • All feature data (e.g., Comments, Presence, Cursors, etc.).
  • Locations
  • Users: These are different from Organization Users. (more details in Access Control section)
Users logged into the same Document ID can see each other’s Presence, Cursors, Comments etc. For example, in a slide presentation application, the entire slide deck is a document.

​
Locations

Locations are optional subspaces within a document, providing finer partitioning of data. For instance:
  • In a slide presentation, the entire slide presentation will be a document each individual slide will be a location.
  • In a dashboard, the entire dashboard is a document but various filters applied will be locations;
  • In a video player, the entire video will be the document and timestamps will be locations.
If a Document is like a house, a Location is like a room within the house.
Locations are completely optional, you can opt to use them or not. If the complexity of your application does not require the use of Locations, you can use Documents by themselves to group your users together. If you opt to use Locations, users in the same Document must also be in the same Location now to interact.

​
Users

A User represents a person who has been authenticated with the Velt SDK. Once a User has been authenticated, their profile can be seen within Velt’s collaboration features. For example in the Comments feature, the User's name is shown by their comment and in @mentions. Additionally in the Presence and in Cursors features, the User's name is shown by their avatar bubble and mouse cursors. There can be two categories of users:
  1. Organization Users: These belong to the organization and by default have access to organization documents and locations. You can control access to documents and locations at a more granular level for these users.
  2. Guest Users: For some use cases, you may want non-organization users to access and collaborate on a document within the organization. Using our access control features, you can provide access to guest users to only certain documents and user contacts within the organization.

​
Contact List for @mention

When the user is on a document, they can @mention other users. By default, the contact list for the @mention feature includes users from:
  • Organization users.
  • Guest users explicitly added to the current document.
  • Organization User Groups.
  • @here: This is a special group that includes only the users explicitly added on the document. This doesn’t include organization users or organization user groups.
Contact list is automatically updated:
  • as users are added or removed from the organization or the document.
  • organization user groups are created or updated.
Access Control: Using the access control features, you can control which users are visible on the contact list on a given document.
  • Organization users can access the entire Organization contact list on a given organization document.
  • Guest (Non-organization) users who were granted access to an organization document cannot access the Organization contact list. If you want to show some organization contacts to these guest users, then you need to explicitly add them to the document.

​
Organization User Groups

You can create custom collection of users such as engineering, marketing etc to group organization users and manage access effectively.
  • This can be used to @mention a team group versus just individuals (just like in Slack).
  • This can also be used to provision access to documents.
  • Organization users can belong to multiple organization user groups.
  • Non-organization users can’t be part of organization user groups.