Scrum4Me/docs/plans/landing-local-first.md

title	status	audience	language	last_updated	applies_to	story_id	pbi_id
Landing v2 — lokaal & veilig + architectuurdiagram	active	maintainer contributor	nl	2026-05-03	SCRUM4ME	cmoq2qoik0001qa175iynfnaa	cmoq2q50s0000qa174rmrjove

Landing v2 — lokaal & veilig + architectuurdiagram

Story: Als bezoeker van de landingspagina wil ik direct begrijpen dat Scrum4Me's unieke propositie is dat code-uitvoering lokaal blijft op mijn eigen hardware, zodat ik weet of dit product bij mijn werkwijze past.

Branch: feat/landing-local-first

Context

Sinds de laatste landingspagina-update (commit feat(landing): highlight realtime updates and beta/desktop-first notice, 2026-04-27, app v0.4.0) zijn meerdere milestones afgerond of in uitvoering die niet op de pagina staan:

• M5 — Todo's
• M8 — Realtime Solo Paneel (Postgres LISTEN/NOTIFY + SSE)
• M9 — Active Product selectie
• M10 — QR-pairing passwordless login
• M11 — Claude question channel
• M13 — Claude job queue + worker mode
• MCP-server in losse repo madhura68/scrum4me-mcp met 18 tools

Belangrijker: het echte unieke aspect — dat code-uitvoering lokaal blijft op de developer's eigen hardware — staat nergens prominent op de huidige pagina. De Vercel-app + Neon-DB zijn een coördinatielaag voor metadata; klantcode draait nooit in de cloud. Dat is dé propositie en moet bovenaan staan, ondersteund door een architectuurdiagram dat GitHub + Neon Postgres + Vercel + Lokale worker in samenhang toont.

Genuanceerde claim (geen overpromise). In Neon staan wél: Task.implementation_plan, StoryLog.content/commit_message, ClaudeJob.plan_snapshot/summary/error, ClaudeQuestion.question — vrije-tekstvelden die agents/users zelf invullen. Wat niet in de cloud belandt: broncodebestanden, diffs/patches, build-artefacten. De hero claimt dit voorzichtig ("executie + code blijven aan jouw kant"); de architectuur-sectie legt per box uit wat er wél staat.

Doelgroep

Mix met zwaartepunt op (a) privacy-bewuste indie devs en (c) kleine teams met homelab/NAS. Compliance-publiek (b) wordt niet expliciet aangesproken (geen SOC2-claims), maar ook niet uitgesloten.

Aanpak — sectievolgorde

#	Sectie	Wijziging
1	Header	ongewijzigd
2	Hero	herschreven (B+Z, zie hieronder)
3	Architectuur	nieuw — twee-zone mermaid-diagram + 4 callouts
4	Tour (screenshots)	ongewijzigd
5	Wat is Scrum4Me?	6 kaarten (set C, zie hieronder)
6	Quickstart: lokale agent in 3 stappen	vervangt "Twee manieren om Claude te koppelen"
7	Scrum in Scrum4Me	ongewijzigd
8	Gebruikershandleiding	uitgebreid naar 10 stappen, MCP als hoofdroute
9	REST API	ongewijzigd
10	Footer	+ link naar madhura68/scrum4me-mcp

LIVE-callout onder de feature-grid vervalt (gaat op in feature-card "Realtime updates").

Sectie-detail

§2 Hero

• H1: "Plannen in de cloud. Uitvoeren op je eigen machine."
• Subhead: "De UI draait op Vercel, je code draait op jou. Een gedeelde job-queue laat lokale Claude Code agents (laptop, NAS of VM) stories autonoom oppakken — zonder dat je broncode ooit de cloud hoeft te raken."
• CTA's: "Account aanmaken" (primary) · "Hoe het werkt" (secondary, anchor naar #architectuur). De oude "Demo bekijken" vervalt; demo-credentials staan al in de body-tekst eronder.
• Beta-notice blok: ongewijzigd.

