# Use Cases × Technische Componenten — Validatiematrix

> **Type**: Architectuur Validatiedocument
> **Versie**: 1.0
> **Datum**: 2026-02-14
> **Doel**: Valideer of de enterprise architectuur alle use cases ondersteunt. Identificeer gaten.
> **Relatie**: Valideert `enterprise-epd-architectuur.md` en `intent-system-architectuur-nl.md`

---

## 1. Use Case Catalogus

Alle use cases uit de huidige codebase, uitgebreid met enterprise-scenario's die nog ontbreken.

### 1.1 Bestaande use cases (geïmplementeerd in prototype)

| ID | Use Case | Categorie | Intent | Status |
|----|----------|-----------|--------|--------|
| UC-01 | Dagnotitie aanmaken via spraak/tekst | Rapportage | `dagnotitie` | ✅ Volledig |
| UC-02 | Rapportage tijdlijn bekijken (per shift) | Rapportage | — (UI) | ✅ Volledig |
| UC-03 | Notitie markeren voor overdracht | Rapportage | — (UI) | ✅ Volledig |
| UC-04 | Overdracht overzicht bekijken | Overdracht | `overdracht` | ✅ Volledig |
| UC-05 | AI-samenvatting genereren voor overdracht | Overdracht | `overdracht` | ✅ Volledig |
| UC-06 | Bronverwijzing volgen vanuit AI-samenvatting | Overdracht | — (UI) | ✅ Volledig |
| UC-07 | Patiënt zoeken op naam/BSN | Zoeken | `zoeken` | ✅ Volledig |
| UC-08 | Patiëntdossier openen | Navigatie | — (UI) | ✅ Volledig |
| UC-09 | Agenda bekijken (vandaag/week) | Agenda | `agenda_query` | ✅ Volledig |
| UC-10 | Afspraak aanmaken | Agenda | `create_appointment` | ✅ Volledig |
| UC-11 | Afspraak annuleren | Agenda | `cancel_appointment` | ✅ Volledig |
| UC-12 | Afspraak verzetten | Agenda | `reschedule_appointment` | ✅ Volledig |
| UC-13 | Intake status bekijken | Intake | `intake_status` | ⚠️ MVP |
| UC-14 | Risicotaxatie bekijken | Intake | `risico_query` | ⚠️ MVP |
| UC-15 | Diagnoses bekijken | Intake | `diagnose_query` | ⚠️ MVP |
| UC-16 | Navigeren naar intake-sectie | Intake | `intake_navigeer` | ⚠️ MVP |
| UC-17 | Spraak-naar-tekst voor invoer | Invoer | — (Deepgram) | ✅ Volledig |
| UC-18 | Samengestelde opdracht (multi-intent) | Classificatie | Meerdere | ✅ Volledig |
| UC-19 | Context-afhankelijke verwijzingen ("hem", "haar") | Classificatie | — (Orchestrator) | ✅ Volledig |
| UC-20 | Nudge na actie (vervolgactie suggestie) | Protocol | — (Nudge) | ⚠️ Code bestaat, niet aangeroepen |

### 1.2 Ontbrekende enterprise use cases

| ID | Use Case | Categorie | Waarom nodig |
|----|----------|-----------|-------------|
| UC-21 | Behandelplan opstellen en bijwerken | Behandeling | Kernfunctie GGZ-EPD |
| UC-22 | Medicatieoverzicht bekijken/bijwerken | Medicatie | Wettelijk verplicht, hoog-risico |
| UC-23 | Incident/MIC-melding registreren | Veiligheid | Wkkgz verplichting |
| UC-24 | Wvggz-dwangmaatregel registreren | Juridisch | Wvggz verplichting |
| UC-25 | Toestemming registreren/intrekken | Juridisch | AVG + Wvggz |
| UC-26 | Audit log doorzoeken (compliance officer) | Audit | NEN 7513 verplichting |
| UC-27 | Patiëntdata exporteren (FHIR Bundle) | Interoperabiliteit | Dataportabiliteit (AVG) |
| UC-28 | Gebruikersbeheer (admin) | Beheer | Multi-tenancy |
| UC-29 | Protocolregel toevoegen/valideren | Knowledge | Protocol Engine beheer |
| UC-30 | Dashboard: team-overzicht per afdeling | Overzicht | Management informatie |
| UC-31 | Rapportage verwijderen (soft delete) + versioning | Rapportage | Wkkgz dossierplicht |
| UC-32 | Groepstherapie sessie rapporteren (meerdere patiënten) | Rapportage | GGZ-specifiek |
| UC-33 | Noodtoegang ("break the glass") | Beveiliging | NEN 7510, noodsituaties |

---

## 2. Technische Componenten Register

Alle componenten die de architectuur beschrijft, met hun verantwoordelijkheid en status.

### 2.1 Component overzicht

