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

Architectuur Overzicht — Mini-EPD

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

---

1. Introductie

Mini-EPD is een elektronisch patiëntendossier voor de geestelijke gezondheidszorg. Het systeem combineert klassieke dossiervoering met een AI-gestuurde spraakinterface genaamd Cortex.

Elevator pitch: Een EPD waarin zorgmedewerkers niet hoeven te klikken, maar gewoon zeggen wat ze willen doen. "Maak notitie voor Jan, medicatie gegeven" — en het gebeurt.

---

2. Technische Stack

Laag	Technologie	Rol
Frontend	Next.js 14, React, Tailwind CSS	Gebruikersinterface
Backend	Next.js API Routes	Server-logica en API's
Database	Supabase (PostgreSQL)	Opslag patiëntgegevens
Authenticatie	Supabase Auth	Inloggen en toegangsbeheer
AI - Taal	Claude (Anthropic)	Classificatie en samenvatting
AI - Spraak	Deepgram	Spraak-naar-tekst
Hosting	Vercel	Deployment en hosting

---

3. Module-overzicht

Het systeem bestaat uit zes hoofdmodules:

Module	Doel	Primaire gebruiker
Cortex	AI spraak/tekst commando's	Iedereen
Dashboard	Overzicht werkzaamheden	Behandelaar
Patiënten	Dossiers en intake	Iedereen
Verpleegrapportage	Dagnotities en overdracht	Verpleegkundige
Agenda	Afspraken en planning	Iedereen
Clients	(Legacy, doorverwijzing)	—

Module-beschrijvingen

Cortex — AI Command Center

Het "brein" van het systeem. Medewerkers geven spraak- of tekstcommando's, Cortex begrijpt de intentie en voert de actie uit. Bijvoorbeeld: "zoek marie" opent direct het zoekscherm met resultaten.

Dashboard

Startpagina met overzicht van caseload, aandachtspunten en aankomende afspraken. Geeft behandelaars in één oogopslag zicht op hun werk.

Patiënten

Beheer van alle patiënten en hun dossiers. Elk dossier bevat:

