# manish-9245/collabpro architecture

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

- Interactive diagram: https://gitdiagram.com/manish-9245/collabpro
- Repository: https://github.com/manish-9245/collabpro

## Overview

#### 1. Purpose and Runtime Topology
CollabPro is a self-hosted, multi-tenant collaborative workspace combining block documents and an Excalidraw engineering canvas. It runs as two Node.js services: a Next.js App Router web/API process and a standalone WebSocket gateway. Primary deployment definitions are `docker-compose.yml` and `charts/collabpro/templates/web-deployment.yaml`; the WS service is separately deployed via `charts/collabpro/templates/ws-deployment.yaml`.

#### 2. Web Application and User Entry Points
The Next.js application enters through `app/layout.tsx` and `app/page.tsx`, with login/register pages at `app/login/page.tsx` and `app/register/page.tsx`. Authenticated navigation centers on the dashboard layout, `app/(routes)/dashboard/layout.tsx`, and workspace routes: `app/(routes)/workspace/[fileId]/page.tsx`. Shared-link viewers use `app/(routes)/workspace/share/[sharedLinkId]/page.tsx`, establishing a separate externally shared access boundary.

#### 3. Workspace Editing Surface
A workspace combines a rich document editor and collaborative canvas:
- `app/(routes)/workspace/_components/Editor.tsx` hosts Editor.js-style document editing.
- `app/(routes)/workspace/_components/Canvas.tsx` hosts the Excalidraw canvas and visual diagram state.
- `app/(routes)/workspace/_components/AiSidebar.tsx` provides workspace AI interaction.
- `app/(routes)/workspace/_components/CanvasAssetBuilder.ts` builds canvas assets, including the AWS icon library.

UI state and data synchronization are coordinated by `app/StateSyncProvider.tsx` and `lib/state-sync/react.tsx`, separating client synchronization behavior from editing components.

#### 4. Dual-Channel State Synchronization
The primary control flow is WebSocket-first collaboration with HTTP state-sync fallback. The standalone gateway starts at `ws-server/server.ts`; collaboration broadcast, authorization caching, mutation processing, and durable writes are divided across `ws-server/collab-broadcast.ts`, `ws-server/access-cache.ts`, and `ws-server/queue-db-write.ts`.

When sockets are unavailable, clients call `app/api/state-sync/route.ts`. Its service layer splits state operations by domain, including `app/api/state-sync/services/fileService.ts` and `app/api/state-sync/services/teamService.ts`. Shared compare-and-swap write behavior is centralized in `lib/cas-writes.ts`, protecting concurrent document/canvas updates across HTTP, WebSocket, and automation paths.

#### 5. Identity, Tenancy, and Access Boundaries
Native signed session-cookie authentication is exposed under `app/api/auth/login/route.ts`, `app/api/auth/register/route.ts`, and `app/api/auth/me/route.ts`. Server/client session handling resides in `lib/session-auth/server.ts` and `lib/session-auth/client.tsx`.

Authorization is tenant/team scoped and enforced around file access in `lib/file-access.ts` and WS-specific checks in `ws-server/file-access.ts`. Share creation and verification are isolated behind `app/api/share/route.ts` and `app/api/share/verify/route.ts`, rather than granting normal workspace access.

#### 6. Persistence, Cache, and Object Storage
PostgreSQL is the system of record, accessed through Prisma definitions and migrations in `prisma/schema.prisma` and `prisma/migrations/`. Redis supports cache-aside reads and distributed rate limiting through `lib/redis-cache.ts` and `lib/rate-limiter.ts`; the system is designed to fall back when Redis is unavailable.

Canvas image uploads use S3-compatible storage via `lib/s3.ts` and `app/api/upload/route.ts`, keeping image payloads outside Postgres. The file service boundary is represented by `lib/file-service.ts`.

#### 7. External Automation and Operational Services
The remote MCP server is `app/api/mcp/route.ts`, with tool definitions in `lib/mcp/tools.ts`; API-key controls are exposed by `app/api/api-keys/route.ts` and middleware in `lib/api-key-middleware.ts`. MCP writes share the normal access and CAS persistence path.