```
LAAG 1: INTERFACE
├── C01  Traditionele EPD UI (Next.js pages + forms)
├── C02  Intent Command Center (⌘K overlay)
├── C03  Spraak Input (Deepgram integratie)
└── C04  Block/Artifact systeem (canvas + forms)

LAAG 2: INTENT SYSTEEM
├── C05  Intent Registry (declaratieve definities)
├── C06  Reflex Classifier (lokale regex matching)
├── C07  Orchestrator (LLM classificatie)
├── C08  Entity Extractor + Date Parser
├── C09  Action System (intent → UI artifact mapping)
└── C10  Protocol Engine / Nudge

LAAG 3: KNOWLEDGE LAYER
├── C11  Protocol Rules Store (gevalideerde regels)
├── C12  RAG Pipeline (protocol indexering + vector search)
├── C13  Regelvalidatie UI (admin)
└── C14  Kennisbron Connectors (wet/protocol/kwaliteitsdoc importers)

LAAG 4: DOMEIN / BUSINESS LOGIC
├── C15  Rapportage Service (CRUD, versioning, soft delete)
├── C16  Overdracht Service (samenvatting generatie)
├── C17  Agenda Service (CRUD, conflictdetectie)
├── C18  Behandelplan Service
├── C19  Medicatie Service
├── C20  Intake Service
├── C21  Patiënt Service (CRUD, zoeken, toewijzing)
└── C22  Toestemming Service (Wvggz, AVG)

LAAG 5: ENTERPRISE FUNDAMENT
├── C23  Auth + SSO (Supabase Auth, SAML)
├── C24  Multi-tenancy (RLS, tenant context)
├── C25  RBAC + ABAC Engine (policy evaluatie)
├── C26  Audit Trail (NEN 7513 immutable log)
├── C27  Field Encryption (AES-256-GCM)
├── C28  FHIR Export Service
├── C29  CDS Hooks Service
├── C30  Observability (Pino, OpenTelemetry)
├── C31  Circuit Breaker / Resilience
├── C32  Health Check Service
└── C33  PII Filter (sanitisatie voor AI prompts)

LAAG 6: PLATFORM SERVICES (zie enterprise-componenten-uitbreiding.md)
├── C34  Notificatie Service (in-app + email + escalatie)
├── C35  Workflow Engine (state machine voor klinische workflows)
├── C36  Full-Text Search Service (klinische notities doorzoeken)
├── C37  Caching Layer (AI responses, API responses, sessiedata)
├── C38  Scheduled Jobs Service (BullMQ repeatable jobs)
└── C39  Webhook System (outbound event webhooks)

LAAG 7: EXTERNE INTEGRATIES (zie enterprise-componenten-uitbreiding.md)
├── C40  ZPM Facturatie Service (Zorgprestatiemodel)
├── C41  Vecozo Connector (voorbereiding)
└── C42  Zorgdomein Connector (voorbereiding)

LAAG 8: ANALYTICS (zie enterprise-componenten-uitbreiding.md)
└── C43  BI Module (materialized views, data-export)
```

### 2.2 Component status

| Component | Prototype status | Enterprise gereed? | Werk nodig |
|-----------|-----------------|-------------------|------------|
| C01 EPD UI | Gedeeltelijk (rapportage, overdracht, agenda) | Nee | Uitbreiden: behandelplan, medicatie, admin |
| C02 Command Center | Volledig | Ja (refactor) | Store splitsen, Registry migratie |
| C03 Spraak Input | Volledig | Ja | Minimale wijzigingen |
| C04 Block/Artifact | Volledig | Ja | Uitbreiden met nieuwe block types |
| C05 Intent Registry | 40% (patronen verspreid over code) | Nee | **Kernwijziging**: centraliseren in config/DB |
| C06 Reflex Classifier | 85% werkend | Gedeeltelijk | Patronen naar Registry verplaatsen |
| C07 Orchestrator | 85% werkend | Gedeeltelijk | Prompt extractie, unified pipeline |
| C08 Entity Extractor | 60% werkend | Gedeeltelijk | Pattern tables externaliseren |
| C09 Action System | 70% werkend | Gedeeltelijk | Meer artifact types |
| C10 Protocol Engine | 30% (code niet aangeroepen) | Nee | **Nieuw bouwen** op basis van Knowledge Layer |
| C11 Protocol Rules Store | 0% | Nee | **Volledig nieuw** |
| C12 RAG Pipeline | 0% | Nee | **Volledig nieuw** |
| C13 Regelvalidatie UI | 0% | Nee | **Volledig nieuw** |
| C14 Kennisbron Connectors | 0% | Nee | **Volledig nieuw** |
| C15 Rapportage Service | 80% (CRUD werkt) | Nee | Versioning, multi-tenant |
| C16 Overdracht Service | 90% werkend | Gedeeltelijk | Multi-tenant, audit integratie |
| C17 Agenda Service | 80% werkend | Gedeeltelijk | Conflictdetectie, multi-tenant |
| C18 Behandelplan Service | 0% | Nee | **Volledig nieuw** |
| C19 Medicatie Service | 0% | Nee | **Volledig nieuw** |
| C20 Intake Service | 40% (MVP blocks) | Nee | Uitbreiden, multi-tenant |
| C21 Patiënt Service | 70% | Nee | Toewijzing, multi-tenant |
| C22 Toestemming Service | 0% | Nee | **Volledig nieuw** |
| C23 Auth + SSO | 60% (Supabase Auth) | Nee | SSO/SAML, MFA, session management |
| C24 Multi-tenancy | 0% | Nee | **Volledig nieuw** |
| C25 RBAC + ABAC | 10% (basis RLS) | Nee | **Grotendeels nieuw** |
| C26 Audit Trail | 0% | Nee | **Volledig nieuw** |
| C27 Field Encryption | 0% | Nee | **Volledig nieuw** |
| C28 FHIR Export | 10% (Patient endpoint) | Nee | Uitbreiden naar alle resources |
| C29 CDS Hooks | 0% | Nee | **Volledig nieuw** |
| C30 Observability | 10% (console.log) | Nee | **Grotendeels nieuw** |
| C31 Circuit Breaker | 20% (classifyWithTimeout) | Nee | Generaliseren |
| C32 Health Check | 0% | Nee | **Volledig nieuw** |
| C33 PII Filter | 40% (logger.ts sanitisatie) | Nee | Uitbreiden voor AI prompts |

