docs: architectuurdocs, styleguides en release notes intake/behandelplan

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
colinislit
2026-07-09 23:16:28 +02:00
parent 9195eb9fed
commit c0a4fa24f2
15 changed files with 12143 additions and 0 deletions

View File

@@ -0,0 +1,864 @@
# 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 (C34C43)
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.