Concepts
The four ideas the library is built on — the document as the unit of everything, convergence as a property of the data structure, one permission seam enforced on both paths, and the line between CRDT state and ordinary data.
Four ideas carry the whole library. Everything else in these docs is a consequence of one of them.
The document is the unit
Everything is keyed by a document name — a path-like string such as
researches/42/writing. That single string decides which CRDT engine syncs it, which
authorization rule guards it, which row it persists to, which comment threads belong to it, and who
counts as present in it. There is no other identifier, and there is no document registry to keep in
sync: a name that matches a declared pattern is a document, and one that doesn't falls through to
the global rule. See Documents.
Convergence is structural, not arbitrated
Two people editing the same paragraph is not a conflict the server resolves — it is a merge the data structure defines. A CRDT guarantees that replicas which have seen the same operations, in any order, hold the same state. That is why there is no "last write wins", no locking, and no server opinion about whose edit was real. The library's job shrinks to moving bytes and persisting them. See CRDTs.
One permission seam, crossed twice
A browser cannot attach an Authorization header to a WebSocket handshake, so the client asks for
a short-lived credential over REST first. That gives an attacker two doors to try — and the
library puts the same authorize callback behind both of them. It is also fail-closed: a
document matching no rule is denied, not allowed. See
Authorization.
CRDT state and ordinary data are different things
The shared content lives in the CRDT because many people write it concurrently. Comments, named versions and the presence roster do not: they are created one at a time, they need to be queried, filtered and joined, and they need permission checks that a merge algorithm cannot express. So they live in your database and travel over REST, alongside the document rather than inside it. The consequence you feel day to day: comments keep working while the WebSocket is down, and a version is a row you can list without materializing the document. See Versions, Comments and Presence.
Getting started
Install @adonis-agora/collaboration, write config/collaboration.ts, authorize a document, choose a storage backend, scaffold the tables, and open your first shared editor.
CRDTs
Why a conflict-free replicated data type removes the conflict instead of resolving it, what Yjs and Automerge each model, and the three consequences that show up in your application code.