# Realtime Collaboration (Hocuspocus + Y.js) **Status:** in_progress (novel-editor-collab-shipped, other-editors-deferred) **Task-ID:** #59 **Phase:** 05 **Estimated Effort:** 3-4 Wochen für Novel-Editor; weitere Editoren ca. 1 Woche pro **Owner:** unassigned ## Problem Die Boilerplate hat aktuell keine Mehrbenutzer-Collaboration im Editor. Wenn zwei Users gleichzeitig denselben KB-Artikel/Workflow/Rich-Text editieren, gewinnt der spätere Save und überschreibt die Änderungen des ersten (last-write-wins). Use-Cases die heute scheitern: - Zwei CRM-User editieren gleichzeitig Contact-Notes - Team schreibt KB-Artikel zusammen - Workflow-Builder mit zwei Designern parallel - Wiki-style Dokumentation Konkurrenz-Tools (Notion, Linear, Figma) liefern das nativ. Ohne Realtime-Collab ist die Boilerplate für Teams >2 unattraktiv. Zusätzliches Symptom: keine User-Cursor / Awareness ("ich sehe Patrick tippt gerade hier"). Konkret betroffene Editoren: - Novel-Editor in `apps/web/app/components/novel/` (Rich-Text, primärer Anwendungsfall) - Spätere Erweiterung: Rows-Edit (Tabellenstruktur), Workflow-Builder (Graph-Struktur) ## Depends on - `05-business-features/feature-flags.md` (#53) — Realtime-Feature pro Tenant via Flag aktivierbar (Gradual-Rollout + Plan-Tier-Gating) - `02-observability/sentry-wiring-api-worker.md` (#11) — Hocuspocus-Connection-Errors landen in Sentry - `02-observability/opentelemetry.md` (#13) — Tracing über Hocuspocus-Connection - Existierender Novel-Editor + Tiptap-Setup in `apps/web/app/components/novel/` ## Blocks - Spätere Erweiterung auf andere Editoren (Rows, Workflows) — sind out-of-scope dieser Task, aber Pattern wird hier etabliert ## Approach Hocuspocus + Y.js als Standard-Stack: 1. **Hocuspocus-Server** als separater Container (Node.js-Service). Auth via JWT-Hook gegen toolctrl-Session. Persistence-Adapter zu Postgres (Y.js-Doc als BLOB pro Resource, regelmäßiger Snapshot). 2. **Tiptap-Extensions im Novel-Editor** — `@tiptap/extension-collaboration` + `@tiptap/extension-collaboration-cursor` + `@hocuspocus/provider` clientside. Awareness mit User-Name + Avatar + Color. 3. **Graceful-Degradation** — wenn `HOCUSPOCUS_URL` nicht gesetzt oder Service unreachable, Editor läuft als Single-User mit existing REST-Save (kein Bruch in Self-Hosted-Setups die das Feature nicht wollen). **Begründung der Architektur-Wahl:** - **Hocuspocus statt eigenem Sync-Server:** Y.js + Hocuspocus sind battle-tested in Notion-Likes (TipTap-Cloud, App-Stack); selber bauen wäre 6-Monats-Projekt. - **Separater Container statt In-Process:** Hocuspocus läuft als WebSocket-Server mit persistent Connections. Wenn er im Web-App-Container mitläuft, blockiert WebSocket-Konzurrenz die Request-Pipeline. Separater Container = saubere Skalierung + unabhängiges Deploy. - **Postgres-Persistence-Adapter:** wir haben bereits Postgres, kein Bedarf für Redis-Persistence (Hocuspocus-Default). Wenn später Last steigt, Migration auf Redis-Persistence einfach möglich. - **Y.js statt Operational Transform:** Y.js (CRDT) ist konfliktfrei mergebar ohne zentralen Server-Reorder; OT braucht zentralen Server der alle Operations linearisiert. CRDT skaliert besser + Offline-fähig. - **Optionale Aktivierung:** existing Self-Hosted-Setups dürfen Realtime einfach disablen, sonst zusätzlicher Container-Pflichtbestandteil → Friction bei Customer-Onboarding. ## Implementation Steps 1. **Hocuspocus-Container-Setup** — `apps/hocuspocus/` neues Workspace-Package mit `Dockerfile`, `package.json` (deps: `@hocuspocus/server`, `@hocuspocus/extension-database`, `@hocuspocus/extension-logger`, prisma-client), `src/index.ts` als Entry. Server-Config: Port 1234 (default), Auth-Hook, Database-Adapter, Logger. `docker-compose.yml`-Snippet hinzufügen + `docker-compose.staging.yml` Erweiterung. - Files: `apps/hocuspocus/Dockerfile`, `apps/hocuspocus/package.json`, `apps/hocuspocus/src/index.ts`, `docker-compose.yml`, `docker-compose.staging.yml` - Commit: `05/realtime-collab: hocuspocus server container scaffold` 2. **Y.js-Doc-Persistence-Schema** — Prisma-Model `CollabDoc { id, tenantId, resourceType (kb-article|crm-note|workflow|...), resourceId, ydocState Bytes, lastUpdatedAt, lastSnapshotAt, version Int }` mit Unique-Index `(tenantId, resourceType, resourceId)`. Migration. - Files: `prisma/schema.prisma`, `prisma/migrations/_collab_docs/migration.sql` - Commit: `05/realtime-collab: collab doc persistence schema` 3. **Hocuspocus-Database-Extension** — implementiert `fetch({ documentName })` und `store({ documentName, state })` gegen `CollabDoc`-Tabelle. DocumentName-Format: `${tenantId}:${resourceType}:${resourceId}`. Bei Fetch: BLOB laden + zurückgeben. Bei Store: Upsert mit version-increment. - Files: `apps/hocuspocus/src/extensions/database.ts`, Test - Commit: `05/realtime-collab: postgres persistence adapter` 4. **Auth-Hook** — `onAuthenticate({ token, requestParameters })`-Hook in Hocuspocus. Token = signed JWT mit `userId + tenantId`, in Client beim Verbinden mitgegeben. Validierung gegen toolctrl-JWT-Secret (`HOCUSPOCUS_SECRET`). Permission-Check: hat User Zugriff auf `(tenantId, resourceType, resourceId)`? Lookup gegen DB-Resource-Specific-Permission-Helper (z.B. KB-Article-Permission-Check). Bei Fail: Connection refused mit 403. - Files: `apps/hocuspocus/src/extensions/auth.ts`, Permission-Helpers (Shared mit Web-App via `packages/auth-permissions/` oder duplicate-helpers für Container-Independence) - Commit: `05/realtime-collab: jwt auth and per-resource permission check` 5. **Snapshot-Strategy + Cleanup-Job** — alle 10min oder alle 50 Updates: snapshot ydocState in `CollabDoc.ydocState` + Update `lastSnapshotAt`. Cleanup-Cron: alte CollabDocs ohne Connections >30 Tage werden archiviert (separate Tabelle `CollabDocArchive`, daraus wiederherstellbar). Verhindert unbeschränktes BLOB-Wachstum. - Files: `apps/hocuspocus/src/extensions/snapshot.ts`, `apps/worker/src/cron/collab-cleanup.ts`, Tests - Commit: `05/realtime-collab: snapshot strategy and cleanup cron` 6. **Tiptap-Collaboration-Extensions im Novel-Editor** — `apps/web/app/components/novel/`: deps hinzufügen (`@tiptap/extension-collaboration`, `@tiptap/extension-collaboration-cursor`, `@hocuspocus/provider`, `yjs`). Editor-Config erweitert: bei `enableCollab=true && HOCUSPOCUS_URL set` instanziiere `HocuspocusProvider({ url, name: docName, token })` + `Collaboration.configure({ document })` + `CollaborationCursor.configure({ user: { name, color } })`. Provider-State-Events handhaben: `connected`, `disconnected`, `synced`, `awarenessUpdate`. - Files: `apps/web/app/components/novel/Editor.tsx` (oder relevante Editor-Datei), neuer `useHocuspocusProvider.ts`-Hook - Commit: `05/realtime-collab: integrate tiptap collaboration in novel editor` 7. **Awareness-UI** — neben Editor user-presence-bar mit Avatar-Stack der aktuell connected User. CollaborationCursor zeigt User-Cursor mit Name-Tooltip. Color-Assignment deterministisch aus userId (Hash → HSL). - Files: `apps/web/app/components/collab/PresenceBar.tsx`, Integration in Editor-Wrapper - Commit: `05/realtime-collab: presence ui with cursor and avatar stack` 8. **Graceful-Degradation-Pfad** — Editor-Wrapper prüft Connection-State: bei `disconnected > 10s` zeige subtilen Status "Offline — Änderungen werden lokal gespeichert" + fallback auf REST-Save via existing Save-Pfad. Bei `synced` zeige nichts oder grünen Indikator. Wenn `HOCUSPOCUS_URL` env nicht gesetzt: Editor läuft komplett Single-User wie vorher (kein Provider initialisiert). - Files: Update Editor-Wrapper, Status-Component - Commit: `05/realtime-collab: graceful degradation when hocuspocus unavailable` 9. **JWT-Issuer-Endpoint** — `apps/web/app/routes/api.collab.token.tsx` action: Auth-required, gibt kurzlebigen JWT (15min TTL) mit `userId+tenantId+resourceType+resourceId`-Claims signed mit `HOCUSPOCUS_SECRET`. Client refresht alle 10min. - Files: `apps/web/app/routes/api.collab.token.tsx`, Test - Commit: `05/realtime-collab: jwt token endpoint for collab auth` 10. **Doku** — `docs/features/realtime-collaboration.md`: Architektur-Diagramm, Hocuspocus-Container-Setup, Y.js-Konzept-Erklärung, Auth-Flow, Persistence-Strategie, Permission-Modell, How-to neue Editor-Integration für Phase-2 (Rows, Workflows), Troubleshooting (häufige Sync-Issues, Snapshot-Recovery). - Files: `docs/features/realtime-collaboration.md` - Commit: `05/realtime-collab: docs` ## Test Requirements - **Unit-Tests:** - Database-Extension: `fetch`/`store` gegen Test-DB, Versions-Increment korrekt - Auth-Hook: valid JWT → accept; expired → refuse; wrong-tenant → refuse; missing-permission → refuse - Snapshot-Strategy: nach N Updates wird snapshot getrigert - JWT-Issuer: nicht-autorisierter Request → 401; autorisiert → valider Token mit korrekten Claims - **Integration-Tests:** - Hocuspocus-Server lokal starten (testcontainer), Client connecten, Doc-Update senden → Persistenz in DB verifizieren - Zwei Clients connecten zu gleichem Doc → Updates eines werden im anderen sichtbar (Y.js-Merge) - Awareness: zwei Clients setzen User-State → beide sehen sich gegenseitig - Snapshot-Recovery: Server-Restart → Doc wird aus DB rehydriert - **E2E-Tests (Playwright):** - Two-Browser-Tab-Test: User A öffnet KB-Artikel → User B öffnet selben Artikel → A tippt → B sieht innerhalb 1s; B-Cursor in A-Tab sichtbar - Offline-Test: Hocuspocus-Container stoppen → User sieht "Offline"-Indikator → Tippt weiter → Container zurück → Re-Sync ohne Datenverlust - Permission-Test: User C ohne Read-Permission auf Artikel → Connection refused - **Coverage-Target:** 80% für `apps/hocuspocus/`, 70% für Editor-Integration - **Test-Files:** `apps/hocuspocus/src/**/*.test.ts`, `apps/web/app/components/novel/*.test.tsx`, E2E `apps/web/tests/e2e/collab-novel.spec.ts` **NICHT als completed markieren bevor alle Tests grün sind.** ## Acceptance Criteria - [ ] Hocuspocus-Container baut + läuft im docker-compose - [ ] `CollabDoc` Prisma-Model + Migration applied - [ ] Database-Extension persistiert Y.js-Docs zuverlässig - [ ] JWT-Auth-Hook mit Permission-Check funktional - [ ] Snapshot-Strategy + Cleanup-Cron aktiv - [ ] Novel-Editor mit Collaboration + Cursor + Awareness - [ ] Presence-Bar zeigt connected Users - [ ] Graceful-Degradation: ohne `HOCUSPOCUS_URL` läuft Editor Single-User, mit Service-Down zeigt Offline-Indikator - [ ] JWT-Issuer-Endpoint mit 15min-TTL - [ ] `docs/features/realtime-collaboration.md` mit Architektur + Setup + Editor-Integration-Guide - [ ] `.env.example` enthält `HOCUSPOCUS_URL`, `HOCUSPOCUS_SECRET` - [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün - [ ] Coverage-Gates erfüllt - [ ] Atomic Commits gepushed auf `agent/05-realtime-collab` - [ ] Detail-MD Progress-Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy - **Feature-Flag-Disable:** `realtime-collab-enabled` global oder pro Tenant. Wenn off, Editor läuft Single-User. - **Env-Disable:** `HOCUSPOCUS_URL` aus Env entfernen → Editor-Wrapper initialisiert keinen Provider, läuft im Legacy-REST-Save-Mode. - **Container-Removal:** docker-compose-Service stoppen + entfernen; Web-App funktioniert vollständig weiter. - **DB-Rollback:** `CollabDoc`-Tabelle gefahrlos droppbar (kein anderer Code referenziert sie). - **Data-Recovery bei Doc-Korruption:** Snapshot-History in `CollabDocArchive` erlaubt Restore. Bei Total-Loss-Doc: User-Lokal-Y.js-State kann re-uploaded werden (out-of-scope-Notfall-Tool). ## Security Notes - **JWT-Lifetime:** 15min ist kompromiss zwischen Replay-Risiko und Refresh-Aufwand. Client-Refresh alle 10min minimiert Connection-Drops. - **Cross-Tenant-Doc-Access:** DocumentName enthält tenantId. Auth-Hook prüft Token-Tenant vs Document-Tenant — Mismatch = refuse. Defense-in-Depth: Database-Extension prüft zusätzlich beim Store. - **Permission-Sync-Lag:** User verliert Permission während Connection aktiv → Connection bleibt zunächst. Mitigation: Permission-Re-Check auf Auth-Refresh-Roundtrip alle 10min. Bei kritischer Permission-Revoke → manual Connection-Drop via API. - **Resource-Exhaustion:** Hocuspocus-Connections sind langlebig. Limit per Tenant via Hocuspocus-`onConnect`-Hook prüft Concurrent-Connection-Count gegen Plan-Quota. Default 50/Tenant. - **CRDT-State-Bloat:** unbeschränkte Edits führen zu wachsendem Y.js-State. Snapshot-Strategy + periodische Compaction ($Yjs.encodeStateAsUpdate(doc)$) reduziert State-Size. - **WebSocket-Endpoint öffentlich:** Hocuspocus-Container exposed WebSocket-Port — sollte hinter Reverse-Proxy (Traefik/Caddy) mit TLS + ggf. Rate-Limit pro Source-IP stehen. ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit Detail-MD-Input. - **Research:** `Explore`-Subagent: "Analysiere existing Novel-Editor in apps/web/app/components/novel — welche Extensions sind schon geladen? Wo wird Save aktuell ausgelöst? Wie kann Collaboration-Extension non-invasive eingebaut werden?" - **Implementation Step 1-4 (Container + Persistence + Auth):** `general-purpose`-Subagent. - **Implementation Step 5 (Snapshot/Cleanup):** `general-purpose`-Subagent. - **Implementation Step 6-7 (Tiptap-Integration + Presence-UI):** `general-purpose`-Subagent + `subframe:design` für Presence-Bar. - **Implementation Step 8-9 (Degradation + JWT-Endpoint):** `general-purpose`-Subagent. - **Tests:** separater `general-purpose`-Subagent inkl. Two-Browser-Playwright-Setup. - **Verification:** `gsd-verifier` + manueller Two-Tab-Test. - **Code-Review:** `gsd-code-reviewer` + `security-review`-Skill (JWT/Permission kritisch). ## Staging-Deployment-Steps 1. Branch `agent/05-realtime-collab` pushen 2. Hocuspocus-Container in Coolify als neuen Service anlegen mit: ```yaml hocuspocus: image: environment: - DATABASE_URL=${DATABASE_URL} - HOCUSPOCUS_SECRET=${HOCUSPOCUS_SECRET} - PORT=1234 ports: - "1234:1234" restart: unless-stopped depends_on: - postgres ``` Traefik-Label für `wss://collab.staging.toolctrl.de` mit TLS-Termination + Subdomain-Routing. 3. `HOCUSPOCUS_URL=wss://collab.staging.toolctrl.de` und `HOCUSPOCUS_SECRET=` in Web-App-Env setzen 4. Migration `pnpm prisma migrate deploy` 5. Staging-Test: - Two-Browser-Test: zwei User-Sessions auf gleichem KB-Artikel → Live-Sync verifizieren - Awareness: Cursor + Presence-Bar zeigen beide User - Permission-Test: zweiter User mit removed-permission → Connection refused (Browser-Devtools-Network) - Hocuspocus-Container kurzzeitig stoppen → Offline-Indikator → Container restart → Re-Sync - Snapshot-DB-Check: nach 50+ Updates `SELECT version, lastSnapshotAt FROM "CollabDoc"` zeigt Increment - WebSocket-TLS-Check: `wscat -c wss://collab.staging.toolctrl.de` verbindet 6. Last-Test: 10 simultane Connections auf gleichem Doc — Sync-Latenz <300ms p95 ## Deviations from Plan - **Step 5 (Snapshot strategy + Cleanup-Cron) deferred** — initial slice ships Hocuspocus' default debounced persistence (2-10s). A follow-up will land `apps/worker/src/cron/collab-cleanup.ts` + the `CollabDocArchive` table + periodic `Y.encodeStateAsUpdate` compaction. - **Step 7 (Presence-Bar avatar-stack UI) deferred** — `CollaborationCursor` ships live name+colour cursor labels (the most visible piece of awareness). A dedicated avatar-stack sidebar is a UI polish follow-up. - **Auth permission helper integration deferred** — current `onAuthenticate` validates the JWT and matches its claims to the documentName triple. Per-resource permission helpers (e.g. KB-article read-permission check) are documented as a follow-up; the JWT already encodes the tenant scope so cross-tenant leakage is closed. - **Token-refresh client logic deferred** — the 15-minute JWT TTL is enforced; the editor relies on a fresh token being fetched per session today. A drop-in interval-refresh hook on `useHocuspocusProvider` is the natural extension. - **Rows + Workflow editor integrations deferred** — the Novel-Editor lands the pattern (hook + token endpoint + Tiptap extension factory). Other editors will reuse the same primitives in their own tasks. ## Progress Log - 2026-05-17 — `66a5e9f4` — hocuspocus server container scaffold (workspace app, Dockerfile, docker-compose service under `realtime` profile, minimal Server bootstrap with Logger extension wired into @toolctrl/logger). - 2026-05-17 — `56a8d786` — CollabDoc Prisma model + migration `20260517145000_05_collab_docs` (unique on tenantId+resourceType+resourceId, indexes on tenantId+resourceType+lastUpdatedAt and lastUpdatedAt). - 2026-05-17 — `3cd89b94` — JWT auth hook in apps/hocuspocus (verifies HS256, refuses on tenant/resourceType/resourceId mismatch). 12 unit tests. - 2026-05-17 — `f99fe4f1` — Postgres database extension (fetch/store against CollabDoc; max-payload guard; version increment). 8 unit tests. - 2026-05-17 — `bb845694` — Novel-Editor client integration: deps (`@hocuspocus/provider` 4.0.0, `@tiptap/extension-collaboration(-cursor)` 2.11.5, `yjs` 13.6.30, `y-prosemirror` 1.3.7, `y-protocols` 1.0.6), `useHocuspocusProvider` hook, conditional Collaboration + CollaborationCursor extensions, status banner, StarterKit history disabled when collab is active. 6 unit tests. - 2026-05-17 — `6f062692` — `POST /api/collab/token` issues 15-min HS256 JWT, gated behind `realtime-collab-enabled` feature flag (returns 403 when off → graceful single-user fallback) and `HOCUSPOCUS_AUTH_SECRET` env (returns 503 when missing). 6 unit tests. - 2026-05-17 — `1dccba6a` — env catalog entries (HOCUSPOCUS_AUTH_SECRET, VITE_HOCUSPOCUS_URL, HOCUSPOCUS_URL/PORT/HOST/MAX_PAYLOAD_BYTES) + `docs/features/realtime-collab.md` (architecture, activation, embedding contract, graceful degradation).