# farhans7/collab-doc architecture

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

- Interactive diagram: https://gitdiagram.com/farhans7/collab-doc
- Repository: https://github.com/farhans7/collab-doc

## Overview

1. **Monorepo shape**
   - The repository is split into three main product surfaces: `apps/web` for the Next.js client, `apps/server` for the Express backend, and `packages/types` for shared TypeScript contracts.
   - Supporting pieces include Docker Compose for local dependencies, GitHub Actions for CI, and a `spike/` folder that appears to be an isolated prototype rather than part of the main app.

2. **Client application boundary**
   - `apps/web` is a Next.js 14 App Router app that owns the UI, page routing, and most browser-side state.
   - Key routes are the dashboard shell, document page (`/doc/[id]`), login page, and a NextAuth handler at `app/api/auth/[...nextauth]/route.ts`.
   - The client is responsible for rendering the editor, member/presence UI, and the AI ghost-text experience.

3. **Editor and collaboration surface**
   - The editor is built around Tiptap/ProseMirror with custom extensions and components under `components/editor/`.
   - `EditorComponent`, `EditorToolbar`, `PresenceBar`, `MemberManagementModal`, `SlashCommandExtension`, and `AIGhostExtension` indicate that editing, collaboration presence, permissions UI, and AI suggestions are all composed inside the document view.
   - `useCollabProvider` likely connects the editor to the real-time collaboration channel, while `useAISuggestion` and `lib/aiStream.ts` handle streamed AI completions.

4. **Authentication and page protection**
   - The web app uses NextAuth plus a route middleware (`apps/web/middleware.ts`) to gate access to protected pages.
   - `lib/auth.ts` and `types/next-auth.d.ts` suggest the client maintains typed session/user claims, which then drive role-aware UI behavior such as editor vs viewer affordances.

5. **Backend API boundary**
   - `apps/server` is a Node.js/Express service that exposes REST endpoints for documents and AI streaming.
   - The primary route modules are `routes/docs.ts` and `routes/ai.ts`, with controller logic in `controllers/docs.controller.ts` and `controllers/ai.controller.ts`.
   - This backend is the system boundary for document metadata, permission checks, and AI proxying.

6. **Document subsystem**
   - The document domain is concentrated in `services/docs.service.ts` and `lib/docManager.ts`.
   - The README indicates a hybrid model: collaborative state is held in memory for fast sync, then persisted to PostgreSQL through Prisma after a debounce window.
   - `schema.prisma` and the migration files define the relational storage for documents, memberships, and related metadata.

7. **Real-time collaboration model**
   - The architecture is CRDT-based, using Y.js/YATA semantics rather than operational transforms.
   - The tests in `services/crdt.test.ts` and integration coverage for collaboration show that convergence behavior is a first-class concern.
   - In practical terms, the editor pushes compact document updates over a real-time channel, and the server acts as a synchronization and persistence layer rather than a strict lock manager.

8. **Presence and multi-user state**
   - The repo emphasizes active peer presence: user cursors, selections, and membership visibility are part of the collaboration experience.
   - Even though the low-level socket server code is not visible in this tree, the presence-focused editor components and integration tests imply a channel-based model for ephemeral user state separate from persistent document content.

9. **AI writing assistance path**
   - AI assistance is separated into its own backend route and service layer, with `controllers/ai.controller.ts` and `services/ai.service.ts` handling streamed output.
   - The README calls out Server-Sent Events for token-by-token delivery, which matches the web-side `aiStream` helper and ghost-text editor extension.
   - This keeps AI generation decoupled from collaborative document persistence: suggestions are local UI state until explicitly merged.

10. **Security, access control, and limits**
   - The server middleware layer contains `requireAuth`, `requireRole`, and `rateLimit`, indicating layered enforcement of authentication, document roles, and abuse protection.
   - `lib/errors.ts` and `lib/asyncHandler.ts` centralize request error handling, which helps keep the route/controllers thin.
   - Redis is used as an operational dependency for rate limiting and, per the README, likely for pub/sub or scaling-related coordination.

11. **Shared contracts**
   - `packages/types` exists to keep request/response and domain types consistent between client and server.
   - This reduces drift across the frontend editor, API routes, and server services, which is especially important in a collaboration system where document, presence, and membership payloads must align exactly.

