DocuSphere stores document metadata (title, owner, organization) in Convex. The actual rich-text content of each document is stored and synchronized by Liveblocks, not Convex. Convex and Liveblocks work together: Convex manages who can access a document, and Liveblocks handles the real-time editing state.
The documents table
All document metadata lives in a singledocuments table. Each row represents one document.
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Yes | The document’s display name. Shown in the dashboard and document header. |
initialContent | string | No | Initial HTML content to pre-populate the editor. Used when creating a document from a template. |
ownerId | string | Yes | The Clerk user ID of the person who created the document. |
roomId | string | No | The Liveblocks room ID associated with this document. Used to connect the editor to the correct collaboration room. |
organizationId | string | No | The Clerk organization ID. Set when the document is created while an organization is the active context in the switcher. Documents with an organizationId are visible to all members of that organization. |
Indexes
Convex uses indexes to make queries fast. Thedocuments table has three:
by_owner_id— indexed onownerId. Used when listing all documents belonging to a specific user.by_organization_id— indexed onorganizationId. Used when listing all documents belonging to a specific organization.search_title— a full-text search index on thetitlefield, filterable byownerIdororganizationId. Powers the title search in the document dashboard.
Available queries and mutations
DocuSphere exposes the following Convex functions viaapi.documents:
Creates a new document. Accepts an optional
title (defaults to “Untitled Document”) and optional initialContent string. Automatically sets ownerId from the authenticated user and organizationId from their active organization context.Returns a paginated list of documents for the current user or organization. Accepts an optional
search string to filter by title using the search_title index.Fetches a single document by its Convex document ID. Throws a
ConvexError with “Document not found” if the document does not exist. Note: this query does not perform an auth check itself — access control is enforced at the Liveblocks auth layer.Fetches multiple documents by an array of Convex document IDs. Useful for bulk lookups, such as loading recently accessed documents.
Renames a document. Accepts the document ID and a new
title. Checks that the caller is the document owner or a member of the document’s organization before applying the change.Permanently deletes a document. Accepts the document ID. Checks that the caller is the document owner or a member of the document’s organization before deleting.
Real-time sync
Convex queries are reactive by default. When you calluseQuery(api.documents.get, ...) in the UI, Convex automatically pushes updates to the component whenever the underlying data changes — no polling or manual refetching required. This means your document list updates instantly when a document is created, renamed, or deleted anywhere in the system.