manish-9245/collabpro

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.