Scrum4Me/docs/plans/archive/2026-04-27-m8-realtime-solo.md

title	status	audience	language	last_updated	applies_to
Realtime updates voor Solo Paneel (M8)	done	maintainer contributor	nl	2026-05-03	M8

Plan: Realtime updates voor Solo Paneel (M8)

Aanleiding

Wanneer Lars in zijn Solo Paneel werkt en parallel Claude Code (via MCP) of Codex aan dezelfde sprint sleutelt, ziet hij de gevolgen pas na een refresh. We willen DB-wijzigingen op tasks/stories van zijn actieve sprint live in beeld zien. Vraag van de gebruiker: "open een websocket".

Transport-keuze — niet écht een WebSocket

Vercel-deploys ondersteunen geen stateful native WebSockets in serverless of Edge functions. Drie reële opties:

Optie	Werkt op Vercel	Externe dienst	Latency	Complexiteit
A. SSE + Postgres LISTEN/NOTIFY	✅ (Node runtime, streaming response)	nee	<100ms na DB-write	gemiddeld
B. SSE + polling 2–3s	✅	nee	1–3s	laag
C. Pusher/Ably (echte WS)	✅	ja (gratis tier)	<50ms	laag, maar elke schrijver moet publishen

Voorgestelde keuze: A — SSE met Postgres LISTEN/NOTIFY.

Reden:

• Eén bron van waarheid: de DB. Web-mutations, REST-API én MCP schrijven allemaal naar Postgres; een trigger NOTIFY't onafhankelijk van de schrijver. Geen coördinatie nodig met mcp.
• Geen externe dienst, geen extra dep, geen kosten erbij.
• Neon ondersteunt LISTEN/NOTIFY op directe verbindingen. DIRECT_URL is al geconfigureerd.
• Naar de client toe: éénrichtingsverkeer — server pusht events, client doet mutaties via bestaande Server Actions/REST. SSE volstaat dus; we hoeven geen full-duplex.
• Voor de gebruiker is het verschil onmerkbaar: realtime updates komen binnen, browsers ondersteunen EventSource native.

We kiezen B (polling) niet omdat het meer DB-load geeft en je Pusher-achtige latency niet haalt. We kiezen C niet vanwege coördinatieoverhead met de MCP-server (extra publish-step in mcp).

Architectuur

┌─────────────────────────────────────────────────────────────────────────┐
│  Postgres (Neon)                                                        │
│  ┌────────────────────────┐                                             │
│  │ TRIGGER on tasks       │──► pg_notify('scrum4me_solo', payload_json) │
│  │ TRIGGER on stories     │                                             │
│  └────────────────────────┘                                             │
└──────────────┬──────────────────────────────────────────────────────────┘
               │ LISTEN scrum4me_solo
               ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  Next.js Node.js runtime route: /api/realtime/solo                      │
│  - auth via iron-session cookie                                         │
│  - opent dedicated pg client (DIRECT_URL), LISTEN scrum4me_solo         │
│  - filtert events: alleen tasks/stories in actieve sprint van een       │
│    product waar user lid/eigenaar is, EN (assignee_id == user OR        │
│    onbeklemtoonde unassigned-story-list)                                │
│  - stuurt SSE: data: {type, entity, id, fields} \n\n                    │
│  - heartbeat \n\n elke 25s                                              │
│  - sluit zelf na 4 min (Vercel maxDuration safety); client reconnect    │
└──────────────┬──────────────────────────────────────────────────────────┘
               │ EventSource('/api/realtime/solo?product_id=...')
               ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  Browser — Solo Paneel                                                  │
│  - useSoloRealtime(productId) hook                                      │
│  - reconnect met exponential backoff (max 30s)                          │
│  - Page Visibility API: close on hidden, reopen on visible              │
│  - dispatcht naar solo-store: applyTaskUpdate, applyTaskCreate,         │
│    applyTaskDelete, applyStoryUpdate (assignee/title/status)            │
│  - reconcile-policy: skip update als optimistic in-flight is voor die   │
│    task; anders server wint                                             │
└─────────────────────────────────────────────────────────────────────────┘

Filtering — wie krijgt welke events?

