Files

colinislit af88ac9446 docs: add architecture and intake intent documentation

- Add architecture overview, implementation plan, and intent overview
- Add intake intent process specs (gap analyse, bouwplan, testplan)
- Add swift architecture specs and visualization prompts
- Remove obsolete aispeedrun-manifesto template

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-02-04 19:26:14 +01:00

20 KiB

Raw Blame History

Intent Overzicht — Cortex

Versie: v1.0 Datum: 4 februari 2026 Doelgroep: Product owners, IT consultants, data scientists

1. Wat is een Intent?

Een intent is de gedetecteerde bedoeling achter een gebruikerscommando. Wanneer een zorgmedewerker zegt "zoek jan", herkent Cortex de intent zoeken met de entity patientName: "jan".

Voorbeeld flow:

Gebruikersinvoer    →    Intent           →    Actie
────────────────────────────────────────────────────────
"notitie jan"       →    dagnotitie       →    Open notitie-formulier
"wat zijn risico's" →    risico_query     →    Toon risico-overzicht
"agenda vandaag"    →    agenda_query     →    Toon afspraken

2. Alle Intents in Kaart

2.1 Basis Intents (Productie)

Intent	Trigger voorbeelden	Wat het doet	Block
`dagnotitie`	"notitie jan", "medicatie gegeven"	Verpleegkundige notitie maken	DagnotitieBlock
`zoeken`	"zoek marie", "wie is jan"	Patiënt opzoeken	ZoekenBlock
`overdracht`	"overdracht", "einde dienst"	Shift-overdracht bekijken	OverdrachtBlock

2.2 Agenda Intents (Productie)

Intent	Trigger voorbeelden	Wat het doet	Block
`agenda_query`	"agenda", "afspraken vandaag"	Afspraken bekijken	AgendaBlock
`create_appointment`	"plan afspraak jan morgen"	Nieuwe afspraak maken	CreateAppointmentBlock
`cancel_appointment`	"annuleer afspraak jan"	Afspraak annuleren	CancelAppointmentBlock
`reschedule_appointment`	"verzet 14:00 naar 15:00"	Afspraak verzetten	RescheduleAppointmentBlock

2.3 Intake Intents (MVP)

Intent	Trigger voorbeelden	Wat het doet	Block
`intake_status`	"wat moet ik nog doen?", "intake checklist"	Intake voortgang tonen	IntakeStatusBlock
`risico_query`	"wat zijn de risico's?", "risicotaxatie"	Risico's weergeven	RisicoBlock
`diagnose_query`	"welke diagnoses?", "toon diagnose"	Diagnoses weergeven	DiagnoseBlock
`intake_navigeer`	"ga naar risico", "open anamnese"	Naar intake-sectie navigeren	(geen block, directe navigatie)

2.4 Speciale Intents

Intent	Wanneer	Wat het doet
`unknown`	Niet herkend	Toon fallback-keuzemenu

3. Anatomie van een Intent

Elke intent heeft meerdere "aanraakpunten" in de codebase:

┌─────────────────────────────────────────────────────────────────────┐
│                        INTENT LEVENSCYCLUS                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  1. TYPES             lib/cortex/types.ts                           │
│     └── Intent naam in CortexIntent type                            │
│     └── Block config in BLOCK_CONFIGS                               │
│     └── Entities in ExtractedEntities                               │
│                                                                     │
│  2. HERKENNING        lib/cortex/reflex-classifier.ts               │
│     └── Regex patterns voor lokale classificatie                    │
│                                                                     │
│  3. AI PROMPT         app/api/cortex/chat/route.ts                  │
│     └── Intent beschrijving in system prompt                        │
│     └── Voorbeelden met JSON output                                 │
│                                                                     │
│  4. VALIDATIE         lib/cortex/action-parser.ts                   │
│     └── Zod schema voor intent validatie                            │
│     └── Artifact type mapping                                       │
│                                                                     │
│  5. ROUTING           lib/cortex/action-parser.ts                   │
│     └── routeIntentToArtifact() switch case                         │
│                                                                     │
│  6. UI BLOCK          components/cortex/blocks/[intent]-block.tsx   │
│     └── React component voor weergave                               │
│                                                                     │
│  7. RENDERING         components/cortex/artifacts/artifact-        │
│                       container.tsx                                 │
│     └── Import statement                                            │
│     └── Switch case in renderArtifactBlock()                        │
│     └── Titel in getArtifactTitle()                                 │
│                                                                     │
│  8. API (optioneel)   app/api/cortex/[domain]/route.ts              │
│     └── Endpoint voor data ophalen                                  │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

