Skip to main content
This page defines the platform primitives used throughout Materi documentation. It is intentionally conceptual and links out to canonical specs when precision matters.

​
Workspaces

A workspace is the primary multi-tenant boundary for users, documents, and policy. What to expect:
  • Users are members of one or more workspaces.
  • Most document access decisions are made in the context of a workspace.

​
Users and identities

A user represents a human or system actor. Identity and access are centrally managed by the authentication/administration surface (Shield). High-level capabilities referenced in the repo documentation include:
  • JWT-based auth flows
  • SSO integrations (e.g., SAML) for enterprise
  • RBAC-style authorization concepts

​
Documents

A document is the primary collaborative unit. In Materi, documents are designed to support:
  • CRUD operations via the HTTP API
  • Real-time concurrent editing via WebSocket collaboration
  • Version history / lifecycle events

​
Real-time collaboration

Collaboration is handled as an always-on stream of operations rather than occasional edits. Core elements:
  • Session/connection: a client’s WebSocket presence within a document
  • Operation: an atomic edit submitted by a client
  • Transform: conflict resolution that reconciles concurrent operations
  • Presence: cursor/selection/user status propagated to other collaborators

​
Events

Events are emitted by services to synchronize work across boundaries. Guiding idea:
  • If a change must be observed by another service (or by downstream consumers), it becomes an event.

​
Event schemas (protobuf)

​
Event schemas (protobuf)

This snippet is generated from the canonical protobuf files in shared/proto. It is intended to be embedded into event reference pages to prevent drift.

​
Sources

  • shared/proto/base_event.proto (sha256:c26c3f9ec333)
  • shared/proto/chat_events.proto (sha256:6a277e157626)
  • shared/proto/collaboration_events.proto (sha256:26a3a9127ac2)
  • shared/proto/comment_events.proto (sha256:e98088c38431)
  • shared/proto/document_events.proto (sha256:acd296c95513)
  • shared/proto/unified_document_events.proto (sha256:b7a2d3f938ed)
  • shared/proto/user_events.proto (sha256:7d83b27678ca)
  • shared/proto/version_events.proto (sha256:256064645825)
  • shared/proto/workspace_events.proto (sha256:6016f8208ee0)

​
Message index

FileMessages
shared/proto/base_event.protoBaseEvent
shared/proto/chat_events.protoConversationCreatedEvent, ConversationUpdatedEvent, ConversationDeletedEvent, ConversationArchivedEvent, MessageSentEvent, MessageStreamStartedEvent, MessageStreamChunkEvent, MessageStreamCompletedEvent, MessageStreamErrorEvent, MessageRegeneratedEvent, MessageEditedEvent, MessageDeletedEvent, MessageFeedbackEvent, TypingIndicatorEvent, AIProcessingEvent, ContextAttachedEvent, ContextDetachedEvent, ContextAttachment, TextRange, TokenUsage, AIConfiguration
shared/proto/collaboration_events.protoOperationAppliedEvent, PresenceUpdateEvent, CursorMovedEvent, DocumentLockedEvent, DocumentUnlockedEvent, ConflictDetectedEvent, VectorClock, CursorPosition, SelectionRange, ViewportInfo
shared/proto/comment_events.protoCommentCreatedEvent, CommentUpdatedEvent, CommentDeletedEvent, CommentResolvedEvent, CommentReactionAddedEvent, CommentReactionRemovedEvent, CommentReplyAddedEvent, CommentThreadUpdatedEvent, CommentPosition, CommentBatchEvent
shared/proto/document_events.protoDocumentCreatedEvent, DocumentUpdatedEvent, DocumentDeletedEvent, DocumentSharedEvent, DocumentAccessRevokedEvent, DocumentExportedEvent, ShareRecipient
shared/proto/unified_document_events.protoUnifiedDocumentCreatedEvent, UnifiedDocumentConvertedEvent, ViewUpdatedEvent, ViewContentSyncEvent, ViewLayoutChangedEvent, EnabledViewsChangedEvent, VariableCreatedEvent, VariableUpdatedEvent, VariableDeletedEvent, VariableReferencedEvent, CrossViewSyncEvent, SharedVariable, VariableSource
shared/proto/user_events.protoUserCreatedEvent, UserUpdatedEvent, UserDeletedEvent, UserSuspendedEvent, UserReactivatedEvent, PermissionsChangedEvent, PasswordChangedEvent, EmailVerifiedEvent, LoginEvent, LogoutEvent
shared/proto/version_events.protoVersionCreatedEvent, VersionRestoredEvent, VersionComparedEvent, VersionHistoryAccessedEvent, VersionSnapshotCreatedEvent, VersionPrunedEvent, DiffStats, VersionBatchEvent
shared/proto/workspace_events.protoWorkspaceCreatedEvent, WorkspaceUpdatedEvent, WorkspaceDeletedEvent, MemberAddedEvent, MemberRemovedEvent, MemberRoleChangedEvent, WorkspaceInvitationSentEvent, WorkspaceInvitationAcceptedEvent, WorkspaceSubscriptionChangedEvent, WorkspaceSettings

​
OpenAPI (HTTP surface)

HTTP endpoints are defined by the OpenAPI spec published into this docs site:
  • /openapi/openapi.json

​
Security model (high level)

This documentation treats security as a first-class behavior:
  • Authentication: who you are
  • Authorization: what you can do
  • Auditability: what happened and who triggered it
Concrete endpoint shapes and auth requirements should always be validated against the canonical OpenAPI spec and the relevant service implementation.