De trigger NOTIFY't elke task/story-mutatie globaal. De SSE-handler is verantwoordelijk voor toegangs- en relevantie-filtering:

1. Toegang: alleen events waarvan de gerelateerde story.product_id in productAccessFilter(userId) zit.
2. Sprint-scope: alleen events binnen de actieve sprint van het product dat in de query-parameter zit.
3. Persoonlijke relevantie: tasks waar story.assignee_id == userId (jouw kolommen), plus stories met assignee_id == null (de "claim me" lijst).

Per event extra DB-roundtrip om dit te checken zou duur zijn. Twee oplossingen, bij voorkeur (b):

(a) Triggerpayload bevat product_id, sprint_id, assignee_id zodat de handler in-memory kan filteren — geen extra DB-call.

(b) Cache in handler: bij connect resolveert de handler userId → activeSprintId, productId, assignedStoryIds. Bij elke notify checkt het de payload tegen die set; bij story-create/assignee-change herwoordt het de set on demand.

Strategie: combineer (a) trigger zet product_id en assignee_id in de payload + (b) handler cacht (activeSprintId, productId, accessibleProducts) voor de connectie-duur.

Concrete implementatie — stories

ST-801 Postgres LISTEN/NOTIFY-infrastructuur

• Migration prisma/migrations/<ts>_add_solo_realtime_triggers/migration.sql:
  • CREATE OR REPLACE FUNCTION notify_solo_change() RETURNS TRIGGER ... — bouwt JSON met op (INSERT/UPDATE/DELETE), entity (task/story), id, product_id, sprint_id, assignee_id, fields (alleen gewijzigde kolommen bij UPDATE)
  • Triggers AFTER INSERT OR UPDATE OR DELETE ON tasks, idem op stories
• Pas prisma migrate deploy toe (idempotent, geen schema-wijziging dus geen TS-impact)
• Done when: psql $DIRECT_URL -c "LISTEN scrum4me_solo;" toont een payload bij UI-mutatie

ST-802 SSE-route /api/realtime/solo

• Bestand app/api/realtime/solo/route.ts, runtime: 'nodejs', maxDuration: 300
• Gebruikt pg.Client (niet de Prisma adapter — directe LISTEN-verbinding)
• Auth via iron-session, 401 zonder cookie
• Query-parameter product_id, 403 zonder access
• Resolveert active sprint id eenmalig; cachet die in connection-scope
• ReadableStream met heartbeat-interval 25s, hard close na 240s
• Filter per event op product_id == requested && (assignee_id == userId || (entity == 'story' && assignee_id == null))
• Logged via console.error bij pg-disconnect
• Done when: handmatig met curl -N op localhost krijg je events binnen 1s na een UI-mutatie

ST-803 Client hook useSoloRealtime(productId)

• lib/realtime/use-solo-realtime.ts (client-only)
• Opent EventSource('/api/realtime/solo?product_id=' + productId)
• Reconnect: exponential backoff start 1s → 30s, reset op succesvolle connect
• Page Visibility: document.visibilityState === 'hidden' → close; bij visible → reopen
• Cleanup op unmount
• Dispatcht events naar solo-store via nieuwe acties (zie ST-804)
• Done when: tab wisselen sluit/opent connectie zichtbaar in DevTools Network

ST-804 Solo-store realtime-acties

• Uitbreiden stores/solo-store.ts:
  • applyTaskUpdate(taskId, fields) — merge in tasks-record; skip als pendingOps[taskId] set is
  • applyTaskCreate(task) — alleen als de task in de eigen kolommen hoort (assignee_id == userId)
  • applyTaskDelete(taskId)
  • applyStoryAssignment(storyId, assigneeId) — re-fetch unassigned-list (kleine GET) of ontvang als deel van payload
  • markPending(taskId)/clearPending(taskId) — optimistic-flow markeert mutaties die we zelf doen, zodat we de echo van onze eigen NOTIFY niet dubbel verwerken
• Done when: unit-test op solo-store met simulated events laat juiste state zien

ST-805 Wire-up in SoloBoard

• components/solo/solo-board.tsx: roep useSoloRealtime(productId) aan na useEffect-init van tasks
• Klein "live" / "verbinden..." status-indicator (status uit hook): groene stip / pulserende grijze stip
• Toast bij langer dan 5s disconnected
• Done when: open Solo paneel in twee tabs, mutate task in tab A, zie status flippen in tab B binnen 1–2s zonder refresh

