Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/05-business-features/realtime-collab.md
T

18 KiB

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/<ts>_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:
    hocuspocus:
      image: <built-image-from-apps/hocuspocus>
      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=<generated> 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).