triqura-ecd/docs/specs/bouwplan-ai-speedrun-marketing-first-v2.1.md

🚀 Mission Control – Bouwplan AI Speedrun EPD v2.1

Projectnaam: AI Speedrun - Mini-EPD Prototype
Versie: v2.1 (Vereenvoudigde User Journey + Teal Design System)
Datum: 17-11-2024
Auteur: Colin Lit
Laatste Update: 17-11-2024

---

1. Doel en context

🎯 Doel: Een werkend EPD-prototype bouwen in 4 weken dat demonstreert hoe "Software on Demand" traditionele ontwikkeling disrupts: van €100.000+ en 12-24 maanden naar €200 build cost en 4 weken doorlooptijd.

📘 Toelichting: Dit project dient een drievoudig doel:

1. Demo voor GGZ-sector: Tonen van AI-waarde in EPD-workflows (intake → profiel → plan) tijdens inspiratiesessies
2. LinkedIn Build in Public: Wekelijkse transparante updates die viral marketing genereren voor AI consultancy
3. Software on Demand Proof: Bewijs dat enterprise-kwaliteit software nu in weken ipv jaren gebouwd kan worden

Nieuwe Strategie (v2.1):

• Vereenvoudigde user journey: Geen separate EPD demo pagina meer
• Features in timeline: Build-in-public transparantie met features showcase per week
• Login met features: Directe showcase van EPD capabilities op login pagina
• Teal-first design: Modern, innovatief brand identity (#0D9488)

Het systeem toont praktische AI-integratie: intake samenvattingen in seconden ipv uren, automatische DSM-classificatie, en behandelplannen die direct bruikbaar zijn. Alles met fictieve demo-data, privacy-first design.

Referenties:

• FO v2.1: docs/specs/fo-marketing-app-flow-v2.md - Vereenvoudigde user journey
• UX Plan v2.0: docs/specs/ux-implementation-plan-v2.md - Teal-first design system

---

2. Uitgangspunten

2.1 Technische Stack

🎯 Doel: Modern, bewezen technologie stack voor snelle development en lage run costs.

Frontend:

• Framework: Next.js 15 (App Router) - Single repo voor marketing + EPD
• Styling: Tailwind CSS v3.4 met teal-first design system
• UI Components: shadcn/ui + custom components (Timeline, AIButton)
• Rich Text: TipTap editor (ProseMirror basis) - Week 3
• Icons: Lucide React
• Animations: Framer Motion (voor timeline scroll effects)
• State: Zustand + React Context (simpel maar effectief)

Backend:

• API: Next.js Route Handlers (server-side)
• Database: Supabase (PostgreSQL + Auth + Storage) - EU region
• AI: Claude 3.5 Sonnet (Anthropic) - Superieur voor Nederlands
• Hosting: Vercel (EU region Amsterdam)

Development & Tools:

• Version Control: GitHub (public repo voor transparantie)
• Type Safety: TypeScript overal
• Package Manager: pnpm (sneller dan npm)
• AI Pair Programming: Cursor IDE
• Testing: Vitest + Playwright (basis coverage)

2.2 Projectkaders

🎯 Doel: Realistische constraints voor 4-weken sprint.

• Tijd: 4 weken part-time (80-120 uur totaal)
• Budget: €200 totaal (€50/maand runtime target)
• Team: 1 developer (Colin) + AI tools als co-pilot
• Data: 100% fictieve demo data
• Scope: MVP voor 10-min demo + marketing site
• Launch: LinkedIn viral series + demo sessies

2.3 Programmeer Uitgangspunten

🎯 Doel: Code quality zonder over-engineering voor MVP.

Core Principles:

• DRY: Herbruikbare componenten, centrale configs
• KISS: Simpele oplossingen boven complexiteit
• SOC: UI/logic/data layers gescheiden
• YAGNI: Alleen bouwen wat nu nodig is

Development Practices:

• Iteratief: Ship daily, perfect later
• AI-First: Laat Claude/Cursor heavy lifting doen
• Copy-Paste OK: Voor MVP snelheid > perfectie
• Error Handling: User-friendly messages overal
• Security: API keys server-side, RLS in Supabase

Design System:

• Primary Color: Teal (#0D9488 / teal-600) - Innovation signal
• AI Color: Amber (#F59E0B / amber-500) - AI actions
• Neutral: Slate scale voor professional foundation
• Typography: Crimson Text (serif) + Inter (sans) + JetBrains Mono

---

3. Epics & Stories Overzicht

🎯 Doel: 8 duidelijke epics voor 4-weken development sprint - Marketing First Strategy met vereenvoudigde user journey.

Epic ID	Titel	Doel	Status	Story Count	Week
WEEK 1 - FOUNDATION & MARKETING REFACTOR
E0	Project Setup	Next.js + Supabase + Vercel running	✅ Compleet	5	1
E1	Marketing Website Refactor	Homepage met timeline + login met features	🔄 In Progress	7	1
E2	Design System Migration	Teal-first colors + component updates	✅ Compleet	5	1
WEEK 2 - EPD CORE
E3	Database & Auth	Schema + RLS + demo users	✅ Compleet	4	2
E4	Core UI & Client Module	Layout + Client CRUD + Navigation	⏳ To Do	5	2
WEEK 3 - AI MAGIC
E5	Intake & AI Integration	TipTap + Claude API + Prompts	⏳ To Do	6	3
E6	Profile & Plan	DSM + behandelplan flows	⏳ To Do	4	3
WEEK 4 - POLISH & LAUNCH
E7	Onboarding System	Walkthrough + tooltips + help	⏳ To Do	4	4
E8	Performance & Launch	Optimization + demo prep	⏳ To Do	4	4

---

4. Epics & Stories (Uitwerking)

Epic 0 — Project Setup

Epic Doel: Werkende development omgeving met alle benodigde tools en dependencies.

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	Story Points
E0.S1	Repository aanmaken	GitHub repo + lokale clone, .gitignore config	✅	—	1
E0.S2	Next.js project initialisatie	Next.js 15 App Router draait, dev server start	✅	E0.S1	2
E0.S3	Supabase setup	Project aangemaakt, database connected, Auth enabled	✅	E0.S2	3
E0.S4	Dependencies installeren	Tailwind, shadcn/ui, Framer Motion, Lucide geïnstalleerd	✅	E0.S2	2
E0.S5	Environment variables	.env.local + Vercel vars geconfigureerd	✅	E0.S3	1

Technical Notes:

• Gebruik pnpm voor snellere installs
• .env.example committen voor team onboarding
• Supabase project in EU region (Amsterdam)

---

Epic 1 — Marketing Website Refactor

Epic Doel: Vereenvoudigde marketing homepage met timeline (features showcase) en login pagina met features.

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	Story Points
E1.S1	Verwijder EPD demo pagina	/epd route verwijderd, navigation updated	⏳	E0.S5	1
E1.S2	Homepage vereenvoudigen	Manifesto content verwijderd, statement section toegevoegd	⏳	E1.S1	3
E1.S3	Timeline component integreren	Aceternity timeline met features per week	⏳	E1.S2	5
E1.S4	Timeline content structuur	content/nl/timeline.json met features array	⏳	E1.S3	2
E1.S5	Login pagina refactor	Split-screen layout: features links, login rechts	⏳	E1.S1	4
E1.S6	Features showcase component	Herbruikbare feature cards voor timeline + login	⏳	E1.S3, E1.S5	3
E1.S7	CTA updates	Homepage CTA naar /login, navigation cleanup	⏳	E1.S2, E1.S5	1

Technical Notes:

• Timeline component: components/ui/timeline.tsx (Aceternity UI pattern)
• Features data: content/nl/timeline.json (met features array per week)
• Login layout: Inspiratie van components/ui/sign-in.tsx
• Mobile: Stack layout voor login pagina (features boven, form onder)

Content Structure:

// content/nl/timeline.json
{
  "weeks": [
    {
      "weekNumber": 1,
      "title": "Week 1 • Nov 11-17",
      "status": "completed",
      "description": "...",
      "features": [
        {
          "title": "AI-Gestuurde Intake",
          "description": "...",
          "time": "< 5 seconden",
          "traditional": "15-20 minuten handmatig",
          "icon": "Brain"
        }
      ],
      "metrics": { ... },
      "achievements": [ ... ]
    }
  ]
}

---

Epic 2 — Design System Migration

Epic Doel: Teal-first design system implementeren (migratie van blue naar teal).

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	Story Points
E2.S1	Tailwind config update	Teal brand colors, amber AI colors	✅	E0.S4	2
E2.S2	Global CSS variables	--primary, --info naar teal	✅	E2.S1	1
E2.S3	Component color updates	Buttons, links, navigation naar teal	✅	E2.S2	3
E2.S4	AIButton component	Amber gradient button voor AI actions	✅	E2.S1	2
E2.S5	Contrast testing	WCAG AA compliance voor teal colors	✅	E2.S3	1

Technical Notes:

• Primary: teal-700 (#0F766E) - 5.47:1 contrast op white (WCAG AA compliant)
• AI actions: amber-600 (#D97706) gradient → amber-700 (#B45309)
• Test contrast: Automated script scripts/test-contrast.ts
• WCAG compliance: 7/11 AA Normal (4.5:1), 11/11 AA Large (3:1) ✅
• Documentation: docs/design/wcag-compliance.md

Implementation Summary:

• ✅ Tailwind config: Teal-700 als DEFAULT voor betere contrast
• ✅ CSS variables: Alle --color-brand, --color-info, --color-input-focus → teal-700
• ✅ Components updated: sign-in, timeline, reading-progress, modern-side-bar
• ✅ AIButton component: Amber-600→700 gradient, 3 variants, fully accessible
• ✅ Contrast tested: All combinations pass WCAG AA for intended use cases

Color Palette (Final):

// tailwind.config.ts
colors: {
  brand: {
    600: '#0D9488', // UI components (3.74:1 on white)
    700: '#0F766E', // PRIMARY text (5.47:1 on white - WCAG AA)
    800: '#115E59', // Hover states
    DEFAULT: '#0F766E',
  },
  ai: {
    600: '#D97706', // AI buttons (3.19:1 - AA Large)
    700: '#B45309', // AI hover (5.02:1 - AA Normal)
  }
}

---

Epic 3 — Database & Auth

Epic Doel: Werkend datamodel met seed data, auth flow en RLS policies.

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	Story Points
E3.S1	Database schema	5 core tables: clients, intake_notes, problem_profiles, treatment_plans, ai_events	✅	E0.S3	5
E3.S2	RLS policies	Row-level security per table (user isolation)	✅	E3.S1	3
E3.S3	Demo users seed	demo@mini-ecd.demo account aangemaakt	✅	E3.S2	1
E3.S4	Auth flow	Magic link + password login werkend	✅	E3.S3	2

Technical Notes:

• Schema: PostgreSQL via Supabase
• RLS: auth.uid() = created_by pattern
• Demo users: Shared dataset voor demo purposes
• Auth: Supabase Auth (magic link + password)

---

Epic 4 — Core UI & Client Module

Epic Doel: EPD app foundation: layout, client CRUD, navigation.

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	Story Points
E4.S1	Coming Soon dashboard	/epd/clients placeholder met roadmap	⏳	E3.S4	2
E4.S2	App layout	Header + sidebar + main content area	⏳	E4.S1	3
E4.S3	Client list page	CRUD operations, table view, filters	⏳	E4.S2	5
E4.S4	Client detail page	Tabs: Intake, Profile, Plan (placeholders)	⏳	E4.S3	3
E4.S5	Navigation & routing	App routes, breadcrumbs, logout flow	⏳	E4.S2	2

Technical Notes:

• Layout: Separate van marketing (app header vs MinimalNav)
• Client CRUD: Forms met validation (Zod)
• Routing: /epd/clients namespace
• Mobile: Responsive table → card layout

---

Epic 5 — Intake & AI Integration

Epic Doel: TipTap editor + Claude API voor intake samenvatting en B1 readability.

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	Story Points
E5.S1	TipTap editor setup	Rich text editor in client detail	⏳	E4.S4	4
E5.S2	Claude API endpoints	/api/ai/summarize, /api/ai/simplify	⏳	E0.S5	5
E5.S3	AI-rail component	Right panel voor AI suggestions	⏳	E5.S2	4
E5.S4	Prompt engineering	Nederlands prompts voor samenvatting	⏳	E5.S2	3
E5.S5	AI event logging	Log alle AI calls naar ai_events table	⏳	E5.S2	2
E5.S6	Error handling	Retry logic, user-friendly errors	⏳	E5.S2	2

Technical Notes:

• TipTap: ProseMirror-based editor
• Claude: 3.5 Sonnet voor Nederlands
• Prompts: Templates in /lib/prompts/
• Cost tracking: Log tokens + estimated costs

---

Epic 6 — Profile & Plan

Epic Doel: DSM-light classificatie + SMART behandelplan generatie.

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	Story Points
E6.S1	Profile tab UI	DSM categories + severity selector	⏳	E4.S4	3
E6.S2	AI categorize endpoint	/api/ai/categorize met DSM-light output	⏳	E5.S2	4
E6.S3	Plan tab UI	SMART doelen form + interventies	⏳	E4.S4	3
E6.S4	AI plan generator	/api/ai/plan met 4 secties output	⏳	E6.S2	5

Technical Notes:

• DSM-light: 6 categorieën (stemming, angst, gedrag, etc.)
• Plan structuur: JSONB in database (flexibel)
• AI output: Structured JSON voor consistentie

---

Epic 7 — Onboarding System

Epic Doel: User guidance voor eerste gebruik (tooltips, walkthrough).

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	Story Points
E7.S1	First-time user detection	Check user_metadata.onboarded flag	⏳	E4.S2	1
E7.S2	Tooltip system	React Joyride of custom tooltips	⏳	E7.S1	3
E7.S3	Help documentation	In-app help modal met shortcuts	⏳	E7.S2	2
E7.S4	Skip onboarding	Option om walkthrough te skippen	⏳	E7.S2	1

Technical Notes:

• Tooltips: Highlight key features (AI buttons, etc.)
• Help: Keyboard shortcuts, feature overview
• Optional: Skip voor returning users

---

Epic 8 — Performance & Launch

Epic Doel: Optimization, testing, demo preparation.

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	Story Points
E8.S1	Performance optimization	Lighthouse > 90, LCP < 2.5s	⏳	E7.S4	3
E8.S2	Accessibility audit	WCAG AA compliance, keyboard nav	⏳	E8.S1	2
E8.S3	Demo dry-run	10-min demo scenario werkt	⏳	E8.S2	2
E8.S4	Production deployment	Live op Vercel, monitoring setup	⏳	E8.S3	2

Technical Notes:

• Performance: Image optimization, code splitting
• Accessibility: Focus states, ARIA labels
• Demo: Pre-seeded data, backup plan
• Monitoring: Vercel Analytics + error tracking

---

5. Kwaliteit & Testplan

🎯 Doel: Vastleggen hoe de kwaliteit van het project wordt geborgd.

Test Types

Test Type	Scope	Tools	Verantwoordelijke
Unit Tests	Business logic, utilities	Vitest	Developer
Integration Tests	API endpoints, database	Playwright	Developer
Smoke Tests	Kritieke user flows	Manual checklist	Developer
Performance Tests	Load times, API response	Lighthouse	Developer
Accessibility Tests	WCAG AA compliance	axe DevTools	Developer

Test Coverage Targets

• Unit tests: 80%+ coverage op /lib folder
• Integration tests: Alle API endpoints
• Smoke tests: 5 happy flows + 3 error scenarios

Manual Test Checklist (voor demo)

Marketing Site:

• Homepage laadt met hero + statement + timeline
• Timeline scrollt en toont features per week
• Login pagina toont features showcase + form
• Navigation werkt (Home, Contact, Login)
• Mobile responsive (timeline, login layout)

EPD App:

• User kan inloggen (magic link + demo credentials)
• Coming Soon dashboard toont roadmap
• Client CRUD werkt (Week 2)
• Intake editor werkt met TipTap (Week 3)
• AI samenvatting genereert binnen 5 sec (Week 3)
• Profile + Plan tabs werken (Week 3)
• Navigatie werkt zonder errors
• Mobile view is responsive
• Error states tonen user-friendly messages

Design System:

• Teal colors consistent overal
• Amber AI buttons duidelijk
• Contrast ratios WCAG AA compliant
• Focus states zichtbaar

---

6. Demo & Presentatieplan

🎯 Doel: Beschrijven hoe de demo wordt gepresenteerd.

Demo Scenario

Duur: 10 minuten
Doelgroep: GGZ innovatiemanagers + bestuurders
Locatie: Live op Vercel (backup: localhost)

Flow:

1. Intro (1 min): Homepage - Statement + Timeline overview
2. Features showcase (2 min): Timeline scrollen, features per week zien
3. Login (1 min): Login pagina met features showcase
4. EPD demo (4 min):
   • Client lijst
   • Nieuwe intake maken
   • AI samenvatting genereren
   • Profile + Plan tabs
5. Afsluiting (2 min): Vragen + LinkedIn build-in-public link

Backup Plan:

• Lokale versie klaar bij internet issues
• Pre-seeded data als AI API niet reageert
• Screenshots als complete fallback

---

7. Risico's & Mitigatie

🎯 Doel: Risico's vroeg signaleren en voorzien van oplossingen.

Risico	Kans	Impact	Mitigatie	Owner
Teal design niet goed ontvangen	Laag	Middel	Rollback plan (1 uur), hybrid approach mogelijk	Developer
Timeline component complex	Middel	Middel	Aceternity UI pattern gebruiken, simplify indien nodig	Developer
Features data structuur te complex	Middel	Laag	Start simpel, iteratief uitbreiden	Developer
AI-output inconsistent	Hoog	Hoog	Snapshot tests, prompt versioning, fallback responses	Developer
API rate limits tijdens demo	Middel	Hoog	Caching, pre-warmed responses, backup data	Developer
Tijdsdruk deadline	Hoog	Middel	Prioriteer MVP features, cut scope indien nodig	Developer
Login pagina layout niet responsive	Laag	Middel	Test op mobile early, stack layout fallback	Developer

---

8. Evaluatie & Lessons Learned

🎯 Doel: Reflecteren op het proces en verbeteringen vastleggen.

Te documenteren na project:

• Wat ging goed? Wat niet?
• Was teal-first design de juiste keuze?
• Werkt vereenvoudigde user journey beter?
• Welke AI-tools waren het meest effectief?
• Welke prompts werkten het beste?
• Waar liepen we vertraging op?
• Wat doen we volgende keer anders?
• Herbruikbare componenten voor volgende projecten

---

9. Referenties

🎯 Doel: Koppelen aan de overige Mission Control-documenten.

Mission Control Documents:

• PRD v1.2 — docs/specs/prd-mini-ecd-v2.md - Product Requirements & Business Case
• FO v2.1 — docs/specs/fo-marketing-app-flow-v2.md - Functioneel Ontwerp (vereenvoudigde user journey)
• UX Plan v2.0 — docs/specs/ux-implementation-plan-v2.md - Teal-first design system
• TO v1.2 — docs/specs/to-mini-ecd-v1_2.md - Technische Architectuur & Database Schema
• API Specs — docs/specs/api-acces-mini-ecd.md - Endpoint Documentation

External Resources:

• Repository: GitHub (public voor transparantie)
• Deployment: Vercel (EU region Amsterdam)
• Design: Tailwind CSS + shadcn/ui
• Documentation: /docs folder in repo

---

10. Glossary & Abbreviations

Term	Betekenis
Epic	Grote feature of fase in development (bevat meerdere stories)
Story	Kleine, uitvoerbare taak binnen een epic
Story Points	Schatting van complexiteit (Fibonacci: 1, 2, 3, 5, 8, 13)
MVP	Minimum Viable Product
DRY	Don't Repeat Yourself
KISS	Keep It Simple, Stupid
SOC	Separation of Concerns
YAGNI	You Aren't Gonna Need It
RLS	Row Level Security (Supabase)
WCAG	Web Content Accessibility Guidelines
LCP	Largest Contentful Paint (performance metric)

---

Versiehistorie

Versie	Datum	Auteur	Wijziging
v2.1	17-11-2024	Colin	Nieuw bouwplan op basis van FO v2.1 (vereenvoudigde user journey) en UX Plan v2.0 (teal-first design). Verwijderd: EPD demo pagina. Nieuw: Timeline met features, login met features showcase.
v1.6	15-11-2024	Colin	Eerdere versie met separate EPD demo pagina

---

Status: Ready for Week 1 Implementation
Next Action: Begin Epic 1 (Marketing Website Refactor)
Owner: Colin Lit
Timeline: Week 1-4 (4 weken sprint)