> ## 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.

# Architecture overview

> Service boundaries, data flow, and canonical specs

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.

| Service    | Responsibility (summary)                                                   | Primary stack          | Code location                        |
| ---------- | -------------------------------------------------------------------------- | ---------------------- | ------------------------------------ |
| API        | REST/HTTP gateway for documents, workspaces, AI features; publishes events | Go (Fiber)             | `domain/api`                         |
| Relay      | WebSocket real-time collaboration; OT + presence; event-driven sync        | Rust (Axum)            | `domain/relay`                       |
| Shield     | Authentication/authorization, user management, admin                       | Python (Django)        | `domain/shield`                      |
| Manuscript | Schema/spec “single truth” (events, envelope)                              | Proto / schema tooling | `domain/manuscript` + `shared/proto` |
| Printery   | Event consumer hub (planned)                                               | Go                     | `domain/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

| 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`                                                                                                                                                                                                                                           |