# Mini-EPD — Architectuur & Datacomponenten (PO/PM-overzicht)

> Doel van dit document: één begrijpelijk overzicht van **wat het systeem doet**, **uit welke bouwblokken het bestaat** en **welke gegevens het beheert** — zonder dat je code hoeft te lezen. Bedoeld voor product owners en project managers.

---

## 1. In één alinea

Het Mini-EPD is een **elektronisch patiëntdossier voor de GGZ**. Een zorgverlener kan patiënten aanmelden, intake doen, behandelplannen maken, dagelijkse rapportages schrijven en diensten overdragen aan een collega. Het bijzondere is de **Cortex AI Command Center**: een natuurlijke-taal-interface (typen of inspreken) waarmee de zorgverlener acties uitvoert in gewone zinnen, zoals *"maak een notitie voor Jan: medicatie ingenomen"* of *"plan een afspraak morgen om 14:00"*.

---

## 2. De drie lagen van het systeem

```
┌──────────────────────────────────────────────────────────────┐
│  1. WAT DE GEBRUIKER ZIET (de modules / schermen)             │
│     Dashboard · Patiëntdossier · Intake · Behandelplan ·       │
│     Verpleegrapportage · Agenda · Cortex AI Command Center     │
├──────────────────────────────────────────────────────────────┤
│  2. DE LOGICA (de API's / verwerking)                          │
│     Rapportage · Overdracht · Behandelplan · Intake ·          │
│     Cortex (intentherkenning + chat) · Spraak-naar-tekst       │
├──────────────────────────────────────────────────────────────┤
│  3. DE GEGEVENS (de database + externe diensten)               │
│     Supabase database · Claude AI · Deepgram (spraak)          │
└──────────────────────────────────────────────────────────────┘
```

---

## 3. De modules (wat de gebruiker ziet)

| Module | Wat de zorgverlener ermee doet |
|---|---|
| **Dashboard** | Startscherm met het Cortex AI Command Center. Hier begint elke actie. |
| **Patiëntdossier** | Volledig dossier per patiënt: basisgegevens (incl. BSN), diagnoses, observaties, intakes. |
| **Intake** | Stapsgewijze intakeprocedure voor een nieuwe patiënt: contactpersonen, risicotaxatie, anamnese, onderzoek, diagnose, behandeladvies. |
| **Behandelplan** | Behandeldoelen en interventies per leefgebied vastleggen en beheren. |
| **Verpleegrapportage** | Dagelijkse notities in een tijdlijn (nacht/ochtend/middag/avond) + **overdracht** met AI-samenvatting voor de collega van de volgende dienst. |
| **Agenda** | Kalender met alle afspraken; afspraken inplannen, verzetten of annuleren. |

---

## 4. Het hart: Cortex AI Command Center

De zorgverlener typt of spreekt een opdracht in. Het systeem begrijpt de bedoeling ("intent") en voert de juiste actie uit. Dit gebeurt in **drie slimme lagen** die samen snelheid én begrip combineren:

```
Gebruiker zegt/typt iets
          │
          ▼
┌─────────────────────┐   Snel & gratis. Herkent veelvoorkomende
│ 1. REFLEX (lokaal)  │   opdrachten direct via patronen (<20ms).
└─────────┬───────────┘   Twijfel of complex? → door naar laag 2.
          │
          ▼
┌─────────────────────┐   AI (Claude) lost lastige gevallen op:
│ 2. ORCHESTRATOR (AI)│   meerdere opdrachten tegelijk, "hem/haar",
└─────────┬───────────┘   "morgen", onduidelijke zinnen.
          │
          ▼
   Actie wordt uitgevoerd (notitie opgeslagen, afspraak gemaakt...)
          │
          ▼
┌─────────────────────┐   Proactieve suggestie achteraf, bijv.
│ 3. NUDGE            │   "Wil je hier ook een observatie bij maken?"
└─────────────────────┘
```

**Waarom drie lagen?** De Reflex-laag handelt het gros af zonder AI-kosten en zonder vertraging. Alleen echt lastige zinnen gaan naar de (betaalde, iets tragere) AI. De Nudge-laag verhoogt de zorgkwaliteit door op het juiste moment iets te suggereren.

**Wat begrijpt Cortex (de "intents"):**
- Dagnotitie maken · Patiënt zoeken · Overdracht bekijken
- Agenda opvragen · Afspraak inplannen / annuleren / verzetten

**Chat & artifacts:** Het scherm is gesplitst — links een **chatpaneel** (gesprek met de assistent), rechts een **werkblok** ("artifact") dat past bij de opdracht: een notitieformulier, een overdrachtssamenvatting, een zoekresultaat, enzovoort.

---

## 5. De externe diensten (afhankelijkheden)

| Dienst | Waarvoor | Belang voor het product |
|---|---|---|
| **Supabase** | Database + inloggen (authenticatie) | De plek waar alle patiëntgegevens veilig staan. |
| **Claude (Anthropic)** | AI: intentherkenning, chat, overdrachtssamenvatting, behandelplan genereren | De "intelligentie" achter Cortex en de samenvattingen. |
| **Deepgram** | Spraak omzetten naar tekst | Maakt inspreken van notities mogelijk. |

> **Aandachtspunt PO/PM:** Claude en Deepgram zijn betaalde externe API's. Gebruik = kosten. Cortex is bewust zo ontworpen dat de goedkope lokale laag het meeste afvangt.

---

## 6. De gegevens (datacomponenten)