4. Bestandsoverzicht per Intent

4.1 `dagnotitie`

Aspect	Bestand	Regel/Sectie
Type definitie	`lib/cortex/types.ts`	`CortexIntent` type
Block config	`lib/cortex/types.ts`	`BLOCK_CONFIGS.dagnotitie`
Patterns	`lib/cortex/reflex-classifier.ts`	`INTENT_PATTERNS.dagnotitie`
AI prompt	`app/api/cortex/chat/route.ts`	System prompt sectie
Validatie	`lib/cortex/action-parser.ts`	`ActionSchema`
Routing	`lib/cortex/action-parser.ts`	`routeIntentToArtifact()` case
UI Block	`components/cortex/blocks/dagnotitie-block.tsx`	Hele bestand
Rendering	`components/cortex/artifacts/artifact-container.tsx`	Import + switch
API	`app/api/reports/route.ts`	POST voor opslaan

Entities:

{
  patientName?: string;    // "jan"
  patientId?: string;      // UUID
  category?: 'medicatie' | 'adl' | 'gedrag' | 'incident' | 'observatie';
  content?: string;        // "medicatie gegeven"
}

4.2 `zoeken`

Aspect	Bestand
Type definitie	`lib/cortex/types.ts`
Block config	`lib/cortex/types.ts`
Patterns	`lib/cortex/reflex-classifier.ts`
UI Block	`components/cortex/blocks/zoeken-block.tsx`
API	`app/api/cortex/patients/search/route.ts`

Entities:

{
  query?: string;          // Zoekterm
  patientName?: string;    // Directe naam
}

4.3 `overdracht`

Aspect	Bestand
Type definitie	`lib/cortex/types.ts`
Block config	`lib/cortex/types.ts`
Patterns	`lib/cortex/reflex-classifier.ts`
UI Block	`components/cortex/blocks/overdracht-block.tsx`
API	`app/api/overdracht/route.ts`

Entities:

{
  // Geen specifieke entities
}

4.4 `agenda_query`

Aspect	Bestand
Type definitie	`lib/cortex/types.ts`
Block config	`lib/cortex/types.ts`
Patterns	`lib/cortex/reflex-classifier.ts`
UI Block	`components/cortex/blocks/agenda-block.tsx`
API	`app/api/cortex/agenda/route.ts`

Entities:

{
  dateRange?: {
    start: Date;
    end: Date;
    label: 'vandaag' | 'morgen' | 'deze week' | 'volgende week' | 'custom';
  };
}

4.5 `create_appointment`

Aspect	Bestand
Type definitie	`lib/cortex/types.ts`
Block config	`lib/cortex/types.ts`
Patterns	`lib/cortex/reflex-classifier.ts`
UI Block	`components/cortex/blocks/agenda-block.tsx` (create mode)
API	`app/api/cortex/agenda/create/route.ts`

Entities:

{
  patientName?: string;
  patientId?: string;
  datetime?: {
    date: Date;
    time: string;  // "HH:mm"
  };
  appointmentType?: 'intake' | 'behandeling' | 'follow-up' | 'telefonisch' | 'huisbezoek' | 'online' | 'crisis' | 'overig';
  location?: 'praktijk' | 'online' | 'thuis';
}

4.6 `intake_status` (MVP)

Aspect	Bestand
Type definitie	`lib/cortex/types.ts`
Block config	`lib/cortex/types.ts`
Patterns	`lib/cortex/reflex-classifier.ts`
UI Block	`components/cortex/blocks/intake-status-block.tsx`
API	`app/api/cortex/intake/status/route.ts`

Entities:

{
  patientId?: string;
  intakeId?: string;
}

Trigger patterns:

"wat moet ik nog doen?"
"is de intake compleet?"
"intake checklist"
"intake status"

4.7 `risico_query` (MVP)

Aspect	Bestand
Type definitie	`lib/cortex/types.ts`
Block config	`lib/cortex/types.ts`
Patterns	`lib/cortex/reflex-classifier.ts`
UI Block	`components/cortex/blocks/risico-block.tsx`
API	`app/api/cortex/intake/risico/route.ts`

Entities:

{
  patientId?: string;
  intakeId?: string;
}

Trigger patterns:

"wat zijn de risico's?"
"risicotaxatie"
"toon risico's"

4.8 `diagnose_query` (MVP)