---

## 3. Validatiematrix — Use Case × Component

Elke cel toont welke componenten een use case nodig heeft. **Rode cellen** zijn gaten.

### 3.1 Rapportage use cases

#### UC-01: Dagnotitie aanmaken via spraak/tekst

```
FLOW:
Zorgverlener spreekt/typt → "Notitie Jan medicatie onrustige nacht"

┌─────────────┐
│ C03 Spraak   │ (optioneel) Audio → tekst
│ of C02 ⌘K   │ Tekst invoer
└──────┬──────┘
       ▼
┌──────────────┐     ┌──────────────┐
│ C05 Registry  │────►│ C06 Reflex    │ Pattern match: "notitie" → dagnotitie
└──────────────┘     └──────┬───────┘
                            │ confidence 0.9
                            ▼
                     ┌──────────────┐
                     │ C08 Entity    │ "Jan" → patient fuzzy match
                     │   Extractor   │ "medicatie" → category
                     └──────┬───────┘
                            ▼
                     ┌──────────────┐
                     │ C09 Action    │ Open dagnotitie-block met prefill
                     │   System      │ { patient: Jan, category: medicatie }
                     └──────┬───────┘
                            ▼
                     ┌──────────────┐
                     │ C04 Block     │ Formulier met vooringevulde data
                     │   (UI)        │ Gebruiker bevestigt + voegt content toe
                     └──────┬───────┘
                            │ [gebruiker klikt "Opslaan"]
                            ▼
                     ┌──────────────┐     ┌──────────────┐
                     │ C25 RBAC      │────►│ C15 Rapportage│ Insert report
                     │   check       │     │   Service     │ shift_date berekend
                     └──────────────┘     └──────┬───────┘
                                                  │
                            ┌─────────────────────┤
                            ▼                     ▼
                     ┌──────────────┐     ┌──────────────┐
                     │ C26 Audit     │     │ C10 Protocol  │ Evalueer nudges
                     │   Trail       │     │   Engine      │ → "Check vitale functies?"
                     └──────────────┘     └──────────────┘

COMPONENTEN NODIG: C02/C03, C05, C06, C08, C09, C04, C25, C15, C26, C10
GATEN:
  🔴 C05 Intent Registry bestaat niet als centraal component
  🔴 C25 RBAC check ontbreekt volledig
  🔴 C26 Audit trail ontbreekt volledig
  🔴 C10 Protocol Engine is niet aangesloten (code bestaat, niet aangeroepen)
  🟡 C15 Rapportage Service mist versioning en multi-tenant
```

#### UC-05: AI-samenvatting genereren voor overdracht

```
FLOW:
Zorgverlener → "Overdracht" of klikt in UI

┌─────────────┐
│ C02 ⌘K      │ of C01 UI → navigatie naar overdracht pagina
└──────┬──────┘
       ▼
┌──────────────┐     ┌──────────────┐
│ C06 Reflex    │────►│ C09 Action    │ Open overdracht-block
└──────────────┘     └──────┬───────┘
                            ▼
                     ┌──────────────┐
                     │ C16 Overdracht│ Haal patiëntenlijst op
                     │   Service     │ Filter op afdeling/dienst
                     └──────┬───────┘
                            │ [voor elke actieve patiënt]
                            ▼
                     ┌──────────────┐
                     │ C33 PII       │ Minimaliseer patiëntdata voor AI
                     │   Filter      │
                     └──────┬───────┘
                            ▼
                     ┌──────────────┐
                     │ C07 Claude    │ Genereer samenvatting
                     │   API         │ Aandachtspunten + actiepunten
                     └──────┬───────┘
                            │
                     ┌──────┴───────┐
                     ▼              ▼
              ┌──────────────┐ ┌──────────────┐
              │ C26 Audit     │ │ C04 Block     │ Render samenvatting
              │   Trail       │ │   (UI)        │ met bronverwijzingen
              └──────────────┘ └──────────────┘

COMPONENTEN NODIG: C01/C02, C06, C09, C16, C33, C07 (Claude), C26, C04
GATEN:
  🔴 C26 Audit trail ontbreekt — wie heeft welke samenvatting gegenereerd?
  🔴 C33 PII filter is onvolledig — welke data gaat naar Claude?
  🟡 C16 Overdracht Service mist tenant-filtering
  🟡 Geen caching — elke keer opnieuw genereren is duur
```

#### UC-31: Rapportage verwijderen + versioning