Het datamodel is **FHIR-geïnspireerd**. FHIR is de internationale standaard voor gestructureerde zorggegevens. "Geïnspireerd" betekent: we volgen de standaard waar het helpt voor uitwisselbaarheid met andere systemen (denk ICD-10/DSM-5 diagnosecodes, BIG/AGB-nummers), maar pragmatisch vereenvoudigd waar dat sneller bouwt.

### De kerngegevens en hoe ze samenhangen

```
                        ┌──────────────┐
                        │  PATIËNT     │  (naam, BSN, geboortedatum, status)
                        └──────┬───────┘
        ┌──────────────┬───────┼───────────┬──────────────┐
        ▼              ▼       ▼            ▼              ▼
  ┌──────────┐  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
  │SCREENING │  │ INTAKE   │ │ DIAGNOSE │ │OBSERVATIE│ │BEHANDEL- │
  │(aanmeld) │  │(+ risico,│ │(condition)│ │(meting)  │ │  PLAN    │
  │          │  │ anamnese,│ │          │ │          │ │(doelen,  │
  │          │  │ onderzoek)│ │          │ │          │ │interventies)│
  └──────────┘  └────┬─────┘ └──────────┘ └──────────┘ └──────────┘
                     │
                     ▼
              ┌──────────────┐
              │ CONTACTMOMENT │  (encounter: intake-gesprek, sessie)
              └──────┬───────┘
                     ▼
              ┌──────────────┐
              │  RAPPORTAGE   │  (dagnotities: voortgang, observatie,
              │  (reports)    │   incident, medicatie, verpleegkundig...)
              └──────────────┘
```

### Wat elk gegevenstype bevat

| Gegevenstype | Wat het is |
|---|---|
| **Patiënt** | De persoon in zorg: naam, BSN, geboortedatum, en een **status** (aangemeld → in zorg → afgerond / afgemeld). |
| **Behandelaar** | De zorgprofessional, met BIG- en AGB-nummer; gekoppeld aan het inlogaccount. |
| **Organisatie** | De GGZ-instelling. |
| **Screening** | Het aanmeldproces: hulpvraag, activiteitenlog, documenten (verwijsbrieven), en het besluit (geschikt / niet geschikt). |
| **Intake** | De intakesessie met onderliggende onderdelen: **anamnese**, **onderzoeken** en **risicotaxaties** (bv. suïcide-/agressierisico met niveau laag→zeer hoog). |
| **Diagnose** (condition) | DSM-5/ICD-10 diagnoses met status. |
| **Observatie** | Metingen en inschattingen (vitale waarden, ROM-scores, klachten). |
| **Behandelplan** | Doelen en interventies, gekoppeld aan diagnoses. |
| **Contactmoment** (encounter) | Een afspraak of sessie tussen patiënt en behandelaar (voedt ook de agenda). |
| **Rapportage** (reports) | Eén centrale tabel voor álle dagnotities, met een **type** (voortgang, observatie, incident, medicatie, contact, crisis, verpleegkundig, ...) en een **categorie** (medicatie, ADL, gedrag, incident, observatie). |

### De patiëntreis door de data

```
Aangemeld  →  Screening  →  Intake  →  In zorg          →  Overdracht
(status:      (besluit:     (anamnese, (diagnoses,           (samenvatting
 planned)     geschikt?)    risico,    behandelplan,          voor volgende
                            onderzoek) dagrapportages)        dienst)
```

---

## 7. Belangrijke regels in de data (voor PO/PM goed om te weten)

| Regel | Wat het betekent | Waarom relevant |
|---|---|---|
| **Soft delete** | Verwijderen markeert alleen ("deleted_at"), de data blijft staan. | Niets gaat echt verloren — belangrijk voor zorgdossiers en herstel. |
| **Shift-logica** | Notities vóór 07:00 horen bij de dienst van de vórige dag. | Zorgt dat nachtdiensten correct in de overdracht vallen. |
| **Overdrachtsfilter** | Alleen notities met "meenemen in overdracht" verschijnen in de samenvatting. | De zorgverlener bepaalt wat relevant is voor de collega. |
| **Row Level Security (RLS)** | De database dwingt af wie welke gegevens mag zien. | Privacy/AVG-fundament. *Let op: in deze prototypefase nog ruim ingesteld — verfijning per team/organisatie staat nog open.* |
| **AI-herkomst** | Bij AI-gegenereerde inhoud wordt zekerheid en redenering bewaard. | Transparantie/controleerbaarheid van AI-output. |

---

## 8. Aandachtspunten & status (eerlijk beeld)

- **Prototype-status:** Dit is een prototype, geen productiesysteem. De beveiligingsregels (RLS) zijn nog ruim; verfijning per team/organisatie is nog niet gebouwd.
- **Twee-sporen datamodel:** Er bestaat nog een oudere ("clients/treatment_plans") naast de nieuwe FHIR-structuur ("patients/care_plans"). Het nieuwe spoor is leidend; het oude is nog niet volledig opgeruimd. Dit is technische schuld om in de gaten te houden.
- **Externe AI-kosten:** Schaalbaarheid van Cortex/AI hangt samen met gebruikskosten van Claude en Deepgram.
- **Geen echte interoperabiliteit (nog):** Het model is FHIR-*geïnspireerd*; volledige FHIR-uitwisseling met externe systemen is nog niet geïmplementeerd.

---

*Bronnen: codebase mini-epd-prototype (modules in `app/`, logica in `app/api/`, Cortex in `lib/cortex/`, datamodel in `supabase/migrations/`).*