Aspect	Bestand
Type definitie	`lib/cortex/types.ts`
Block config	`lib/cortex/types.ts`
Patterns	`lib/cortex/reflex-classifier.ts`
UI Block	`components/cortex/blocks/diagnose-block.tsx`
API	`app/api/cortex/intake/diagnose/route.ts`

Entities:

{
  patientId?: string;
  intakeId?: string;
}

Trigger patterns:

"welke diagnoses?"
"toon diagnose"
"wat is de diagnose?"

4.9 `intake_navigeer` (MVP)

Aspect	Bestand
Type definitie	`lib/cortex/types.ts`
Patterns	`lib/cortex/reflex-classifier.ts`
Handler	`components/cortex/command-center/command-center.tsx`

Let op: Deze intent heeft geen block — het navigeert direct naar een EPD-pagina.

Entities:

{
  navigationTarget?: 'contacts' | 'kindcheck' | 'risk' | 'anamnese' |
                     'examination' | 'rom' | 'diagnosis' | 'behandeladvies';
}

Trigger patterns:

"ga naar risico"
"open diagnose"
"naar anamnese"

5. Data Flow Diagram

5.1 Van Invoer naar Actie

┌──────────────┐
│  GEBRUIKER   │
│  spreekt/    │
│  typt        │
└──────┬───────┘
       │ "notitie jan medicatie"
       ▼
┌──────────────────────────────────────────────────────────────┐
│ LAAG 1: REFLEX ARC                                           │
│ lib/cortex/reflex-classifier.ts                              │
│                                                              │
│ • Pattern matching: /^notitie\s+\w+/i                        │
│ • Confidence: 0.95                                           │
│ • Escalatie check: geen multi-intent, geen context nodig     │
│                                                              │
│ Output: { intent: "dagnotitie", confidence: 0.95 }           │
└──────────────────────────┬───────────────────────────────────┘
                           │
          ┌────────────────┴────────────────┐
          │ Confidence >= 0.7?              │
          └────────────────┬────────────────┘
                           │ Ja
                           ▼
┌──────────────────────────────────────────────────────────────┐
│ ROUTING                                                      │
│ lib/cortex/action-parser.ts → routeIntentToArtifact()        │
│                                                              │
│ Input:  intent="dagnotitie", entities={patientName:"jan"}    │
│ Output: { type: "dagnotitie", prefill: {...}, title: "..." } │
└──────────────────────────┬───────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────┐
│ UI RENDERING                                                 │
│ components/cortex/artifacts/artifact-container.tsx           │
│                                                              │
│ • Switch op artifact.type                                    │
│ • Rendert <DagnotitieBlock prefill={...} />                  │
└──────────────────────────┬───────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────┐
│ BLOCK                                                        │
│ components/cortex/blocks/dagnotitie-block.tsx                │
│                                                              │
│ • Toont formulier met prefilled data                         │
│ • Gebruiker vult aan en klikt "Opslaan"                      │
│ • POST naar /api/reports                                     │
└──────────────────────────────────────────────────────────────┘

5.2 Escalatie naar AI (Laag 2)

Wanneer escaleert de Reflex Arc naar de AI Orchestrator?

Trigger	Voorbeeld	Reden
Lage confidence	"blah blah"	Geen pattern match
Ambiguïteit	"jan"	Kan zoeken of notitie zijn
Multi-intent	"zeg jan af en maak notitie"	Twee acties in één zin
Context nodig	"maak notitie voor hem"	Wie is "hem"?
Relatieve tijd	"morgen om 14:00"	Datum moet berekend worden

┌──────────────────────────────────────────────────────────────┐
│ LAAG 2: ORCHESTRATOR (bij escalatie)                         │
│ app/api/cortex/chat/route.ts                                 │
│                                                              │
│ • Stuurt context + input naar Claude AI                      │
│ • AI retourneert IntentChain met 1+ actions                  │
│ • Kan clarification vragen ("Met welke patiënt?")            │
└──────────────────────────────────────────────────────────────┘

6. Entity Extractie

6.1 Hoe worden entities geëxtraheerd?

Lokaal (Reflex Arc):

Eenvoudige regex voor bekende patronen
Voorbeeld: /^notitie\s+(\w+)/ → extraheert patiëntnaam

AI (Orchestrator):

Claude analyseert volledige zin
Extraheert alle relevante entities
Kan context gebruiken (actieve patiënt, agenda)

6.2 Entity Types