```
FLOW:
Zorgverlener wil rapport wijzigen of verwijderen

┌─────────────┐
│ C01 UI       │ Klik op "bewerken" of "verwijderen" in tijdlijn
└──────┬──────┘
       ▼
┌──────────────┐
│ C25 RBAC      │ Mag deze gebruiker dit rapport wijzigen?
│   + ABAC      │ Check: auteur OF hoofdbehandelaar OF admin
└──────┬───────┘
       ▼
┌──────────────┐
│ C15 Rapportage│ WIJZIGEN: nieuwe versie aanmaken
│   Service     │   → version++, previous_version_id link
│               │ VERWIJDEREN: soft delete (deleted_at)
│               │   → NOOIT hard delete (Wkkgz)
└──────┬───────┘
       ▼
┌──────────────┐
│ C26 Audit     │ Log: wie, wat, wanneer, waarom
│   Trail       │ + data_before / data_after snapshot
└──────────────┘

COMPONENTEN NODIG: C01, C25, C15, C26
GATEN:
  🔴 C15 Rapportage Service heeft GEEN versioning (alleen soft delete)
  🔴 C25 Eigenaarschap-check ontbreekt
  🔴 C26 Audit trail ontbreekt — geen bewijs van wijzigingen
```

### 3.2 Enterprise use cases (nieuw)

#### UC-23: Incident/MIC-melding registreren

```
FLOW:
Zorgverlener → "Incident melding: patiënt gevallen op kamer 3"

┌─────────────┐
│ C02 ⌘K      │ "incident melding patiënt gevallen"
└──────┬──────┘
       ▼
┌──────────────┐
│ C06 Reflex    │ Pattern: "incident" / "melding" / "MIC" / "gevallen"
│               │ → intent: NEW "incident_melding" (ONTBREEKT)
└──────┬───────┘
       ▼
┌──────────────┐
│ C08 Entity    │ Extraheer: patiënt, locatie, type incident
│   Extractor   │ "gevallen" → incident_type: "val"
└──────┬───────┘
       ▼
┌──────────────┐
│ C09 Action    │ Open incident-formulier (ONTBREEKT)
│               │ Velden: patiënt, datum/tijd, locatie, beschrijving,
│               │ ernst, getuigen, maatregelen genomen
└──────┬───────┘
       │ [gebruiker bevestigt]
       ▼
┌──────────────┐     ┌──────────────┐
│ C15 Rapportage│     │ C26 Audit     │
│   report_type:│     │   Trail       │
│   'incident'  │     └──────────────┘
└──────┬───────┘
       ▼
┌──────────────┐
│ C10 Protocol  │ Nudges:
│   Engine      │ → "Valpreventie protocol activeren?"
│               │ → "Informeer hoofdbehandelaar"
│               │ → "Plan follow-up observatie"
└──────────────┘

COMPONENTEN NODIG: C02, C06, C08, C09, C04, C15, C26, C10
NIEUWE COMPONENTEN NODIG:
  🔴 Intent 'incident_melding' toevoegen aan Registry
  🔴 Incident-formulier block (UI component)
  🔴 Protocol rules voor incidentopvolging
  🟡 Ernst-classificatie schema
  🟡 Notificatie naar hoofdbehandelaar (C-NEW: Notificatie Service)
```

#### UC-24: Wvggz-dwangmaatregel registreren

```
FLOW:
Arts → Registreer dwangmaatregel (bijv. separatie, gedwongen medicatie)

┌─────────────┐
│ C01 UI       │ Via traditionele formulier (te complex voor intent)
│               │ OF C02 ⌘K → "dwangmaatregel registreren [patient]"
└──────┬──────┘
       ▼
┌──────────────┐
│ C25 RBAC      │ Check: alleen arts/psychiater mag dwangmaatregel registreren
│   + ABAC      │ Check: patiënt heeft Wvggz legal_status
│               │ Check: toestemming/machtiging is actief (C22)
└──────┬───────┘
       ▼
┌──────────────┐
│ NEW: C34      │ Dwangmaatregel formulier
│ Wvggz Service │ Velden: type maatregel, start/eind, reden,
│               │ alternatieven overwogen, proportionaliteit
│               │ Juridische grondslag (zorgmachtiging nr.)
└──────┬───────┘
       ▼
┌──────────────┐     ┌──────────────┐
│ C22 Toestem-  │     │ C26 Audit     │ EXTRA LOGGING:
│   ming Service│     │   Trail       │ Wvggz-maatregel = P1 audit event
│   Verify OK   │     │               │ purpose: 'wvggz_dwangmaatregel'
└──────────────┘     └──────────────┘
       ▼
┌──────────────┐
│ C10 Protocol  │ Nudges:
│   Engine      │ → "Plan evaluatie dwangmaatregel (binnen 24u)"
│               │ → "Informeer geneesheer-directeur"
│               │ → "Registreer in Wvggz-register"
└──────────────┘

NIEUWE COMPONENTEN NODIG:
  🔴 C34 Wvggz Service (registratie, evaluatie, rapportage)
  🔴 C22 Toestemming Service (verificatie juridische grondslag)
  🔴 Wvggz-specifieke ABAC policies
  🔴 Protocol rules voor Wvggz-termijnen
  🔴 Notificatie naar geneesheer-directeur
```

#### UC-26: Audit log doorzoeken