ST-806 Documentatie + acceptatietest

• Update docs/architecture.md: nieuwe sectie "Realtime updates" met diagram en filtering-regels
• Update CLAUDE.md: vermelding dat Solo Paneel realtime is + dat MCP-writes vanzelf doorkomen
• Update docs/api/rest-contract.md: korte note over /api/realtime/solo (Bearer auth, SSE format)
• E2E-acceptatie: lijst van scenario's (zelfde gebruiker twee tabs, MCP-write, REST-write, story-claim, network-flap) handmatig getest
• Done when: scenario's lopen door zonder onverwachte gedragingen

Backlog-edits

In docs/backlog/index.md:

1. Milestone-overzicht — rij toevoegen onder M7:

   | M8: Realtime Solo Paneel | Live updates voor stories/tasks via SSE+LISTEN/NOTIFY | ST-801 – ST-806 |
   

2. Sectie M8 toevoegen na de M7-sectie, met de zes stories hierboven (ST-801..ST-806) inclusief "Done when"-criteria. Allemaal [ ] (nog niet gestart).

Wijzigingen elders

• .env.example blijft ongewijzigd (DIRECT_URL stond er al)
• docs/architecture.md — sectie "Realtime updates" met diagram en regel "alle UPDATE-triggers zitten op tasks/stories; nieuwe entiteiten erbij vragen om uitbreiding van de trigger-functie"
• Geen wijziging in lib/code.ts of lib/code-server.ts — dit is server-only realtime
• Schema-drift agent in mcp pikt de migratie automatisch op (geen Prisma-modelwijziging maar wel een nieuwe migratie); typecheck blijft groen omdat we geen Prisma Client-wijziging hebben

Risico's en mitigaties

Risico	Mitigatie
Vercel sluit Node-route na maxDuration	Hard-close server-side bij 240s + automatische client-reconnect; gebruiker merkt dit niet
Echo van eigen optimistic mutation	markPending/clearPending in solo-store; skip als pendingOps[taskId] set is
Connection leaks (open pg.Client's)	req.signal.addEventListener('abort') cleanup; bij Edge cold-start sluit Vercel zelf
Trigger overhead op writes	Triggers zijn lichtgewicht (één pg_notify call); meet bij rollout
Oude pg_notify payloads >8kb	Zorg dat we alleen primitives (id, status, sort_order, etc.) sturen — geen description/implementation_plan in de payload, daar is een refetch voor
Test-DB heeft geen triggers	Migratie automatisch toegepast in CI (Prisma migrate deploy); bestaande tests blijven groen
MCP-server schema-sync detecteert migratie als drift	False alarm — wekelijkse cron rapporteert "schema-prisma diff", maar typecheck blijft groen omdat het alleen migratie-SQL is. Beoordeel handmatig bij rapport

Wat dit NIET oplost

• Realtime in Sprint Backlog of Product Backlog — alleen Solo Paneel
• Conflict-merge bij gelijktijdige updates van twee gebruikers (last-write-wins blijft)
• Mobile pagina (out of scope desktop-first MVP)
• Audit-trail van wie wat wanneer veranderde (bestaat al via StoryLog)

Volgorde van uitvoering

1. Branch feat/m8-realtime-solo van main
2. ST-801 (migratie + trigger) — commit, lokaal verifiëren met psql LISTEN
3. ST-802 (SSE-route) — commit, curl -N lokaal testen tegen lokale UI-mutatie
4. ST-803 (client hook) — commit
5. ST-804 (store-uitbreiding) — commit, met unit-test
6. ST-805 (wire-up + UI-indicator) — commit
7. ST-806 (docs + acceptatie) — commit
8. PR openen — Vercel preview-deploy laat realtime werken op preview-DB (mits trigger via migrate deploy mee)
9. Na review: merge

Geschatte size

• ~6 stories, ~12–18 commits
• 1 migratie, 1 nieuwe route, 1 nieuwe hook, kleine store-uitbreiding, UI-indicator
• ~400 regels code + ~80 regels docs
• 1 PR