triqura-ecd/docs/specs/ai-integratie/bouwplan-ai-docs-assistent-v1.md

Mission Control — Bouwplan AI Documentatie Assistent

Projectnaam: Mini-ECD – AI Documentatie Assistent Versie: v1.0 Datum: 01-12-2025 Auteur: Colin van der Heijden

---

1. Doel en context

Doel: Een floating chat widget bouwen die eindgebruikers van het EPD helpt door vragen te beantwoorden op basis van de systeemdocumentatie.

Context: Dit is de eerste AI-integratie in het Mini-ECD prototype. Het dient als fundament voor toekomstige AI features (zoals AI Pre-fill Behandelplan). De widget maakt documentatie direct toegankelijk via een conversatie-interface.

Relatie met andere documenten:

• PRD: prd-ai-docs-assistent-v1.md — Wat en waarom
• FO: fo-ai-docs-assistent-v1.md — Hoe het werkt voor gebruikers

---

2. Uitgangspunten

2.1 Technische Stack

Laag	Technologie
Frontend	Next.js 14.2 + React + Tailwind CSS
Backend	Next.js API Routes (App Router)
Database	Supabase PostgreSQL (alleen voor auth check)
AI	Claude API (claude-sonnet-4-20250514) met streaming
Hosting	Vercel
Icons	Lucide React (Sparkles, X, Send)

2.2 Projectkaders

Aspect	Waarde
Bouwtijd	1-2 dagen
Team	1 developer
Data	Alleen bestaande MDX documentatie
Scope	MVP — chat widget met streaming responses
Persistentie	Sessie-only (geen database opslag)

2.3 Programmeer Uitgangspunten

Code Quality Principles:

• DRY — Herbruikbare hook voor chat state, centrale prompt configuratie
• KISS — Eenvoudige fetch naar Claude API, geen SDK overhead
• SOC — UI componenten gescheiden van API logic en knowledge base
• YAGNI — Geen RAG, geen database opslag, geen multi-provider support

Security:

• API key alleen server-side (Next.js API route)
• Widget alleen voor ingelogde gebruikers
• Geen logging van conversaties

---

3. Epics & Stories Overzicht

Epic ID	Titel	Doel	Status	Stories
E0	Knowledge Base Content	FAQ's en guidelines in markdown	✅ Done	2
E1	Knowledge Services	CategoryDetector, KnowledgeLoader, PromptBuilder	✅ Done	3
E2	API Endpoint	Streaming Claude integratie	✅ Done	1
E3	Chat UI Components	Widget, messages, input	✅ Done	4
E4	Integratie & Testing	Widget in EPD, testen	⏳ To Do	2

Totaal: 12 stories, ~18 story points

---

4. Epics & Stories (Uitwerking)

Epic 0 — Knowledge Base Content

Epic Doel: Gestructureerde FAQ's en guidelines in markdown bestanden.

Story ID	Beschrijving	Acceptatiecriteria	Status	SP
E0.S1	FAQ markdown bestanden	6 FAQ bestanden met Q&A per categorie	✅	2
E0.S2	Guidelines bestanden	2 guideline bestanden (interface, technisch)	✅	1

Deliverables:

lib/docs/knowledge/
├── faq_clientbeheer.md      # Cliënt aanmaken, zoeken, verwijderen
├── faq_intake.md            # Intake starten, notities, spraak
├── faq_screening.md         # Screening resultaten, vragenlijsten
├── faq_behandelplan.md      # Plan maken, doelen, interventies
├── faq_spraak.md            # Microfoon, dicteren, transcriptie
├── faq_inloggen.md          # Login, wachtwoord, rechten
├── guidelines_interface.md   # UI uitleg, navigatie, menu's
└── guidelines_technisch.md   # FHIR API, data model (devs)

---

Epic 1 — Knowledge Services

Epic Doel: Intelligente services voor dynamische knowledge loading.

Story ID	Beschrijving	Acceptatiecriteria	Status	SP
E1.S1	CategoryDetector	Keyword matching om relevante categorieën te bepalen	✅	2
E1.S2	KnowledgeLoader	Laadt alleen relevante markdown bestanden	✅	2
E1.S3	PromptBuilder	Combineert base prompt + relevante knowledge	✅	2

Deliverables:

lib/docs/
├── category-detector.ts    # Analyseert vraag → categorieën
├── knowledge-loader.ts     # Laadt relevante knowledge
└── prompt-builder.ts       # Bouwt geoptimaliseerde prompt

Category Mapping:

const CATEGORY_KEYWORDS: Record<Category, string[]> = {
  clientbeheer: ['cliënt', 'patient', 'aanmaken', 'zoeken', 'dossier'],
  intake: ['intake', 'gesprek', 'notitie', 'verslag'],
  screening: ['screening', 'vragenlijst', 'score', 'resultaat'],
  behandelplan: ['behandelplan', 'doel', 'interventie', 'plan'],
  spraak: ['spraak', 'microfoon', 'dicteren', 'stem', 'transcriptie'],
  inloggen: ['inloggen', 'wachtwoord', 'login', 'account'],
  interface: ['menu', 'knop', 'scherm', 'navigatie', 'waar vind'],
  technisch: ['api', 'fhir', 'endpoint', 'database', 'developer']
};