12. **Infrastructure and delivery**
   - The root `docker-compose.yml`, server Dockerfiles, and `.env.example` show the app is designed to run with PostgreSQL and Redis in local/dev environments.
   - CI is defined in `.github/workflows/ci.yml`, and the server has both unit and integration Jest configs, including tests that hit a real backend/database setup.
   - Overall, the deployment shape is: browser client on Next.js, API/backend on Express, PostgreSQL for durable state, Redis for operational coordination, and Anthropic-backed AI streaming behind the server.

Main entry points: [`apps/web/components/editor/EditorComponent.tsx`](https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/EditorComponent.tsx) (Editor core), [`apps/server/src/services/docs.service.ts`](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/services/docs.service.ts) (Docs service), [`apps/web/app/(dashboard)/layout.tsx`](https://github.com/farhans7/collab-doc/blob/main/apps/web/app/(dashboard)/layout.tsx) (Web shell), [`apps/web/app/doc/[id]/page.tsx`](https://github.com/farhans7/collab-doc/blob/main/apps/web/app/doc/[id]/page.tsx) (Document page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_web["Web App"]
  node_web_shell["Web shell<br/>nextjs app<br/>[layout.tsx]"]
  node_web_dashboard["Dashboard<br/>page<br/>[page.tsx]"]
  node_web_doc_page["Document page<br/>route page<br/>[page.tsx]"]
  node_web_login["Login<br/>page<br/>[page.tsx]"]
  node_web_auth_route["Auth route<br/>[route.ts]"]
  node_web_middleware["Route guard<br/>middleware<br/>[middleware.ts]"]
  node_editor_core["Editor core<br/>tiptap component"]
  node_editor_toolbar["Toolbar<br/>editor ui<br/>[EditorToolbar.tsx]"]
  node_editor_presence["Presence bar<br/>collab ui<br/>[PresenceBar.tsx]"]
  node_editor_members["Member modal<br/>permissions ui"]
  node_editor_slash{{"Slash command<br/>extension"}}
  node_editor_ghost{{"AI ghost text<br/>extension"}}
  node_hook_collab["Collab hook<br/>react hook"]
  node_hook_ai["AI hook<br/>react hook<br/>[useAISuggestion.ts]"]
  node_web_ai_stream["AI stream<br/>stream client<br/>[aiStream.ts]"]
  node_web_auth_lib["Auth config<br/>session config<br/>[auth.ts]"]
end

subgraph group_group_server["API Server"]
  node_server_docs_route["Docs route<br/>express route<br/>[docs.ts]"]
  node_server_ai_route["AI route<br/>express route<br/>[ai.ts]"]
  node_server_docs_ctrl["Docs controller<br/>[docs.controller.ts]"]
  node_server_ai_ctrl["AI controller<br/>[ai.controller.ts]"]
  node_server_docs_service["Docs service<br/>domain service<br/>[docs.service.ts]"]
  node_server_ai_service["AI service<br/>domain service<br/>[ai.service.ts]"]
  node_doc_manager["Doc manager<br/>sync state<br/>[docManager.ts]"]
  node_server_auth["Auth checks<br/>middleware<br/>[requireAuth.ts]"]
  node_server_role["Role guard<br/>middleware<br/>[requireRole.ts]"]
  node_server_rate["Rate limit<br/>middleware<br/>[rateLimit.ts]"]
  node_server_prisma[("Prisma data<br/>database layer<br/>[prisma.ts]")]
  node_server_redis[("Redis<br/>ops dependency<br/>[redis.ts]")]
end

subgraph group_group_types["Shared Types"]
  node_shared_types["Shared contracts<br/>ts package<br/>[index.ts]"]
end

subgraph group_group_infra["Infra"]
  node_compose["Compose stack<br/>infra config<br/>[docker-compose.yml]"]
  node_ci["CI workflow<br/>automation<br/>[ci.yml]"]
end

node_web_shell -->|"renders"| node_web_dashboard
node_web_shell -->|"hosts"| node_web_doc_page
node_web_shell -->|"links"| node_web_login
node_web_middleware -->|"protects"| node_web_login
node_web_auth_route -->|"uses"| node_web_auth_lib
node_web_doc_page -->|"composes"| node_editor_core
node_editor_core -->|"includes"| node_editor_toolbar
node_editor_core -->|"includes"| node_editor_presence
node_editor_core -->|"includes"| node_editor_members
node_editor_core -->|"extends"| node_editor_slash
node_editor_core -->|"extends"| node_editor_ghost
node_editor_core -->|"connects"| node_hook_collab
node_editor_core -->|"connects"| node_hook_ai
node_hook_ai -->|"streams"| node_web_ai_stream
node_hook_collab -.->|"syncs"| node_server_docs_route
node_server_docs_route -->|"routes to"| node_server_docs_ctrl
node_server_ai_route -->|"routes to"| node_server_ai_ctrl
node_server_docs_ctrl -->|"delegates"| node_server_docs_service
node_server_ai_ctrl -->|"delegates"| node_server_ai_service
node_server_docs_service -->|"coordinates"| node_doc_manager
node_doc_manager -->|"persists"| node_server_prisma
node_server_docs_service -->|"checks"| node_server_auth
node_server_docs_service -->|"checks"| node_server_role
node_server_ai_service -->|"limits"| node_server_rate
node_server_rate -->|"uses"| node_server_redis
node_server_docs_service -->|"shares"| node_shared_types
node_editor_core -->|"shares"| node_shared_types
node_server_docs_service -.->|"depends on"| node_compose
node_ci -.->|"verifies"| node_server_docs_service

click node_web_shell "https://github.com/farhans7/collab-doc/blob/main/apps/web/app/(dashboard)/layout.tsx"
click node_web_dashboard "https://github.com/farhans7/collab-doc/blob/main/apps/web/app/(dashboard)/page.tsx"
click node_web_doc_page "https://github.com/farhans7/collab-doc/blob/main/apps/web/app/doc/[id]/page.tsx"
click node_web_login "https://github.com/farhans7/collab-doc/blob/main/apps/web/app/login/page.tsx"
click node_web_auth_route "https://github.com/farhans7/collab-doc/blob/main/apps/web/app/api/auth/[...nextauth]/route.ts"
click node_web_middleware "https://github.com/farhans7/collab-doc/blob/main/apps/web/middleware.ts"
click node_editor_core "https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/EditorComponent.tsx"
click node_editor_toolbar "https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/EditorToolbar.tsx"
click node_editor_presence "https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/PresenceBar.tsx"
click node_editor_members "https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/MemberManagementModal.tsx"
click node_editor_slash "https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/SlashCommandExtension.ts"
click node_editor_ghost "https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/AIGhostExtension.ts"
click node_hook_collab "https://github.com/farhans7/collab-doc/blob/main/apps/web/hooks/useCollabProvider.ts"
click node_hook_ai "https://github.com/farhans7/collab-doc/blob/main/apps/web/hooks/useAISuggestion.ts"
click node_web_ai_stream "https://github.com/farhans7/collab-doc/blob/main/apps/web/lib/aiStream.ts"
click node_web_auth_lib "https://github.com/farhans7/collab-doc/blob/main/apps/web/lib/auth.ts"
click node_server_docs_route "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/routes/docs.ts"
click node_server_ai_route "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/routes/ai.ts"
click node_server_docs_ctrl "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/controllers/docs.controller.ts"
click node_server_ai_ctrl "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/controllers/ai.controller.ts"
click node_server_docs_service "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/services/docs.service.ts"
click node_server_ai_service "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/services/ai.service.ts"
click node_doc_manager "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/lib/docManager.ts"
click node_server_auth "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/middleware/requireAuth.ts"
click node_server_role "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/middleware/requireRole.ts"
click node_server_rate "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/middleware/rateLimit.ts"
click node_server_prisma "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/lib/prisma.ts"
click node_server_redis "https://github.com/farhans7/collab-doc/blob/main/apps/server/src/lib/redis.ts"
click node_shared_types "https://github.com/farhans7/collab-doc/blob/main/packages/types/index.ts"
click node_compose "https://github.com/farhans7/collab-doc/blob/main/docker-compose.yml"
click node_ci "https://github.com/farhans7/collab-doc/blob/main/.github/workflows/ci.yml"

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_web_shell,node_web_dashboard,node_web_doc_page,node_web_login,node_web_auth_route,node_web_middleware,node_editor_core,node_editor_toolbar,node_editor_presence,node_editor_members,node_editor_slash,node_editor_ghost,node_hook_collab,node_hook_ai,node_web_ai_stream,node_web_auth_lib toneBlue
class node_server_docs_route,node_server_ai_route,node_server_docs_ctrl,node_server_ai_ctrl,node_server_docs_service,node_server_ai_service,node_doc_manager,node_server_auth,node_server_role,node_server_rate,node_server_prisma,node_server_redis toneAmber
class node_shared_types toneMint
class node_compose,node_ci toneRose
```

## Components

### Web App

Next.js client, routes, editor UI, and auth gating.

- [Web shell](https://github.com/farhans7/collab-doc/blob/main/apps/web/app/(dashboard)/layout.tsx): nextjs app · Dashboard layout and root client entry for the Next.js app. · `apps/web/app/(dashboard)/layout.tsx`
- [Dashboard](https://github.com/farhans7/collab-doc/blob/main/apps/web/app/(dashboard)/page.tsx): page · Main authenticated landing page. · `apps/web/app/(dashboard)/page.tsx`
- [Document page](https://github.com/farhans7/collab-doc/blob/main/apps/web/app/doc/[id]/page.tsx): route page · Primary editor route for a document by id. · `apps/web/app/doc/[id]/page.tsx`
- [Login](https://github.com/farhans7/collab-doc/blob/main/apps/web/app/login/page.tsx): page · Public sign-in entry point. · `apps/web/app/login/page.tsx`
- [Auth route](https://github.com/farhans7/collab-doc/blob/main/apps/web/app/api/auth/[...nextauth]/route.ts): nextauth route · NextAuth handler for session and login callbacks. · `apps/web/app/api/auth/[...nextauth]/route.ts`
- [Route guard](https://github.com/farhans7/collab-doc/blob/main/apps/web/middleware.ts): middleware · Protects authenticated pages and enforces access flow. · `apps/web/middleware.ts`
- [Editor core](https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/EditorComponent.tsx): tiptap component · Composes the document editor, toolbar, and collaboration UI. · `apps/web/components/editor/EditorComponent.tsx`
- [Toolbar](https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/EditorToolbar.tsx): editor ui · Editing actions and formatting controls. · `apps/web/components/editor/EditorToolbar.tsx`
- [Presence bar](https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/PresenceBar.tsx): collab ui · Shows active members, cursors, and presence state. · `apps/web/components/editor/PresenceBar.tsx`
- [Member modal](https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/MemberManagementModal.tsx): permissions ui · Manages document membership and role affordances. · `apps/web/components/editor/MemberManagementModal.tsx`
- [Slash command](https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/SlashCommandExtension.ts): extension · Command palette and editor slash-trigger behavior. · `apps/web/components/editor/SlashCommandExtension.ts`
- [AI ghost text](https://github.com/farhans7/collab-doc/blob/main/apps/web/components/editor/AIGhostExtension.ts): extension · Renders inline AI suggestions inside the editor. · `apps/web/components/editor/AIGhostExtension.ts`
- [Collab hook](https://github.com/farhans7/collab-doc/blob/main/apps/web/hooks/useCollabProvider.ts): react hook · Connects the editor to the realtime collaboration provider. · `apps/web/hooks/useCollabProvider.ts`
- [AI hook](https://github.com/farhans7/collab-doc/blob/main/apps/web/hooks/useAISuggestion.ts): react hook · Drives streamed AI suggestions for the editor. · `apps/web/hooks/useAISuggestion.ts`
- [AI stream](https://github.com/farhans7/collab-doc/blob/main/apps/web/lib/aiStream.ts): stream client · Client-side SSE helper for token streaming. · `apps/web/lib/aiStream.ts`
- [Auth config](https://github.com/farhans7/collab-doc/blob/main/apps/web/lib/auth.ts): session config · Typed auth/session helpers for the web app. · `apps/web/lib/auth.ts`

### API Server

Express backend for documents, collaboration, and AI streaming.

- [Docs route](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/routes/docs.ts): express route · REST entry for document operations. · `apps/server/src/routes/docs.ts`
- [AI route](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/routes/ai.ts): express route · REST/SSE entry for AI generation and proxying. · `apps/server/src/routes/ai.ts`
- [Docs controller](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/controllers/docs.controller.ts): controller · HTTP-layer document request handling. · `apps/server/src/controllers/docs.controller.ts`
- [AI controller](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/controllers/ai.controller.ts): controller · HTTP-layer AI request and stream handling. · `apps/server/src/controllers/ai.controller.ts`
- [Docs service](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/services/docs.service.ts): domain service · Coordinates document CRUD, membership, and persistence logic. · `apps/server/src/services/docs.service.ts`
- [AI service](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/services/ai.service.ts): domain service · Calls the model provider and formats streamed output. · `apps/server/src/services/ai.service.ts`
- [Doc manager](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/lib/docManager.ts): sync state · In-memory document state and debounce persistence bridge. · `apps/server/src/lib/docManager.ts`
- [Auth checks](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/middleware/requireAuth.ts): middleware · Authentication and role-based authorization guard. · `apps/server/src/middleware/requireAuth.ts`
- [Role guard](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/middleware/requireRole.ts): middleware · Enforces document roles and access boundaries. · `apps/server/src/middleware/requireRole.ts`
- [Rate limit](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/middleware/rateLimit.ts): middleware · Abuse protection for API and streaming endpoints. · `apps/server/src/middleware/rateLimit.ts`
- [Prisma data](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/lib/prisma.ts): database layer · Relational persistence for documents and memberships. · `apps/server/src/lib/prisma.ts`
- [Redis](https://github.com/farhans7/collab-doc/blob/main/apps/server/src/lib/redis.ts): ops dependency · Operational coordination and rate limiting backend. · `apps/server/src/lib/redis.ts`

### Shared Types

Cross-package TypeScript contracts used by client and server.

- [Shared contracts](https://github.com/farhans7/collab-doc/blob/main/packages/types/index.ts): ts package · Common request, response, and domain types. · `packages/types/index.ts`

### Infra

Workspace-level delivery and local runtime support.

- [Compose stack](https://github.com/farhans7/collab-doc/blob/main/docker-compose.yml): infra config · Local PostgreSQL and Redis dependency topology. · `docker-compose.yml`
- [CI workflow](https://github.com/farhans7/collab-doc/blob/main/.github/workflows/ci.yml): automation · Repository checks and test pipeline. · `.github/workflows/ci.yml`

## Connections

- Web shell → Dashboard: renders · Dashboard UI sits inside the authenticated web shell.
- Web shell → Document page: hosts · Document route is mounted under the dashboard layout.
- Web shell → Login: links · Unauthenticated users are redirected toward login.
- Route guard → Login: protects · Gates protected pages and funnels unauthenticated access.
- Auth route → Auth config: uses · NextAuth route depends on web auth configuration.
- Document page → Editor core: composes · Document page assembles the editor experience.
- Editor core → Toolbar: includes · Toolbar is part of the editor surface.
- Editor core → Presence bar: includes · Presence UI is rendered with the editor.
- Editor core → Member modal: includes · Membership controls are embedded in the document view.
- Editor core → Slash command: extends · Slash commands augment editing behavior.
- Editor core → AI ghost text: extends · AI ghost text integrates into the editor.
- Editor core → Collab hook: connects · Editor uses the collaboration provider hook.
- Editor core → AI hook: connects · Editor consumes streamed AI suggestions through a hook.
- AI hook → AI stream: streams · Suggestion hook reads token streams from the client helper.
- Collab hook → Docs route: syncs · Realtime collaboration ultimately syncs with the document API boundary.
- Docs route → Docs controller: routes to · Document requests are handled by the controller layer.
- AI route → AI controller: routes to · AI requests are handled by the AI controller.
- Docs controller → Docs service: delegates · Controller keeps HTTP concerns thin and forwards to domain logic.
- AI controller → AI service: delegates · AI controller forwards generation and streaming work.
- Docs service → Doc manager: coordinates · Service uses the in-memory doc manager for sync and persistence.
- Doc manager → Prisma data: persists · Document state is flushed to relational storage.
- Docs service → Auth checks: checks · Document operations are guarded by authentication.
- Docs service → Role guard: checks · Role-based access is enforced at the service boundary.
- AI service → Rate limit: limits · AI endpoints are protected by rate limiting.
- Rate limit → Redis: uses · Redis backs request throttling and coordination.
- Docs service → Shared contracts: shares · Server exchanges shared contracts with the web app.
- Editor core → Shared contracts: shares · Editor payloads and document models use shared contracts.
- Docs service → Compose stack: depends on · Durable document storage assumes local infra services.
- CI workflow → Docs service: verifies · CI exercises backend and collaboration behavior.