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.*