• Basisgegevens (NAW, verzekering)
• Screening (hulpvraag, documenten)
• Intake (anamnese, diagnoses, risico's)
• Behandelplan (doelen, interventies)
• Rapportage (dagnotities)

Verpleegrapportage

Twee functies:

1. Rapportage — Invoer van dagelijkse observaties per patiënt
2. Overdracht — AI-samenvatting van alle notities voor shift-wissel

Agenda

Kalenderweergave van alle afspraken. Filtert per patiënt, dag of week.

---

4. Cortex — Diepere Uitwerking

Cortex is het onderscheidende element van dit EPD. Het werkt met drie lagen:

Laag 1: Reflex Arc (Snelle herkenning)

• Wat: Lokale patroonherkenning zonder AI
• Snelheid: <20 milliseconden
• Wanneer: Eenvoudige, veelvoorkomende commando's
• Voorbeeld: "notitie jan" → herkent direct als "dagnotitie maken"

Laag 2: Orchestrator (AI-classificatie)

• Wat: Claude AI analyseert complexe invoer
• Snelheid: 200-800 milliseconden
• Wanneer: Meerdere acties, context nodig, onduidelijke input
• Voorbeeld: "Zeg jan af en maak notitie griep" → herkent twee acties

Laag 3: Nudge (Proactieve suggesties)

• Wat: Suggesties na voltooide acties
• Wanneer: Na opslaan van bepaalde notities
• Voorbeeld: Notitie met "wond" → suggestie: "Wondcontrole inplannen?"

Ondersteunde commando's (intents)

Intent	Wat het doet	Voorbeeld
dagnotitie	Verpleegkundige notitie	"medicatie jan gegeven"
zoeken	Patiënt zoeken	"zoek marie"
overdracht	Overdracht openen	"overdracht"
agenda_query	Afspraken bekijken	"afspraken vandaag"
create_appointment	Afspraak maken	"plan intake jan morgen 14:00"
cancel_appointment	Afspraak annuleren	"annuleer afspraak jan"
intake_status	Intake voortgang	"wat moet ik nog doen?"

Cortex UI-opbouw

Het scherm is verticaal gesplitst:

• Links (40%): Chat — conversatie met Cortex
• Rechts (60%): Werkgebied — formulieren en lijsten

Sneltoetsen:

• Cmd/Ctrl + K — Focus op invoerveld
• Cmd/Ctrl + Enter — Verstuur commando
• Esc — Sluit werkgebied

---

5. Data-architectuur

Kernentiteiten

De database is georganiseerd rond de patiënt als centrale entiteit:

Entiteit	Beschrijving
patients	Basisgegevens patiënten
encounters	Contactmomenten (afspraken, bezoeken)
observations	Meetgegevens (vitals, symptomen)
conditions	Diagnoses en aandoeningen
reports	Alle notities en rapportages
intakes	Intake-trajecten
care_plans	Behandelplannen
risk_assessments	Risico-evaluaties
practitioners	Zorgverleners

Rapportage-types

Alle notities zitten in één tabel (reports) met een type-aanduiding:

Type	Gebruik
verpleegkundig	Dagelijkse zorgnotities
observatie	Klinische waarnemingen
incident	Incidenten/crises
voortgang	Voortgangsnota's
medicatie	Medicijnbeheer
contact	Contactlogboek

API-groepen

De backend API's zijn logisch gegroepeerd:

Groep	Functie
/api/patients/*	Patiëntgegevens
/api/reports/*	Rapportages CRUD
/api/overdracht/*	Shift-overdracht + AI-samenvatting
/api/intakes/*	Intake-beheer
/api/cortex/*	AI command center
/api/deepgram/*	Spraakherkenning

---

6. Diagrambeschrijvingen

Onderstaande beschrijvingen kun je gebruiken om visuele diagrammen te maken.

Diagram A: Systeemoverzicht (Container)

Componenten:

1. Gebruiker (persoon) — Zorgmedewerker met browser
2. Frontend (container) — Next.js React applicatie
3. API Layer (container) — Next.js API Routes
4. Database (container) — Supabase PostgreSQL
5. Claude AI (externe service) — Anthropic API
6. Deepgram (externe service) — Spraak-naar-tekst API

Verbindingen:

• Gebruiker → Frontend (HTTPS)
• Frontend → API Layer (REST/SSE)
• API Layer → Database (SQL via Supabase client)
• API Layer → Claude AI (HTTPS, voor classificatie en samenvatting)
• Frontend → Deepgram (WebSocket, voor live spraak)

---

Diagram B: Cortex Flow (Sequence)

Actoren: Gebruiker, Frontend, Reflex Arc, Orchestrator (Claude), Database

Flow:

1. Gebruiker spreekt/typt commando
2. Frontend stuurt tekst naar API
3. Reflex Arc probeert lokaal te classificeren
4. Als succesvol: Retourneer intent + entiteiten
5. Als niet succesvol: Escaleer naar Orchestrator
6. Orchestrator (Claude) analyseert en retourneert intent chain
7. Frontend toont juiste werkgebied (formulier/lijst)
8. Gebruiker voltooit actie
9. Data wordt opgeslagen in Database
10. (Optioneel) Nudge evalueert en toont suggestie

---

Diagram C: Module-relaties (Component)

Modules en hun connecties:

┌─────────────────────────────────────────────────────┐
│                    CORTEX                           │
│  (kan alle andere modules aansturen via commando's) │
└───────────────────────┬─────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
┌───────────┐   ┌───────────────┐   ┌────────┐
│ PATIËNTEN │◄──│ VERPLEEG-     │   │ AGENDA │
│           │   │ RAPPORTAGE    │   │        │
└─────┬─────┘   └───────────────┘   └────────┘
      │
      ▼
┌─────────────┐
│ DASHBOARD   │
│ (overzicht) │
└─────────────┘

Beschrijving:

• Cortex fungeert als "universele afstandsbediening"
• Patiënten-module is de kern voor dossierdata
• Verpleegrapportage leest en schrijft naar patiëntendossiers
• Agenda toont afspraken gekoppeld aan patiënten
• Dashboard aggregeert data uit alle modules

---

Diagram D: Data-relaties (ERD vereenvoudigd)

Entiteiten en relaties:

PATIENT (1) ──────< (N) ENCOUNTER
    │
    ├──────< (N) OBSERVATION
    │
    ├──────< (N) CONDITION
    │
    ├──────< (N) REPORT
    │
    └──────< (N) INTAKE
                  │
                  ├──── ANAMNESE
                  ├──── EXAMINATION
                  ├──── RISK_ASSESSMENT
                  └──── CARE_PLAN

Leeswijzer:

• Eén patiënt heeft meerdere contactmomenten (encounters)
• Eén patiënt heeft meerdere observaties, diagnoses en rapportages
• Eén patiënt kan meerdere intake-trajecten doorlopen
• Elk intake-traject bevat anamnese, onderzoek, risico's en behandelplan

---

7. Glossary

Term	Betekenis
EPD	Elektronisch Patiënten Dossier
Cortex	AI command center voor spraak/tekst commando's
Intent	Gedetecteerde bedoeling achter een commando
Reflex Arc	Snelle, lokale patroonherkenning (geen AI)
Orchestrator	AI-laag voor complexe classificatie
Nudge	Proactieve suggestie na een actie
Overdracht	Shift-wissel met samenvatting van notities
RLS	Row Level Security — database-beveiliging per gebruiker
Intake	Opnameproces nieuwe patiënt
Anamnese	Medische voorgeschiedenis
ROM	Routine Outcome Monitoring — effectmeting behandeling
FHIR	Internationale standaard voor zorgdata-uitwisseling

---

8. Contactpunten voor verdieping

Onderwerp	Waar te vinden
Functioneel ontwerp Cortex	docs/swift/
API-documentatie	app/api/ (code + comments)
Database schema	supabase/migrations/
UI componenten	components/
Release notes	docs/releasenotes/

---

Dit document geeft een high-level overzicht. Voor technische implementatiedetails, raadpleeg de broncode of vraag het development team.