```
FLOW:
Compliance officer → "Wie heeft dossier patiënt X bekeken afgelopen maand?"

┌─────────────┐
│ C01 UI       │ Admin → Audit log pagina
│   (admin)     │ Zoekfilters: patiënt, gebruiker, periode, actie
└──────┬──────┘
       ▼
┌──────────────┐
│ C25 RBAC      │ Check: rol = 'audit' of 'admin'
│               │ Audit officers hebben read-only toegang tot ALLE logs
└──────┬───────┘
       ▼
┌──────────────┐
│ C26 Audit     │ Query: forensische zoekopdracht
│   Trail       │ Filters: entity_type, entity_id, user_id, date range
│               │ Resultaat: gesorteerd op timestamp
└──────┬───────┘
       ▼
┌──────────────┐
│ C26 Audit     │ META: het doorzoeken van de audit log
│   Trail       │ wordt ZELF ook gelogd (wie zoekt wat op)
└──────────────┘

COMPONENTEN NODIG: C01, C25, C26
GATEN:
  🔴 C26 Audit log UI (admin pagina) ontbreekt volledig
  🔴 Export functie (CSV/PDF voor externe auditor)
  🟡 Anomalie-detectie dashboard
```

#### UC-33: Noodtoegang ("break the glass")

```
FLOW:
Arts in noodsituatie → toegang nodig tot patiënt die niet is toegewezen

┌─────────────┐
│ C01 UI       │ Patiëntdossier → "Geen toegang" melding
│               │ → Knop: "Noodtoegang aanvragen"
└──────┬──────┘
       ▼
┌──────────────┐
│ C25 RBAC      │ Normale check FAALT (niet toegewezen)
│   + ABAC      │ → Noodtoegang flow activeren
└──────┬───────┘
       ▼
┌──────────────────────────────────────┐
│ NEW: Break-the-Glass Dialog           │
│ "U bent niet toegewezen aan deze      │
│  patiënt. Noodtoegang vereist een    │
│  reden."                              │
│                                       │
│  Reden: [dropdown]                    │
│  - Medisch noodgeval                  │
│  - Dienstdoend arts (geen toewijzing) │
│  - Vervanging collega                 │
│  Toelichting: [vrij tekstveld]        │
│                                       │
│  [Annuleren]  [Noodtoegang activeren] │
└──────┬───────────────────────────────┘
       │ [gebruiker bevestigt]
       ▼
┌──────────────┐
│ C26 Audit     │ P1 AUDIT EVENT:
│   Trail       │ action: 'emergency_access'
│               │ purpose: reden uit formulier
│               │ → Automatische notificatie naar privacy officer
└──────┬───────┘
       ▼
┌──────────────┐
│ C21 Patiënt   │ Tijdelijke toegang (bijv. 4 uur)
│   Service     │ Auto-expire na timeout
└──────────────┘

NIEUWE COMPONENTEN NODIG:
  🔴 Break-the-glass UI component
  🔴 Tijdelijke toegang mechanisme in C25
  🔴 Automatische notificatie service
  🔴 Auto-expire logica
```

---

## 4. Gap Analyse — Samenvatting

### 4.1 Kritieke gaten (blokkeren enterprise deployment)

| # | Gap | Impact | Benodigde componenten | Inspanning |
|---|-----|--------|----------------------|------------|
| G1 | **Geen audit trail** | NEN 7513 niet-compliant, geen bewijs bij audit | C26 volledig bouwen | 2-3 weken |
| G2 | **Geen multi-tenancy** | Kan niet bij meerdere instellingen draaien | C24 volledig bouwen | 2-3 weken |
| G3 | **Geen RBAC/ABAC** | Iedereen ziet alles, geen rolgebaseerde toegang | C25 volledig bouwen | 2-3 weken |
| G4 | **Intent Registry ontbreekt** | Patronen verspreid over 3-4 bestanden | C05 centraliseren | 2-3 dagen |
| G5 | **Protocol Engine niet actief** | Nudges bestaan maar worden nooit getoond | C10 aansluiten + C11 rules store | 1-2 weken |
| G6 | **Geen versioning op rapportages** | Wijzigingsgeschiedenis niet traceerbaar | C15 uitbreiden | 3-5 dagen |
| G7 | **Geen field encryptie** | BSN en diagnoses onversleuteld in DB | C27 bouwen | 1 week |

### 4.2 Functionele gaten (ontbrekende GGZ-modules)

| # | Gap | Impact | Inspanning |
|---|-----|--------|------------|
| G8 | **Behandelplan module** | Kernfunctie GGZ ontbreekt volledig | C18: 3-4 weken |
| G9 | **Medicatie module** | Wettelijk verplicht, hoog-risico domein | C19: 3-4 weken |
| G10 | **Wvggz registratie** | Kan geen verplichte zorg registreren | C34 + C22: 2-3 weken |
| G11 | **Incident/MIC module** | Wkkgz niet-compliant | Uitbreiding C15 + intent: 1-2 weken |
| G12 | **Knowledge Layer** | Geen protocol-gestuurde nudges | C11-C14: 4-6 weken |

### 4.3 Technische gaten