Flow:

Vraag: "Hoe maak ik een intake aan?"
         ↓
CategoryDetector → ['intake']
         ↓
KnowledgeLoader → laadt faq_intake.md
         ↓
PromptBuilder → base prompt + intake FAQ
         ↓
Claude API → streaming response

---

Epic 2 — API Endpoint

Epic Doel: Streaming API endpoint met dynamische knowledge.

Story ID	Beschrijving	Acceptatiecriteria	Status	SP
E2.S1	Streaming endpoint	POST /api/docs/chat met dynamic knowledge, SSE stream	✅	3

Deliverables:

app/api/docs/chat/
  route.ts               # Streaming API endpoint

API Contract:

// Request
POST /api/docs/chat
{
  messages: Array<{ role: 'user' | 'assistant', content: string }>,
  userMessage: string
}

// Response: Server-Sent Events stream
event: content_block_delta
data: {"delta":{"text":"..."}}

---

Epic 3 — Chat UI Components

Epic Doel: Complete chat widget UI volgens FO specificaties.

Story ID	Beschrijving	Acceptatiecriteria	Status	SP
E3.S1	Chat state hook	use-docs-chat.ts met messages, loading, sendMessage, streaming	✅	2
E3.S2	Message list component	chat-messages.tsx met styling, auto-scroll, streaming cursor	✅	1
E3.S3	Input component	chat-input.tsx met textarea, send, Enter/Shift+Enter	✅	1
E3.S4	Widget container	docs-chat-widget.tsx met trigger, panel, header, animaties	✅	2

Deliverables:

components/docs-chat/
  use-docs-chat.ts       # Custom hook
  chat-messages.tsx      # Message list
  chat-input.tsx         # Input area
  docs-chat-widget.tsx   # Main container

UI Specs (uit FO):

Element	Specificatie
Trigger button	56x56px, amber gradient, Sparkles icon, fixed bottom-6 right-6
Panel	384px breed, max 80vh, slide-in animatie
User messages	Rechts, bg-amber-100, rounded
Assistant messages	Links, bg-slate-100, rounded
Streaming	Pulserende cursor ▊

---

Epic 4 — Integratie & Testing

Epic Doel: Widget geïntegreerd in EPD en getest.

Story ID	Beschrijving	Acceptatiecriteria	Status	SP
E4.S1	Widget integratie	DocsChatWidget in EPD layout, alleen ingelogde users	⏳	1
E4.S2	Smoke tests	Happy flow, error states, category detection werkt	⏳	1

Te wijzigen bestand:

app/epd/components/epd-layout-client.tsx

---

5. Kwaliteit & Testplan

Test Types

Test Type	Scope	Methode
Unit	Knowledge base loader	Console test
Integration	API endpoint	curl/Postman
Smoke	Volledige flow	Manual in browser

Manual Test Checklist

• Widget trigger button zichtbaar in EPD
• Klik opent chat panel met animatie
• Welkomstbericht wordt getoond
• Vraag versturen werkt (Enter + button)
• Streaming response verschijnt woord-voor-woord
• Vervolgvraag behoudt context
• X-knop sluit panel
• Conversatie blijft behouden na sluiten/openen
• Error state toont bij API failure
• Widget verdwijnt bij uitloggen

Acceptatiecriteria (uit PRD)

Criterium	Target
First token	< 2 seconden
Volledige response	< 30 seconden
Error rate	< 5%

---

6. Demo & Presentatieplan

Duur: 3 minuten Scenario:

1. Intro (30s): "Dit is de documentatie assistent"
2. Vraag 1 (45s): "Hoe maak ik een intake aan?" → streaming antwoord
3. Vraag 2 (45s): "En hoe gebruik ik spraakherkenning?" → context behouden
4. Edge case (30s): "Wat is de beste behandeling?" → "weet ik niet" response
5. Afsluiting (30s): Widget sluiten, conversatie behouden

---

7. Risico's & Mitigatie

Risico	Kans	Impact	Mitigatie
AI hallucineert	Middel	Hoog	Strikte system prompt, FAQ's eerst, "alleen uit docs" regel
Trage response	Laag	Middel	Streaming UX, timeout na 30s
Context te groot	Laag	Middel	~119KB past in context window, monitoring
API rate limits	Laag	Middel	Sessie-based (geen caching nodig)

---

8. Referenties

Mission Control Documents

• PRD: prd-ai-docs-assistent-v1.md
• FO: fo-ai-docs-assistent-v1.md
• Gerelateerd: prd-ai-prefill-behandelplan-v1.md

Bestaande Code Patterns

Bestand	Pattern
app/api/reports/classify/route.ts	Claude API fetch pattern
lib/mdx/documentatie.ts	MDX loading met gray-matter
components/ui/ai-button.tsx	Amber AI styling

Externe Referenties

• Claude API Docs
• Anthropic Streaming

---

9. Glossary

Term	Betekenis
SSE	Server-Sent Events (streaming protocol)
Knowledge Base	Verzameling documentatie voor AI context
FAQ	Frequently Asked Questions
Streaming	Real-time response, woord-voor-woord

---

Versiehistorie:

Versie	Datum	Auteur	Wijziging
v1.0	01-12-2025	Colin van der Heijden	Initiële versie