Entity	Type	Voorbeeld	Gebruikt door
`patientName`	string	"jan de vries"	Alle intents
`patientId`	UUID	"abc-123..."	Alle intents
`category`	enum	"medicatie"	dagnotitie
`content`	string	"medicatie gegeven"	dagnotitie
`query`	string	"jan"	zoeken
`dateRange`	object	{ start, end, label }	agenda_query
`datetime`	object	{ date, time }	create_appointment
`appointmentType`	enum	"intake"	create_appointment
`location`	enum	"praktijk"	create_appointment
`navigationTarget`	enum	"risk"	intake_navigeer

7. Block Types

7.1 Block Categorieën

Type	Doel	Voorbeeld
Query Block	Data tonen (read-only)	RisicoBlock, DiagnoseBlock
Action Block	Data invoeren/wijzigen	DagnotitieBlock
Status Block	Voortgang/checklist tonen	IntakeStatusBlock
Navigation Block	Direct navigeren	(intake_navigeer)

7.2 Block Structuur

Alle blocks volgen hetzelfde patroon:

┌─────────────────────────────────────────────────────┐
│ [Icon] Titel                              [Sluiten] │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Loading state   →   Error state   →   Data state   │
│  (spinner)           (foutmelding)     (content)    │
│                                                     │
│  ───────────────────────────────────────────────    │
│  [Secundaire actie]          [Primaire actie]       │
└─────────────────────────────────────────────────────┘

8. Confidence & Escalatie

8.1 Drempelwaarden

Waarde	Betekenis	Actie
`>= 0.9`	Zeer zeker	Direct uitvoeren
`0.7 - 0.9`	Redelijk zeker	Uitvoeren met bevestiging
`< 0.7`	Onzeker	Escaleer naar AI of vraag verduidelijking

8.2 Escalatie Redenen

type EscalationReason =
  | 'low_confidence'        // Confidence < 0.7
  | 'ambiguous'             // Top-2 intents liggen dicht bij elkaar
  | 'multi_intent_detected' // Meerdere acties gedetecteerd
  | 'needs_context'         // Voornaamwoorden zoals "hij", "haar"
  | 'relative_time';        // "morgen", "volgende week"

9. Gerelateerde Documentatie

Document	Locatie	Inhoud
Block Template Pattern	`docs/intent/intake-intent-proces/block-template-pattern.md`	Technisch patroon voor blocks
Session Log	`docs/intent/intake-intent-proces/session-log-2026-02-03.md`	Bug fixes en lessons learned
Implementatieplan	`docs/architectuur/implementatieplan-nieuwe-intents.md`	Stappenplan nieuwe intents

10. Glossary

Term	Betekenis
Intent	Gedetecteerde bedoeling achter een commando
Entity	Geëxtraheerd gegeven uit de invoer (naam, datum, etc.)
Block	UI component dat een intent visueel afhandelt
Artifact	Container voor blocks in het werkgebied
Confidence	Zekerheidsgraad van classificatie (0-1)
Escalatie	Doorverwijzing naar AI voor complexe invoer
Prefill	Vooringevulde data in een formulier

Voor het toevoegen van nieuwe intents, zie: implementatieplan-nieuwe-intents.md

20 KiB Raw Blame History

Intent Overzicht — Cortex

1. Wat is een Intent?

2. Alle Intents in Kaart

2.1 Basis Intents (Productie)

2.2 Agenda Intents (Productie)

2.3 Intake Intents (MVP)

2.4 Speciale Intents

3. Anatomie van een Intent

4. Bestandsoverzicht per Intent

4.1 dagnotitie

4.2 zoeken

4.3 overdracht

4.4 agenda_query

4.5 create_appointment

4.6 intake_status (MVP)

4.7 risico_query (MVP)

4.8 diagnose_query (MVP)

4.9 intake_navigeer (MVP)

5. Data Flow Diagram

5.1 Van Invoer naar Actie

5.2 Escalatie naar AI (Laag 2)

6. Entity Extractie

6.1 Hoe worden entities geëxtraheerd?

6.2 Entity Types

7. Block Types

7.1 Block Categorieën

7.2 Block Structuur

8. Confidence & Escalatie

8.1 Drempelwaarden

8.2 Escalatie Redenen

9. Gerelateerde Documentatie

10. Glossary

20 KiB

Raw Blame History

4.1 `dagnotitie`

4.2 `zoeken`

4.3 `overdracht`

4.4 `agenda_query`

4.5 `create_appointment`

4.6 `intake_status` (MVP)

4.7 `risico_query` (MVP)

4.8 `diagnose_query` (MVP)

4.9 `intake_navigeer` (MVP)