| # | Gap | Impact | Inspanning |
|---|-----|--------|------------|
| G13 | **Geen SSO/SAML** | Enterprise instellingen vereisen SSO | C23 uitbreiden: 1 week |
| G14 | **Geen structured logging** | Console.log in productie = blind vliegen | C30: 1 week |
| G15 | **Geen health checks** | Geen alerting bij uitval | C32: 2-3 dagen |
| G16 | **Circuit breaker incompleet** | Alleen voor classify, niet generiek | C31 generaliseren: 3-5 dagen |
| G17 | **PII filter incompleet** | Patiëntdata lekt naar AI prompts | C33 uitbreiden: 3-5 dagen |
| G18 | **Geen FHIR Bundle export** | Alleen Patient endpoint, rest ontbreekt | C28 uitbreiden: 1-2 weken |
| G19 | **Geen notificatie service** | Geen alerts bij incidenten, Wvggz-termijnen | Nieuw component: 1-2 weken |
| G20 | **Geen caching** | AI samenvattingen elke keer opnieuw genereren | Cache layer toevoegen: 3-5 dagen |

---

## 5. Use Case × Component Kruistabel

Welk component is nodig voor welke use case? `●` = nodig, `○` = optioneel, `-` = niet relevant.

```
                    UC  UC  UC  UC  UC  UC  UC  UC  UC  UC  UC  UC  UC
Component           01  05  07  10  11  21  23  24  26  27  31  32  33
                   dag ovdr zoek afsp ann beh  inc wvgz aud fhir ver  grp nood
─────────────────────────────────────────────────────────────────────────────
C01 EPD UI          ○   ●   ○   ○   ○   ●   ●   ●   ●   ●   ●   ●   ●
C02 Command Center  ●   ●   ●   ●   ●   ○   ●   ○   -   -   -   ○   -
C03 Spraak          ○   -   -   -   -   -   ○   -   -   -   -   ○   -
C04 Block/Artifact  ●   ●   ●   ●   ●   -   ●   -   -   -   -   -   -
C05 Intent Registry ●   ●   ●   ●   ●   -   ●   -   -   -   -   -   -
C06 Reflex          ●   ●   ●   ●   ●   -   ●   -   -   -   -   -   -
C07 Orchestrator    ○   ○   ○   ○   ○   -   ○   -   -   -   -   -   -
C08 Entity Extract  ●   -   ●   ●   ●   -   ●   -   -   -   -   -   -
C09 Action System   ●   ●   ●   ●   ●   -   ●   -   -   -   -   -   -
C10 Protocol Engine ●   ●   -   -   -   ●   ●   ●   -   -   -   -   -
C15 Rapportage Svc  ●   ●   -   -   -   -   ●   -   -   -   ●   ●   -
C16 Overdracht Svc  -   ●   -   -   -   -   -   -   -   -   -   -   -
C17 Agenda Svc      -   -   -   ●   ●   -   -   -   -   -   -   -   -
C18 Behandelplan    -   -   -   -   -   ●   -   -   -   ○   -   -   -
C21 Patiënt Svc     ●   ●   ●   ●   -   ●   ●   ●   -   ●   -   -   ●
C22 Toestemming     -   -   -   -   -   -   -   ●   -   -   -   -   -
C24 Multi-tenancy   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●
C25 RBAC/ABAC       ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●
C26 Audit Trail     ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●
C27 Field Encrypt   -   -   ○   -   -   -   -   ●   -   ●   -   -   -
C28 FHIR Export     -   -   -   -   -   -   -   -   -   ●   -   -   -
C30 Observability   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●   ●
C31 Circuit Breaker ○   ●   -   -   -   -   -   -   -   -   -   -   -
C33 PII Filter      ○   ●   -   -   -   -   -   -   -   -   -   -   -
C34 Wvggz Svc       -   -   -   -   -   -   -   ●   -   -   -   -   -
```

**Leeswijzer**: C24 (Multi-tenancy), C25 (RBAC), C26 (Audit) en C30 (Observability) zijn nodig voor **elke** use case. Dit zijn de vier horizontale lagen die als eerste gebouwd moeten worden.

---

## 6. Bouwvolgorde — Prioritering op basis van gaps

### Fase 0: Horizontale lagen (weken 1-4)

Bouw de vier componenten die **elke** use case nodig heeft:

```
Week 1-2:  C24 Multi-tenancy (RLS, tenant context middleware)
           C26 Audit Trail (immutable log, NEN 7513)

Week 3-4:  C25 RBAC + ABAC Engine (rollen, policies, evaluatie)
           C30 Observability (Pino structured logging)
```

**Waarom eerst**: Zonder deze vier werkt geen enkele enterprise use case. Retrofit is exponentieel duurder.

### Fase 1: Intent systeem solide maken (weken 5-6)

```
Week 5:    C05 Intent Registry (centraliseer patronen uit reflex-classifier)
           C06 Reflex refactor (lees uit Registry)
           C07 Orchestrator refactor (unified pipeline met Classify)

Week 6:    C10 Protocol Engine activeren (nudge.ts aansluiten)
           C15 Rapportage versioning + soft delete (G6)
           C33 PII Filter uitbreiden
```

**Na deze fase**: UC-01 t/m UC-20 werken enterprise-grade.

### Fase 2: Ontbrekende GGZ-modules (weken 7-12)

