docs: add architecture and intake intent documentation

- Add architecture overview, implementation plan, and intent overview - Add intake intent process specs (gap analyse, bouwplan, testplan) - Add swift architecture specs and visualization prompts - Remove obsolete aispeedrun-manifesto template Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-04 19:26:14 +01:00
parent 91b61d215b
commit af88ac9446
18 changed files with 6905 additions and 756 deletions
--- a/docs/architectuur/architectuur-overzicht.md
+++ b/docs/architectuur/architectuur-overzicht.md
@@ -0,0 +1,296 @@
+# 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.*