§3 Architectuur (nieuw)

Diagrambron: docs/diagrams/architecture.mmd (mermaid). Twee zones via subgraph:

flowchart LR
    User([Jij in je browser]):::user

    subgraph Scrum["Scrum4Me-stack (managed)"]
        direction TB
        Vercel["Vercel<br/>UI · Server Actions · cron"]
        Neon[("Neon Postgres<br/>metadata · jobs · logs")]
        Vercel <-->|Prisma + SSE| Neon
    end

    subgraph Yours["Jouw kant (lokaal)"]
        direction TB
        Worker["Lokale worker<br/>laptop / NAS / VM<br/>Claude Code + MCP"]
        GitHub[("GitHub<br/>jouw repo")]
        Worker -->|git push| GitHub
    end

    User -->|HTTPS| Vercel
    Neon <-.->|job claim<br/>+ LISTEN/NOTIFY| Worker

    classDef user fill:none,stroke-dasharray:3 3

Renderpijp:

• Bron in docs/diagrams/architecture.mmd.
• Output naar public/diagrams/architecture-light.svg + architecture-dark.svg (gecommit in git).
• Nieuw npm-script: "diagrams": "mmdc -i docs/diagrams/architecture.mmd -t default -b transparent -o public/diagrams/architecture-light.svg && mmdc -i docs/diagrams/architecture.mmd -t dark -b transparent -o public/diagrams/architecture-dark.svg".
• Geen prebuild-hook — handmatig draaien bij wijziging.
• In page.tsx: twee <Image>-tags, één met className="dark:hidden" en één met className="hidden dark:block".

Onder het diagram, 4 callout-cards "Wat draait waar?":

1. Vercel — alleen UI, Server Actions en cron. Geen sourcecode, geen build-artefacten.
2. Neon Postgres — Scrum-metadata, plan-tekstvelden, logs en commit-hashes. Geen volledige diffs, geen broncodebestanden.
3. Lokale worker — jouw machine. Claude Code via stdio-MCP, claimt jobs (FOR UPDATE SKIP LOCKED), executeert lokaal, commit lokaal, push lokaal. Multi-worker (laptop + NAS) parallel veilig.
4. GitHub — jouw eigen repo. Scrum4Me kent alleen de repo_url-string en commit-hashes uit logs.

§5 Feature-kaarten (6 stuks, set C)

1. Hiërarchisch plannen — Product → PBI → Story → Taak.
2. Sprint Board + Solo Paneel — twee weergaven van dezelfde data: team-bord en persoonlijk Kanban.
3. Lokale Claude-agents — job-queue, "Voer uit"-knop, atomic claim, multi-worker.
4. Realtime updates — SSE + Postgres LISTEN/NOTIFY; UI binnen 1–2s in sync (vervangt LIVE-callout).
5. Async vraagkanaal — Claude vraagt input via bel-icoon zodra plan-ambiguïteit optreedt.
6. Todo's — lichtgewicht notities los van sprint-hiërarchie.

QR-login en Active Product selection krijgen géén kaart (QR-login wel genoemd in handleiding stap 1).

§6 Quickstart (vervangt "Twee manieren")

Activerende sectie met code-snippet:

# 1. Clone en installeer de MCP-server
git clone https://github.com/madhura68/scrum4me-mcp
cd scrum4me-mcp && npm install

# 2. Voeg toe aan Claude Code config (zie repo-README)
# 3. Start Claude Code en vraag:
#    "pak de volgende job uit de Scrum4Me-queue"

Daarnaast korte tekst-bullet: "Liever zonder MCP? Gebruik de REST API met een Bearer-token (zie API-overzicht hieronder)."

§8 Handleiding — 10 stappen

