# its-dorra/dotion architecture

> Architecture diagram of the GitHub repository its-dorra/dotion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/its-dorra/dotion
- Repository: https://github.com/its-dorra/dotion

## Overview

Dotion is a real-time collaborative workspace. Users enter through the web app, select a workspace, and work with pages; that workflow extends into editing, sharing, comments, search, and AI assistance. The server provides domain APIs and realtime coordination, while services apply authorization and domain logic over repositories and PostgreSQL. The README also documents file storage, background indexing and cleanup, and event/outbox processing. Several server-to-service and route-to-handler links are not visible in the excerpts, so those connections are omitted rather than inferred.

Main entry points: [`apps/server/src/routes/workspaces/pages/routes.ts`](https://github.com/its-dorra/dotion/blob/main/apps/server/src/routes/workspaces/pages/routes.ts) (Page API), [`apps/web/src/routes/app/workspaces/$workspaceId/route.tsx`](https://github.com/its-dorra/dotion/blob/main/apps/web/src/routes/app/workspaces/%24workspaceId/route.tsx) (Web application), [`packages/services/src/pages.service.ts`](https://github.com/its-dorra/dotion/blob/main/packages/services/src/pages.service.ts) (Page service), [`packages/services/src/search.service.ts`](https://github.com/its-dorra/dotion/blob/main/packages/services/src/search.service.ts) (Search and indexing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workspace"]
  node_webapp["Web application<br/>[route.tsx]"]
  node_pageui["Page editing<br/>[api.ts]"]
  node_workspaceui["Workspace features<br/>[api.ts]"]
  node_searchui["Search interface"]
  node_assistantui["AI assistant"]
  node_commentsui["Comments interface"]
end

subgraph group_server["Server domains"]
  node_server["HTTP application<br/>[app.ts]"]
  node_pagesapi["Page API<br/>[routes.ts]"]
  node_workspaceapi["Workspace API<br/>[routes.ts]"]
  node_assistantapi["Assistant API<br/>[routes.ts]"]
  node_commentsapi["Comments API<br/>[routes.ts]"]
end

subgraph group_services["Domain services"]
  node_authz["Authorization"]
  node_pagesvc["Page service<br/>[pages.service.ts]"]
  node_workspacesvc["Workspace service"]
  node_searchsvc["Search and indexing<br/>[search.service.ts]"]
  node_embedding["Embedding generation"]
  node_storage["File storage<br/>[storage.service.ts]"]
end

subgraph group_data["Persistence and jobs"]
  node_db[("PostgreSQL repositories")]
  node_queue["Background queues<br/>[index.ts]"]
end

subgraph group_shared["Realtime and contracts"]
  node_realtime["Realtime coordination<br/>[durable-object.ts]"]
  node_events["Outbox and events<br/>[index.ts]"]
  node_sharedschemas["Shared schemas<br/>[index.ts]"]
end

node_user(("Workspace user"))
node_r2[("Cloudflare R2")]
node_postgres[("Neon PostgreSQL")]
node_cloudflarequeue["Cloudflare Queues"]

node_user -->|"uses"| node_webapp
node_webapp -->|"opens pages"| node_pageui
node_webapp -->|"opens search"| node_searchui
node_webapp -->|"opens assistant"| node_assistantui
node_pageui -.->|"requests pages"| node_pagesapi
node_workspaceui -.->|"requests workspaces"| node_workspaceapi
node_commentsui -.->|"requests comments"| node_commentsapi
node_searchui -.->|"searches workspace"| node_server
node_assistantui -.->|"streams chat"| node_assistantapi
node_server -.->|"routes requests"| node_pagesapi
node_pagesapi -.->|"delegates page work"| node_pagesvc
node_workspaceapi -.->|"delegates workspace work"| node_workspacesvc
node_assistantapi -.->|"retrieves context"| node_searchsvc
node_pagesvc -->|"accesses repositories"| node_db
node_workspacesvc -.->|"persists workspace data"| node_db
node_searchsvc -->|"reads and indexes"| node_db
node_searchsvc -->|"generates vectors"| node_embedding
node_pagesvc -.->|"checks access"| node_authz
node_pagesapi -.->|"coordinates collaboration"| node_realtime
node_realtime -.->|"syncs edits"| node_user
node_server -.->|"handles uploads"| node_storage
node_storage -->|"stores files"| node_r2
node_pagesvc -.->|"emits domain events"| node_events
node_events -.->|"dispatches jobs"| node_cloudflarequeue
node_cloudflarequeue -.->|"delivers jobs"| node_queue
node_queue -.->|"indexes pages"| node_searchsvc
node_queue -.->|"cleans assets"| node_storage
node_db -.->|"queries"| node_postgres
node_pagesapi -.->|"validates contracts"| node_sharedschemas

click node_webapp "https://github.com/its-dorra/dotion/blob/main/apps/web/src/routes/app/workspaces/%24workspaceId/route.tsx"
click node_pageui "https://github.com/its-dorra/dotion/blob/main/apps/web/src/features/pages/api.ts"
click node_workspaceui "https://github.com/its-dorra/dotion/blob/main/apps/web/src/features/workspaces/api.ts"
click node_searchui "https://github.com/its-dorra/dotion/tree/main/apps/web/src/features/search"
click node_assistantui "https://github.com/its-dorra/dotion/tree/main/apps/web/src/features/ai-assistant"
click node_commentsui "https://github.com/its-dorra/dotion/tree/main/apps/web/src/features/comments"
click node_server "https://github.com/its-dorra/dotion/blob/main/apps/server/src/app.ts"
click node_pagesapi "https://github.com/its-dorra/dotion/blob/main/apps/server/src/routes/workspaces/pages/routes.ts"
click node_workspaceapi "https://github.com/its-dorra/dotion/blob/main/apps/server/src/routes/workspaces/routes.ts"
click node_assistantapi "https://github.com/its-dorra/dotion/blob/main/apps/server/src/routes/workspaces/assistant/routes.ts"
click node_commentsapi "https://github.com/its-dorra/dotion/blob/main/apps/server/src/routes/workspaces/pages/comments/routes.ts"
click node_realtime "https://github.com/its-dorra/dotion/blob/main/apps/server/src/routes/workspaces/pages/durable-object.ts"
click node_authz "https://github.com/its-dorra/dotion/blob/main/packages/services/src/authorization/authorization.service.ts"
click node_pagesvc "https://github.com/its-dorra/dotion/blob/main/packages/services/src/pages.service.ts"
click node_workspacesvc "https://github.com/its-dorra/dotion/blob/main/packages/services/src/workspaces.service.ts"
click node_searchsvc "https://github.com/its-dorra/dotion/blob/main/packages/services/src/search.service.ts"
click node_embedding "https://github.com/its-dorra/dotion/blob/main/packages/services/src/embedding.service.ts"
click node_storage "https://github.com/its-dorra/dotion/blob/main/packages/services/src/storage.service.ts"
click node_db "https://github.com/its-dorra/dotion/tree/main/packages/db/src/repositories"
click node_queue "https://github.com/its-dorra/dotion/blob/main/apps/server/src/queues/index.ts"
click node_events "https://github.com/its-dorra/dotion/blob/main/apps/server/src/events/index.ts"
click node_sharedschemas "https://github.com/its-dorra/dotion/blob/main/packages/shared/src/events/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_pageui,node_workspaceui,node_searchui,node_assistantui,node_commentsui,node_user toneBlue
class node_server,node_pagesapi,node_workspaceapi,node_assistantapi,node_commentsapi,node_r2,node_postgres toneAmber
class node_authz,node_pagesvc,node_workspacesvc,node_searchsvc,node_embedding,node_storage toneMint
class node_db,node_queue,node_cloudflarequeue toneRose
class node_realtime,node_events,node_sharedschemas toneIndigo
```

## Components

### Web workspace

- [Web application](https://github.com/its-dorra/dotion/blob/main/apps/web/src/routes/app/workspaces/%24workspaceId/route.tsx): `apps/web/src/routes/app/workspaces/$workspaceId/route.tsx`
- [Page editing](https://github.com/its-dorra/dotion/blob/main/apps/web/src/features/pages/api.ts): `apps/web/src/features/pages/api.ts`
- [Workspace features](https://github.com/its-dorra/dotion/blob/main/apps/web/src/features/workspaces/api.ts): `apps/web/src/features/workspaces/api.ts`
- [Search interface](https://github.com/its-dorra/dotion/tree/main/apps/web/src/features/search): `apps/web/src/features/search`
- [AI assistant](https://github.com/its-dorra/dotion/tree/main/apps/web/src/features/ai-assistant): `apps/web/src/features/ai-assistant`
- [Comments interface](https://github.com/its-dorra/dotion/tree/main/apps/web/src/features/comments): `apps/web/src/features/comments`

### Server domains

- [HTTP application](https://github.com/its-dorra/dotion/blob/main/apps/server/src/app.ts): `apps/server/src/app.ts`
- [Page API](https://github.com/its-dorra/dotion/blob/main/apps/server/src/routes/workspaces/pages/routes.ts): `apps/server/src/routes/workspaces/pages/routes.ts`
- [Workspace API](https://github.com/its-dorra/dotion/blob/main/apps/server/src/routes/workspaces/routes.ts): `apps/server/src/routes/workspaces/routes.ts`
- [Assistant API](https://github.com/its-dorra/dotion/blob/main/apps/server/src/routes/workspaces/assistant/routes.ts): `apps/server/src/routes/workspaces/assistant/routes.ts`
- [Comments API](https://github.com/its-dorra/dotion/blob/main/apps/server/src/routes/workspaces/pages/comments/routes.ts): `apps/server/src/routes/workspaces/pages/comments/routes.ts`

### Domain services

- [Authorization](https://github.com/its-dorra/dotion/blob/main/packages/services/src/authorization/authorization.service.ts): `packages/services/src/authorization/authorization.service.ts`
- [Page service](https://github.com/its-dorra/dotion/blob/main/packages/services/src/pages.service.ts): `packages/services/src/pages.service.ts`
- [Workspace service](https://github.com/its-dorra/dotion/blob/main/packages/services/src/workspaces.service.ts): `packages/services/src/workspaces.service.ts`
- [Search and indexing](https://github.com/its-dorra/dotion/blob/main/packages/services/src/search.service.ts): `packages/services/src/search.service.ts`
- [Embedding generation](https://github.com/its-dorra/dotion/blob/main/packages/services/src/embedding.service.ts): `packages/services/src/embedding.service.ts`
- [File storage](https://github.com/its-dorra/dotion/blob/main/packages/services/src/storage.service.ts): `packages/services/src/storage.service.ts`

### Persistence and jobs

- [PostgreSQL repositories](https://github.com/its-dorra/dotion/tree/main/packages/db/src/repositories): `packages/db/src/repositories`
- [Background queues](https://github.com/its-dorra/dotion/blob/main/apps/server/src/queues/index.ts): `apps/server/src/queues/index.ts`

### Realtime and contracts

- [Realtime coordination](https://github.com/its-dorra/dotion/blob/main/apps/server/src/routes/workspaces/pages/durable-object.ts): `apps/server/src/routes/workspaces/pages/durable-object.ts`
- [Outbox and events](https://github.com/its-dorra/dotion/blob/main/apps/server/src/events/index.ts): `apps/server/src/events/index.ts`
- [Shared schemas](https://github.com/its-dorra/dotion/blob/main/packages/shared/src/events/index.ts): `packages/shared/src/events/index.ts`

### Other components

- **Workspace user**
- **Cloudflare R2**
- **Neon PostgreSQL**
- **Cloudflare Queues**

## Connections

- Workspace user → Web application: uses
- Web application → Page editing: opens pages (evidence: `apps/web/src/routes/app/workspaces/$workspaceId/route.tsx`)
- Web application → Search interface: opens search (evidence: `apps/web/src/routes/app/workspaces/$workspaceId/route.tsx`)
- Web application → AI assistant: opens assistant (evidence: `apps/web/src/routes/app/workspaces/$workspaceId/route.tsx`)
- Page editing → Page API: requests pages
- Workspace features → Workspace API: requests workspaces
- Comments interface → Comments API: requests comments
- Search interface → HTTP application: searches workspace
- AI assistant → Assistant API: streams chat (evidence: `apps/server/src/routes/workspaces/assistant/routes.ts`)
- HTTP application → Page API: routes requests
- Page API → Page service: delegates page work
- Workspace API → Workspace service: delegates workspace work
- Assistant API → Search and indexing: retrieves context
- Page service → PostgreSQL repositories: accesses repositories (evidence: `packages/services/src/pages.service.ts`)
- Workspace service → PostgreSQL repositories: persists workspace data
- Search and indexing → PostgreSQL repositories: reads and indexes (evidence: `packages/services/src/search.service.ts`)
- Search and indexing → Embedding generation: generates vectors (evidence: `packages/services/src/search.service.ts`)
- Page service → Authorization: checks access
- Page API → Realtime coordination: coordinates collaboration
- Realtime coordination → Workspace user: syncs edits
- HTTP application → File storage: handles uploads
- File storage → Cloudflare R2: stores files (evidence: `packages/services/src/storage.service.ts`)
- Page service → Outbox and events: emits domain events
- Outbox and events → Cloudflare Queues: dispatches jobs
- Cloudflare Queues → Background queues: delivers jobs
- Background queues → Search and indexing: indexes pages
- Background queues → File storage: cleans assets
- PostgreSQL repositories → Neon PostgreSQL: queries
- Page API → Shared schemas: validates contracts (evidence: `apps/server/src/routes/workspaces/pages/routes.ts`)