```
Week 7-8:  C18 Behandelplan Service (UC-21)
           C19 Medicatie Service (UC-22)

Week 9-10: C22 Toestemming Service (UC-25)
           C34 Wvggz Service (UC-24)
           UC-23 Incident/MIC formulier

Week 11-12: C27 Field Encryption (BSN, diagnoses)
            C23 Auth uitbreiden (SSO/SAML, MFA)
            UC-33 Break-the-glass noodtoegang
```

### Fase 3: Knowledge Layer + interoperabiliteit (weken 13-18)

```
Week 13-14: C11 Protocol Rules Store (database)
            C13 Regelvalidatie UI (admin)

Week 15-16: C12 RAG Pipeline (pgvector, protocol indexering)
            C14 Kennisbron Connectors (eerste protocollen inladen)

Week 17-18: C28 FHIR Export (alle resources)
            C29 CDS Hooks Service
            C32 Health Check + C31 Circuit Breaker generaliseren
```

---

## 7. Technische Specificaties per Component

### 7.1 C24 Multi-tenancy — Specificatie

**Verantwoordelijkheid**: Isoleer data per instelling/tenant.

**Database wijzigingen**:
- `tenant_id UUID NOT NULL` kolom op ELKE tabel met patiëntdata
- RLS policy per tabel: `USING (tenant_id = get_current_tenant())`
- Helper function: `get_current_tenant()` leest uit `app.current_tenant_id` setting

**Middleware**:
```typescript
// Elke request:
// 1. Haal user op uit Supabase Auth
// 2. Lees tenant_id uit user metadata
// 3. Zet als header voor Server Components
// 4. Zet als PostgreSQL setting voor RLS
```

**Bestanden**:
- `lib/auth/tenant-context.ts` — Helper om tenant te zetten/lezen
- `middleware.ts` — Injecteer tenant in elke request
- Migratie: `add_tenant_id_to_all_tables.sql`
- Migratie: `create_rls_policies.sql`

**Test**: Maak twee tenants, voeg patiënt toe aan tenant A, verifieer dat tenant B de patiënt NIET kan zien.

---

### 7.2 C26 Audit Trail — Specificatie

**Verantwoordelijkheid**: Onwijzigbare log van alle toegang en wijzigingen aan patiëntdata.

**Database**:
- Tabel `audit_logs` (zie enterprise-epd-architectuur.md §5.2)
- Partitionering per maand
- Triggers die UPDATE/DELETE blokkeren
- Hash chain voor integriteitsverificatie

**API**:
```typescript
// lib/audit/logger.ts
logAuditEvent({ entityType, entityId, action, purpose, cortexIntent?, metadata? })

// Automatisch:
// - user_id, user_role, user_name uit auth context
// - tenant_id uit tenant context
// - timestamp server-side
// - data_hash berekend
// - previous_hash opgehaald
```

**Integratiepunten**: Elke API route roept `logAuditEvent()` aan na succesvolle actie. Dit is een **hard requirement** — geen route zonder audit log.

**Bestanden**:
- `lib/audit/logger.ts` — Core logging functie
- `lib/audit/hash.ts` — Hash chain berekening
- `app/api/audit/route.ts` — Query endpoint (admin only)
- Migratie: `create_audit_logs.sql`

---

### 7.3 C25 RBAC + ABAC — Specificatie

**Verantwoordelijkheid**: Bepaal of een gebruiker een actie mag uitvoeren op een resource.

**Twee lagen**:
1. **RBAC** (snel): Rol → vaste permissions set
2. **ABAC** (verfijnd): Context-afhankelijke policies (toewijzing, toestemming, tijdvenster)

**API**:
```typescript
// lib/access-control/evaluator.ts
const { allowed, reason } = await evaluateAccess({
  userId, action, resource, resourceId, tenantId
});

if (!allowed) {
  return Response.json({ error: 'Geen toegang', reason }, { status: 403 });
}
```

**Bestanden**:
- `lib/access-control/roles.ts` — Rol definities en basis permissions
- `lib/access-control/policies.ts` — ABAC policy definities
- `lib/access-control/evaluator.ts` — Policy evaluatie engine
- Migratie: `create_access_policies.sql`

---

### 7.4 C05 Intent Registry — Specificatie

**Verantwoordelijkheid**: Single source of truth voor alle intent definities.

**Structuur per intent**:
```typescript
interface IntentDefinition {
  id: CortexIntent;                    // 'dagnotitie', 'zoeken', etc.
  label: { nl: string; en: string };   // Mensleesbare labels
  description: string;                 // Voor LLM context
  priority: 'P1' | 'P2' | 'P3';

  // Reflex patterns
  reflexPatterns: Array<{
    pattern: RegExp;
    weight: number;
    extractHints?: string[];           // Welke entities te extracten
  }>;

  // Orchestrator hints
  aiExamples: Array<{
    input: string;
    expectedIntent: CortexIntent;
    expectedEntities: Record<string, string>;
  }>;

  // Entity configuratie
  entities: {
    required: string[];                // Welke entities verplicht
    optional: string[];
  };

  // Action mapping
  artifactType: string;                // Welk block/formulier openen
  requiresConfirmation: boolean;       // Destructieve actie?

  // Access control
  allowedRoles?: string[];             // Welke rollen mogen dit intent gebruiken
  featureFlag?: string;                // Feature flag voor geleidelijke uitrol
  enabled: boolean;
}
```