1. Account aanmaken (+ bijzin: "of paar je telefoon één keer en log voortaan in via QR")
2. Product aanmaken
3. Product Backlog opbouwen
4. Sprint starten
5. Sprint Board
6. Solo Paneel
7. API-token aanmaken (nodig voor MCP én REST)
8. Claude Code koppelen — installeer scrum4me-mcp (aanbevolen) of gebruik REST API
9. Story laten uitvoeren — klik "Voer uit", lokale agent pakt 'm op via wait_for_job, commit + status-update gaan automatisch; NavBar toont actieve workers
10. Sprint afronden

§10 Footer

Voeg link toe naar https://github.com/madhura68/scrum4me-mcp naast bestaande Scrum4Me-repo-link. Geen drie-kolommen-layout.

Bestanden

Wijzigen:

• app/page.tsx — alle sectie-aanpassingen
• package.json — nieuwe diagrams-script

Nieuw:

• docs/diagrams/architecture.mmd — mermaid-bron
• public/diagrams/architecture-light.svg — gegenereerd
• public/diagrams/architecture-dark.svg — gegenereerd

Referentie (geen edits):

• docs/runbooks/mcp-integration.md
• docs/architecture/claude-question-channel.md
• docs/plans/ST-1111-claude-job-trigger.md

Wat we niet doen

• Geen losse /architecture-route — diagram blijft op homepage.
• Geen extracted components onder components/landing/.
• Geen runtime-mermaid (zou ~350KB bundle-impact zijn).
• Geen prebuild-hook.
• Geen Engelse vertaling.
• Geen wijziging aan theme.css of shadcn-config.
• Geen LIVE-callout meer onder feature-grid.
• Geen drie CTA's in hero.

Verificatie

npm install
npm run diagrams
npm run dev    # http://localhost:3000 in 1024px+

Visueel checken:

• Hero leest "Plannen in de cloud. Uitvoeren op je eigen machine."
• Architectuur-sectie toont diagram met twee zones; in dark-mode switcht automatisch.
• Anchor-link #architectuur werkt vanuit hero-CTA.
• Feature-grid toont 6 kaarten in lg:grid-cols-3 over 2 rijen.
• Quickstart-codeblock leesbaar en kopieerbaar.
• Handleiding heeft 10 stappen, MCP staat in stap 8 als aanbevolen.
• Footer toont MCP-repo én Scrum4Me-repo.
• Demo-credentials nog steeds zichtbaar onder hero-CTA's.

npm run lint && npm test && npm run build

Daarna pas commit. Niet pushen zonder bevestiging (CLAUDE.md hardstop).

Grilling-uitkomsten (samenvatting)

15 vragen via /grill-me op 2026-05-03 hebben volgende beslissingen vastgelegd:

#	Onderwerp	Beslissing
1	Veiligheidsclaim	Genuanceerd: hero zacht, architectuur-sectie eerlijk over plan-tekstvelden in DB
2	Doelgroep	Mix (D), zwaartepunt op privacy-bewuste indie + homelab-team
3	Diagram-nodes	4 boxen + label "Lokale worker (laptop / NAS / VM)"
4	Renderkeuze	Mermaid via mmdc (al in repo)
5	Diagram-zonering	Twee subgraphs (Scrum4Me-stack vs Jouw kant)
6	Embedding	<Image> x2, light + dark SVG, switch via Tailwind
7	Hero-copy	H1 "Plannen in de cloud. Uitvoeren op je eigen machine." + subhead Z
8	Sectievolgorde	Architectuur op #3, Tour op #4
9	Feature-cards	Set C: 6 stuks, Sprint+Solo gecombineerd, Todo's erbij
10	Handleiding	10 stappen, MCP als hoofdroute, "Voer uit" als stap 9
11	Diagram-bron	docs/diagrams/architecture.mmd, output gecommit
12	Twee manieren → Quickstart	Vervangen door code-snippet
13	Hero-CTA's	"Account aanmaken" + "Hoe het werkt" (anchor)
14	Plan-bestand	Story aangemaakt, plan in docs/plans/landing-local-first.md
15	Beta + LIVE + Footer	Beta-notice behouden, LIVE-callout schrappen, één extra footer-link