Madhura68 96e4423485 docs(PBI-80): ADR-0006 addendum + demo-client-state patroon (ST-1347)

ADR-0006 krijgt een "Updated 2026-05-12"-sectie die de PBI-80-uitzondering
documenteert: client-side UI-prefs (filters, sort, layout, scope-keuze) zijn
voor demo toegestaan via in-memory store, terwijl alle data-mutaties three-layer
beschermd blijven. Patroon-doc beschrijft wanneer en hoe `isDemo` te gebruiken
in nieuwe componenten. CLAUDE.md quickref + docs/INDEX.md ge-update.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-12 19:33:25 +02:00

2.8 KiB

Raw Blame History

ADR-0006: Demo-user write protection enforced in three layers

Status

accepted

Context

Scrum4Me has a demo account that allows prospective users to explore the app without signing up. The demo user must never be able to create, update, or delete any data. A single guard at one layer is insufficient: a bug or a missing check in any one layer would expose a write path. See docs/architecture/auth-and-sessions.md and docs/plans/ST-1110-demo-readonly.md for implementation details.

Decision

Write protection for the demo user is enforced at three independent layers:

Network — proxy.ts: The Next.js proxy middleware rejects all non-GET requests from demo sessions before they reach any route handler or server action.
Server — every Server Action and Route Handler: Each write endpoint checks session.isDemo and returns 403 immediately if true.
UI — disabled buttons + <DemoTooltip>: Write controls (create, edit, delete, reorder) are rendered as disabled with a tooltip explaining the demo restriction. No write request is ever sent.

Consequences

Positive

Defense-in-depth: any single layer can fail independently without exposing a write path.
Clear user feedback at the UI layer without relying on error responses.
Straightforward to audit: search for isDemo to find all enforcement points.

Negative

Three enforcement sites for every new write operation — easy to miss one when adding a new feature.
Mitigation: the DemoTooltip pattern is documented in docs/patterns/ and enforced in code review.

Updated 2026-05-12 — Exception for client-side UI preferences

PBI-80 relaxes the policy for client-side UI preferences only:

Allowed for demo: product-switch and sprint-switch via URL navigation, filters/sort, layout state (split-panes, collapsed PBIs, selections) — routed through the in-memory useUserSettingsStore.
Why this is safe: none of these touch the database. The demo user is a single shared row, but each visitor's browser holds its own Zustand store and URL state. A refresh resets to seed defaults; visitors never see each other's choices.
Unchanged — three-layer enforcement still applies to: all data mutations (PBI/story/task/sprint create/update/delete/reorder), account fields (username, password, email), role assignment, QR-pairing, web-push, and any cron/webhook secrets.
Pattern for new demo-friendly features: if it is UI state, route it through useUserSettingsStore.setPref (which already has a demo-fork at stores/user-settings/store.ts:80) or pure URL navigation via router.push. Never call a server action for demo. See docs/patterns/demo-client-state.md.

2.8 KiB Raw Blame History