How farhans7/collab-doc works
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: EditorComponent.tsx Editor core · docs.service.ts Docs service · layout.tsx Web shell · page.tsx Document page
Components 31
Web App
Next.js client, routes, editor UI, and auth gating.
- Web shell · Dashboard layout and root client entry for the Next.js app.
apps/web/app/(dashboard)/layout.tsx - Dashboard · Main authenticated landing page.
apps/web/app/(dashboard)/page.tsx - Document page · Primary editor route for a document by id.
apps/web/app/doc/[id]/page.tsx - Login · Public sign-in entry point.
apps/web/app/login/page.tsx - Auth route · NextAuth handler for session and login callbacks.
apps/web/app/api/auth/[...nextauth]/route.ts - Route guard · Protects authenticated pages and enforces access flow.
apps/web/middleware.ts - Editor core · Composes the document editor, toolbar, and collaboration UI.
apps/web/components/editor/EditorComponent.tsx - Toolbar · Editing actions and formatting controls.
apps/web/components/editor/EditorToolbar.tsx - Presence bar · Shows active members, cursors, and presence state.
apps/web/components/editor/PresenceBar.tsx - Member modal · Manages document membership and role affordances.
apps/web/components/editor/MemberManagementModal.tsx - Slash command · Command palette and editor slash-trigger behavior.
apps/web/components/editor/SlashCommandExtension.ts - AI ghost text · Renders inline AI suggestions inside the editor.
apps/web/components/editor/AIGhostExtension.ts - Collab hook · Connects the editor to the realtime collaboration provider.
apps/web/hooks/useCollabProvider.ts - AI hook · Drives streamed AI suggestions for the editor.
apps/web/hooks/useAISuggestion.ts - AI stream · Client-side SSE helper for token streaming.
apps/web/lib/aiStream.ts - Auth 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 · REST entry for document operations.
apps/server/src/routes/docs.ts - AI route · REST/SSE entry for AI generation and proxying.
apps/server/src/routes/ai.ts - Docs controller · HTTP-layer document request handling.
apps/server/src/controllers/docs.controller.ts - AI controller · HTTP-layer AI request and stream handling.
apps/server/src/controllers/ai.controller.ts - Docs service · Coordinates document CRUD, membership, and persistence logic.
apps/server/src/services/docs.service.ts - AI service · Calls the model provider and formats streamed output.
apps/server/src/services/ai.service.ts - Doc manager · In-memory document state and debounce persistence bridge.
apps/server/src/lib/docManager.ts - Auth checks · Authentication and role-based authorization guard.
apps/server/src/middleware/requireAuth.ts - Role guard · Enforces document roles and access boundaries.
apps/server/src/middleware/requireRole.ts - Rate limit · Abuse protection for API and streaming endpoints.
apps/server/src/middleware/rateLimit.ts - Prisma data · Relational persistence for documents and memberships.
apps/server/src/lib/prisma.ts - Redis · 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 · Common request, response, and domain types.
packages/types/index.ts
Infra
Workspace-level delivery and local runtime support.
- Compose stack · Local PostgreSQL and Redis dependency topology.
docker-compose.yml - CI workflow · Repository checks and test pipeline.
.github/workflows/ci.yml
Connections 29
- 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.