> ## Documentation Index
> Fetch the complete documentation index at: https://try.materi.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

> Core primitives: workspaces, documents, events, collaboration, security

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

| File                                         | Messages                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shared/proto/base_event.proto`              | `BaseEvent`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `shared/proto/chat_events.proto`             | `ConversationCreatedEvent`, `ConversationUpdatedEvent`, `ConversationDeletedEvent`, `ConversationArchivedEvent`, `MessageSentEvent`, `MessageStreamStartedEvent`, `MessageStreamChunkEvent`, `MessageStreamCompletedEvent`, `MessageStreamErrorEvent`, `MessageRegeneratedEvent`, `MessageEditedEvent`, `MessageDeletedEvent`, `MessageFeedbackEvent`, `TypingIndicatorEvent`, `AIProcessingEvent`, `ContextAttachedEvent`, `ContextDetachedEvent`, `ContextAttachment`, `TextRange`, `TokenUsage`, `AIConfiguration` |
| `shared/proto/collaboration_events.proto`    | `OperationAppliedEvent`, `PresenceUpdateEvent`, `CursorMovedEvent`, `DocumentLockedEvent`, `DocumentUnlockedEvent`, `ConflictDetectedEvent`, `VectorClock`, `CursorPosition`, `SelectionRange`, `ViewportInfo`                                                                                                                                                                                                                                                                                                        |
| `shared/proto/comment_events.proto`          | `CommentCreatedEvent`, `CommentUpdatedEvent`, `CommentDeletedEvent`, `CommentResolvedEvent`, `CommentReactionAddedEvent`, `CommentReactionRemovedEvent`, `CommentReplyAddedEvent`, `CommentThreadUpdatedEvent`, `CommentPosition`, `CommentBatchEvent`                                                                                                                                                                                                                                                                |
| `shared/proto/document_events.proto`         | `DocumentCreatedEvent`, `DocumentUpdatedEvent`, `DocumentDeletedEvent`, `DocumentSharedEvent`, `DocumentAccessRevokedEvent`, `DocumentExportedEvent`, `ShareRecipient`                                                                                                                                                                                                                                                                                                                                                |
| `shared/proto/unified_document_events.proto` | `UnifiedDocumentCreatedEvent`, `UnifiedDocumentConvertedEvent`, `ViewUpdatedEvent`, `ViewContentSyncEvent`, `ViewLayoutChangedEvent`, `EnabledViewsChangedEvent`, `VariableCreatedEvent`, `VariableUpdatedEvent`, `VariableDeletedEvent`, `VariableReferencedEvent`, `CrossViewSyncEvent`, `SharedVariable`, `VariableSource`                                                                                                                                                                                         |
| `shared/proto/user_events.proto`             | `UserCreatedEvent`, `UserUpdatedEvent`, `UserDeletedEvent`, `UserSuspendedEvent`, `UserReactivatedEvent`, `PermissionsChangedEvent`, `PasswordChangedEvent`, `EmailVerifiedEvent`, `LoginEvent`, `LogoutEvent`                                                                                                                                                                                                                                                                                                        |
| `shared/proto/version_events.proto`          | `VersionCreatedEvent`, `VersionRestoredEvent`, `VersionComparedEvent`, `VersionHistoryAccessedEvent`, `VersionSnapshotCreatedEvent`, `VersionPrunedEvent`, `DiffStats`, `VersionBatchEvent`                                                                                                                                                                                                                                                                                                                           |
| `shared/proto/workspace_events.proto`        | `WorkspaceCreatedEvent`, `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.