Skip to main content
Materi is organized as an event-driven system with a REST gateway, a real-time collaboration service, and an authentication/administration service. At a high level, the platform combines HTTP APIs with WebSocket collaboration, and uses Redis Streams for cross-service synchronization.

​
Service map (high level)

The canonical service list and responsibilities live in the monorepo docs; this page is the reader-friendly map.
ServiceResponsibility (summary)Primary stackCode location
APIREST/HTTP gateway for documents, workspaces, AI features; publishes eventsGo (Fiber)domain/api
RelayWebSocket real-time collaboration; OT + presence; event-driven syncRust (Axum)domain/relay
ShieldAuthentication/authorization, user management, adminPython (Django)domain/shield
ManuscriptSchema/spec “single truth” (events, envelope)Proto / schema toolingdomain/manuscript + shared/proto
PrinteryEvent consumer hub (planned)Godomain/printery

​
Data flow patterns

​
1) Request/response (HTTP)

Typical workflow:
  1. A client calls the API over HTTP.
  2. Authorization is enforced using the system’s auth model (see Shield responsibilities).
  3. The API persists domain state (e.g., document/workspace changes).
  4. The API publishes a cross-service event to Redis Streams when the change matters outside the service boundary.

​
2) Real-time collaboration (WebSocket)

Typical workflow:
  1. Clients connect to Relay via WebSocket.
  2. Concurrent edits are coordinated using an operational transform approach.
  3. Presence (cursor/selection) updates are streamed to connected clients.
  4. Collaboration actions that must be reflected system-wide are published as events.

​
3) Event-driven synchronization

Events are the primary mechanism for keeping services in sync without tight coupling.
  • Transport: Redis Streams
  • Schemas: Protocol Buffers (polyglot-safe)

​
Canonical specifications

​
OpenAPI

The API reference for REST is generated from the OpenAPI spec published into this docs site:
  • /openapi/openapi.json

​
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