**Opslag**: TypeScript config file (fase 1), migreerbaar naar database (fase 3).

**Bestanden**:
- `lib/cortex/registry/intent-registry.ts` — Registry class
- `lib/cortex/registry/definitions/dagnotitie.ts` — Per intent een definitie
- `lib/cortex/registry/definitions/zoeken.ts`
- `lib/cortex/registry/definitions/index.ts` — Barrel export
- `lib/cortex/registry/types.ts` — IntentDefinition interface

---

### 7.5 C10 Protocol Engine — Specificatie

**Verantwoordelijkheid**: Evalueer klinische regels na afgeronde acties. Stel vervolgacties voor.

**Pure function**: `(completedAction, patientContext, rules) → suggestions[]`

**Regel evaluatie**:
```typescript
// lib/cortex/protocol-engine/evaluator.ts

async function evaluateRules(
  completedAction: CompletedAction,
  patientContext: PatientContext,
  rules: ProtocolRule[]
): Promise<NudgeSuggestion[]> {

  const applicableRules = rules.filter(rule =>
    rule.status === 'actief' &&
    rule.trigger.afterIntent?.includes(completedAction.intent)
  );

  const suggestions: NudgeSuggestion[] = [];

  for (const rule of applicableRules) {
    const conditionMet = await evaluateCondition(rule.condition, patientContext);
    if (conditionMet) {
      suggestions.push({
        ruleId: rule.id,
        message: rule.suggestion.message,
        priority: rule.suggestion.priority,
        evidence: rule.suggestion.evidence,
        suggestedIntent: rule.suggestion.suggestedIntent,
        source: rule.source,
      });
    }
  }

  return suggestions.sort((a, b) =>
    a.priority.localeCompare(b.priority) // P1 eerst
  );
}
```

**Bestanden**:
- `lib/cortex/protocol-engine/evaluator.ts` — Rule evaluatie
- `lib/cortex/protocol-engine/conditions.ts` — Conditie evaluatie (static + query)
- `lib/cortex/protocol-engine/rules/` — Gevalideerde regels per domein
- `app/api/cortex/nudge/route.ts` — API endpoint

---

## 8. Validatie Conclusie

### De architectuur ondersteunt alle use cases MITS:

1. **De vier horizontale lagen eerst gebouwd worden** (G1-G3 + G14): multi-tenancy, audit, RBAC, logging
2. **Het intent systeem gecentraliseerd wordt** (G4): Intent Registry als single source of truth
3. **De Protocol Engine aangesloten wordt** (G5): nudge.ts → protocol-engine met rules store
4. **Ontbrekende GGZ-modules gebouwd worden** (G8-G12): behandelplan, medicatie, Wvggz, incidenten

### Wat de architectuur GOED doet:

- Dual interface (traditioneel + intent) ondersteunt alle use cases via twee paden
- De pipeline (Registry → Classify → Resolve → Action → Protocol) is generiek genoeg voor nieuwe intents
- Multi-tenancy via RLS is pragmatisch en past bij Supabase
- Audit trail als horizontale laag dekt alle use cases zonder per-module implementatie

### Wat nog aandacht nodig heeft:

- ~~**Notificatie service** (niet in architectuur): incidenten, Wvggz-termijnen, break-the-glass alerts~~ → **Opgelost: C34** (zie `enterprise-componenten-uitbreiding.md`)
- **Groepstherapie** (UC-32): één rapportage voor meerdere patiënten — huidige datamodel is 1:1
- ~~**Caching strategie**: AI-samenvattingen zijn duur, caching ontbreekt in architectuur~~ → **Opgelost: C37** (zie `enterprise-componenten-uitbreiding.md`)
- **Offline support**: niet besproken, maar relevant voor mobiele zorgverleners

### Uitbreiding: 10 nieuwe componenten (C34–C43)

Na de initiële gap analyse zijn 10 aanvullende enterprise componenten geïdentificeerd en gespecificeerd. Deze zijn gedocumenteerd in **`enterprise-componenten-uitbreiding.md`** en omvatten:

| Component | Laag | Status |
|-----------|------|--------|
| C34 Notificatie Service | Platform Services | Interface gedefinieerd |
| C35 Workflow Engine (State Machine) | Platform Services | Interface + voorbeeldworkflows |
| C36 Full-Text Search | Platform Services | Interface + PostgreSQL tsvector schema |
| C37 Caching Layer | Platform Services | Interface + TTL strategie |
| C38 Scheduled Jobs | Platform Services | Interface + job definities |
| C39 Webhook System | Platform Services | Interface + security (HMAC) |
| C40 ZPM Facturatie | Externe Integraties | Interface + database schema |
| C41 Vecozo Connector | Externe Integraties | Interface + mock (voorbereiding) |
| C42 Zorgdomein Connector | Externe Integraties | Interface + mock (voorbereiding) |
| C43 BI Module | Analytics | Materialized views gedefinieerd |

De gap items G19 (notificatie) en G20 (caching) uit §4.3 zijn hiermee opgelost. Zie het uitbreidingsdocument voor volledige interface definities, database schemas en integratiepunten.
