triqura-ecd/docs/architectuur/intent-overzicht.md

# 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:**
```typescript
{
  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:**
```typescript
{
  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:**
```typescript
{
  // 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:**
```typescript
{
  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:**
```typescript
{
  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:**
```typescript
{
  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:**
```typescript
{
  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:**
```typescript
{
  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:**
```typescript
{
  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

```typescript
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`*