Operational/security integrations include health checks at `app/api/health/route.ts`, audit facilities in `lib/audit.ts`, queued notifications in `lib/notification-queue.ts`, and Snyk/SonarCloud compliance endpoints under `app/api/compliance/snyk/route.ts` and `app/api/compliance/sonarcloud/route.ts`.

Main entry points: [`app/api/state-sync/services/fileService.ts`](https://github.com/manish-9245/collabpro/blob/main/app/api/state-sync/services/fileService.ts) (File state service), [`app/StateSyncProvider.tsx`](https://github.com/manish-9245/collabpro/blob/main/app/StateSyncProvider.tsx) (State sync provider), [`ws-server/collab-broadcast.ts`](https://github.com/manish-9245/collabpro/blob/main/ws-server/collab-broadcast.ts) (Collaboration broadcast), [`app/(routes)/dashboard/layout.tsx`](https://github.com/manish-9245/collabpro/blob/main/app/(routes)/dashboard/layout.tsx) (Dashboard & workspace routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Next.js web process"]
  node_entry["App entry<br/>Next.js entry<br/>[layout.tsx]"]
  node_dashboard["Dashboard &amp; workspace routes<br/>authenticated UI<br/>[layout.tsx]"]
  node_workspace["Workspace editor<br/>editing surface<br/>[page.tsx]"]
  node_state_provider["State sync provider<br/>client sync"]
  node_http_sync["HTTP state sync<br/>API fallback<br/>[route.ts]"]
  node_file_ops["File state service<br/>[fileService.ts]"]
  node_auth["Session auth<br/>auth API<br/>[route.ts]"]
  node_session["Server session handling<br/>session library<br/>[server.ts]"]
  node_uploads["Upload API<br/>asset ingestion<br/>[route.ts]"]
  node_web_deploy["Web deployment<br/>Kubernetes deployment"]
end

subgraph group_collab["Collaboration gateway"]
  node_ws_server{{"WebSocket gateway<br/>Node.js service<br/>[server.ts]"}}
  node_ws_broadcast["Collaboration broadcast<br/>mutation processor"]
  node_ws_access["WS file access<br/>authorization<br/>[file-access.ts]"]
  node_ws_deploy["WS deployment<br/>Kubernetes deployment<br/>[ws-deployment.yaml]"]
end

subgraph group_data["Persistence services"]
  node_cas["CAS writes<br/>concurrency control<br/>[cas-writes.ts]"]
  node_prisma[("PostgreSQL schema<br/>system of record<br/>[schema.prisma]")]
  node_redis[("Redis cache &amp; limits<br/>cache-aside store<br/>[redis-cache.ts]")]
  node_s3[("S3-compatible storage<br/>object storage<br/>[s3.ts]")]
end

subgraph group_external["External access"]
  node_share["Shared-link access<br/>external viewer boundary<br/>[page.tsx]"]
  node_share_verify["Share verification<br/>share API<br/>[route.ts]"]
  node_mcp["MCP automation API<br/>remote tool API<br/>[route.ts]"]
end

node_entry -->|"authenticated navigation"| node_dashboard
node_dashboard -->|"opens file"| node_workspace
node_workspace -->|"coordinates client state"| node_state_provider
node_state_provider -->|"WebSocket-first sync"| node_ws_server
node_state_provider -.->|"HTTP fallback"| node_http_sync
node_http_sync -->|"file operations"| node_file_ops
node_file_ops -->|"guarded writes"| node_cas
node_ws_server -->|"processes mutations"| node_ws_broadcast
node_ws_broadcast -->|"authorizes access"| node_ws_access
node_ws_broadcast -->|"guarded writes"| node_cas
node_cas -->|"durable state"| node_prisma
node_file_ops -.->|"cache-aside"| node_redis
node_auth -->|"creates session"| node_session
node_session -->|"gates access"| node_dashboard
node_share -->|"verifies link"| node_share_verify
node_share_verify -->|"restricted file access"| node_file_ops
node_mcp -->|"automation writes"| node_file_ops
node_uploads -->|"stores images"| node_s3
node_web_deploy -->|"deploys web process"| node_entry
node_ws_deploy -->|"deploys gateway"| node_ws_server

click node_entry "https://github.com/manish-9245/collabpro/blob/main/app/layout.tsx"
click node_dashboard "https://github.com/manish-9245/collabpro/blob/main/app/(routes)/dashboard/layout.tsx"
click node_workspace "https://github.com/manish-9245/collabpro/blob/main/app/(routes)/workspace/%5BfileId%5D/page.tsx"
click node_state_provider "https://github.com/manish-9245/collabpro/blob/main/app/StateSyncProvider.tsx"
click node_http_sync "https://github.com/manish-9245/collabpro/blob/main/app/api/state-sync/route.ts"
click node_file_ops "https://github.com/manish-9245/collabpro/blob/main/app/api/state-sync/services/fileService.ts"
click node_auth "https://github.com/manish-9245/collabpro/blob/main/app/api/auth/login/route.ts"
click node_session "https://github.com/manish-9245/collabpro/blob/main/lib/session-auth/server.ts"
click node_share "https://github.com/manish-9245/collabpro/blob/main/app/(routes)/workspace/share/%5BsharedLinkId%5D/page.tsx"
click node_share_verify "https://github.com/manish-9245/collabpro/blob/main/app/api/share/verify/route.ts"
click node_mcp "https://github.com/manish-9245/collabpro/blob/main/app/api/mcp/route.ts"
click node_ws_server "https://github.com/manish-9245/collabpro/blob/main/ws-server/server.ts"
click node_ws_broadcast "https://github.com/manish-9245/collabpro/blob/main/ws-server/collab-broadcast.ts"
click node_ws_access "https://github.com/manish-9245/collabpro/blob/main/ws-server/file-access.ts"
click node_cas "https://github.com/manish-9245/collabpro/blob/main/lib/cas-writes.ts"
click node_prisma "https://github.com/manish-9245/collabpro/blob/main/prisma/schema.prisma"
click node_redis "https://github.com/manish-9245/collabpro/blob/main/lib/redis-cache.ts"
click node_uploads "https://github.com/manish-9245/collabpro/blob/main/app/api/upload/route.ts"
click node_s3 "https://github.com/manish-9245/collabpro/blob/main/lib/s3.ts"
click node_web_deploy "https://github.com/manish-9245/collabpro/blob/main/charts/collabpro/templates/web-deployment.yaml"
click node_ws_deploy "https://github.com/manish-9245/collabpro/blob/main/charts/collabpro/templates/ws-deployment.yaml"

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_entry,node_dashboard,node_workspace,node_state_provider,node_http_sync,node_file_ops,node_auth,node_session,node_uploads,node_web_deploy toneBlue
class node_ws_server,node_ws_broadcast,node_ws_access,node_ws_deploy toneAmber
class node_cas,node_prisma,node_redis,node_s3 toneMint
class node_share,node_share_verify,node_mcp toneRose
```

## Components

### Next.js web process

App Router UI and HTTP API.

- [App entry](https://github.com/manish-9245/collabpro/blob/main/app/layout.tsx): Next.js entry · `app/layout.tsx`
- [Dashboard & workspace routes](https://github.com/manish-9245/collabpro/blob/main/app/(routes)/dashboard/layout.tsx): authenticated UI · `app/(routes)/dashboard/layout.tsx`
- [Workspace editor](https://github.com/manish-9245/collabpro/blob/main/app/(routes)/workspace/%5BfileId%5D/page.tsx): editing surface · Combines document, canvas, and AI UI. · `app/(routes)/workspace/[fileId]/page.tsx`
- [State sync provider](https://github.com/manish-9245/collabpro/blob/main/app/StateSyncProvider.tsx): client sync · `app/StateSyncProvider.tsx`
- [HTTP state sync](https://github.com/manish-9245/collabpro/blob/main/app/api/state-sync/route.ts): API fallback · `app/api/state-sync/route.ts`
- [File state service](https://github.com/manish-9245/collabpro/blob/main/app/api/state-sync/services/fileService.ts): state service · `app/api/state-sync/services/fileService.ts`
- [Session auth](https://github.com/manish-9245/collabpro/blob/main/app/api/auth/login/route.ts): auth API · `app/api/auth/login/route.ts`
- [Server session handling](https://github.com/manish-9245/collabpro/blob/main/lib/session-auth/server.ts): session library · `lib/session-auth/server.ts`
- [Upload API](https://github.com/manish-9245/collabpro/blob/main/app/api/upload/route.ts): asset ingestion · `app/api/upload/route.ts`
- [Web deployment](https://github.com/manish-9245/collabpro/blob/main/charts/collabpro/templates/web-deployment.yaml): Kubernetes deployment · `charts/collabpro/templates/web-deployment.yaml`

### Collaboration gateway

Standalone WebSocket runtime.

- [WebSocket gateway](https://github.com/manish-9245/collabpro/blob/main/ws-server/server.ts): Node.js service · Primary real-time collaboration channel. · `ws-server/server.ts`
- [Collaboration broadcast](https://github.com/manish-9245/collabpro/blob/main/ws-server/collab-broadcast.ts): mutation processor · `ws-server/collab-broadcast.ts`
- [WS file access](https://github.com/manish-9245/collabpro/blob/main/ws-server/file-access.ts): authorization · `ws-server/file-access.ts`
- [WS deployment](https://github.com/manish-9245/collabpro/blob/main/charts/collabpro/templates/ws-deployment.yaml): Kubernetes deployment · `charts/collabpro/templates/ws-deployment.yaml`

### Persistence services

Durable data, cache, and object storage.

- [CAS writes](https://github.com/manish-9245/collabpro/blob/main/lib/cas-writes.ts): concurrency control · Shared optimistic write path. · `lib/cas-writes.ts`
- [PostgreSQL schema](https://github.com/manish-9245/collabpro/blob/main/prisma/schema.prisma): system of record · `prisma/schema.prisma`
- [Redis cache & limits](https://github.com/manish-9245/collabpro/blob/main/lib/redis-cache.ts): cache-aside store · Optional cache and distributed rate limiting. · `lib/redis-cache.ts`
- [S3-compatible storage](https://github.com/manish-9245/collabpro/blob/main/lib/s3.ts): object storage · Stores canvas image payloads. · `lib/s3.ts`

### External access

Shared access and automation boundaries.

- [Shared-link access](https://github.com/manish-9245/collabpro/blob/main/app/(routes)/workspace/share/%5BsharedLinkId%5D/page.tsx): external viewer boundary · `app/(routes)/workspace/share/[sharedLinkId]/page.tsx`
- [Share verification](https://github.com/manish-9245/collabpro/blob/main/app/api/share/verify/route.ts): share API · `app/api/share/verify/route.ts`
- [MCP automation API](https://github.com/manish-9245/collabpro/blob/main/app/api/mcp/route.ts): remote tool API · `app/api/mcp/route.ts`

## Connections

- App entry → Dashboard & workspace routes: authenticated navigation
- Dashboard & workspace routes → Workspace editor: opens file
- Workspace editor → State sync provider: coordinates client state
- State sync provider → WebSocket gateway: WebSocket-first sync
- State sync provider → HTTP state sync: HTTP fallback
- HTTP state sync → File state service: file operations
- File state service → CAS writes: guarded writes
- WebSocket gateway → Collaboration broadcast: processes mutations
- Collaboration broadcast → WS file access: authorizes access
- Collaboration broadcast → CAS writes: guarded writes
- CAS writes → PostgreSQL schema: durable state
- File state service → Redis cache & limits: cache-aside
- Session auth → Server session handling: creates session
- Server session handling → Dashboard & workspace routes: gates access
- Shared-link access → Share verification: verifies link
- Share verification → File state service: restricted file access
- MCP automation API → File state service: automation writes
- Upload API → S3-compatible storage: stores images
- Web deployment → App entry: deploys web process
- WS deployment → WebSocket gateway: deploys gateway