From b58f1febc31ed2514533c1d4de1dfd9618da84fa Mon Sep 17 00:00:00 2001 From: vps1_gitea_admin Date: Tue, 31 Mar 2026 15:48:38 +0000 Subject: [PATCH] Add "Architectuurvoorstel" --- Architectuurvoorstel.md | 240 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 Architectuurvoorstel.md diff --git a/Architectuurvoorstel.md b/Architectuurvoorstel.md new file mode 100644 index 0000000..2f2bcd2 --- /dev/null +++ b/Architectuurvoorstel.md @@ -0,0 +1,240 @@ +# Architectuurvoorstel + +## 1. Systeemoverzicht + +``` +┌─────────────────────────────────────────────────────────────┐ +│ BROWSER │ +│ Vue 3 + Vite SPA │ +└──────────────────────┬──────────────────────────────────────┘ + │ HTTPS / REST + WebSocket + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ LARAVEL APPLICATIE │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │ +│ │ API │ │ Auth & │ │ Domein- │ │ Event / │ │ +│ │ Routes │ │ Autoris. │ │ Services │ │ Queue │ │ +│ └──────────┘ └──────────┘ └──────────┘ └───────┬───────┘ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ +│ │ Eloquent │ │ File │ │ AI │ │ │ +│ │ Models │ │ Storage │ │ Gateway │◀────────┘ │ +│ └────┬─────┘ └──────────┘ └────┬─────┘ │ +└───────┼─────────────────────────┼───────────────────────────┘ + │ │ + ▼ ▼ +┌──────────────┐ ┌──────────────────┐ +│ PostgreSQL │ │ PYTHON AI-SERVICE │ +│ + pgvector │ │ ┌──────────────┐ │ +│ │ │ │ LangGraph / │ │ +│ - Domeindata │ │ │ Orchestrator │ │ +│ - Embeddings │ │ ├──────────────┤ │ +│ - Audit log │ │ │ RAG Pipeline │ │ +│ │ │ ├──────────────┤ │ +└──────────────┘ │ │ Agent Skills │ │ + │ └──────────────┘ │ + └──────────────────┘ +``` + +--- + +## 2. Componentbeschrijving + +### 2.1 Frontend: Vue 3 + Vite + +**Keuze:** Vue 3 met Composition API, gebouwd met Vite + +**Motivatie:** +- Reactieve, snelle UI voor complexe dashboards en formulieren +- Composition API biedt goede code-organisatie voor grotere applicaties +- Vite geeft snelle ontwikkelervaring (HMR) en geoptimaliseerde builds +- Groot ecosysteem met UI-componentbibliotheken + +**Belangrijke libraries (voorstel):** +- **Inertia.js** — bridging tussen Laravel en Vue zonder aparte API voor pageloads +- **Pinia** — state management +- **VueUse** — utility composables +- **UI-framework** — nader te bepalen na designinterview (kandidaten: PrimeVue, Naive UI, custom met Tailwind) + +**Alternatief overwogen:** Livewire +- Voordeel: minder frontend-complexiteit +- Nadeel: minder geschikt voor rijke interactieve interfaces (dashboards, drag-and-drop, real-time updates) +- Conclusie: Vue is beter passend bij de ambitie van dit platform + +### 2.2 Backend: Laravel + +**Keuze:** Laravel (huidige LTS of latest stable) + +**Verantwoordelijkheden:** +- Domeinlogica en business rules +- Autorisatie (policies, gates) +- Workflow- en statusovergangen +- API-endpoints (REST) +- Event-driven processing (queues, jobs) +- File storage en documentbeheer +- Gateway naar AI-service + +**Architectuurprincipes:** +- **Service-oriented** — domeinlogica in service classes, niet in controllers +- **Event-driven** — statusovergangen en acties via events +- **API-first** — alle functionaliteit beschikbaar via API +- **Audit trail** — alle mutaties worden gelogd + +### 2.3 Database: PostgreSQL + pgvector + +**Keuze:** PostgreSQL met pgvector-extensie + +**Motivatie:** +- Robuuste, bewezen relationele database +- pgvector maakt vectoropslag en -zoeken mogelijk zonder apart systeem +- Uitstekende JSON-ondersteuning voor flexibele velden +- Full-text search ingebouwd +- Goede Laravel-ondersteuning + +**Structuur:** +- Domeinmodel → relationele tabellen +- Embeddings → pgvector kolommen op documenten en kennisartikelen +- Audit log → append-only tabel met JSON-payload +- Sessie/cache → Redis (optioneel, bij performance-behoefte) + +### 2.4 AI-service: Python + +**Keuze:** Aparte Python-service voor AI-logica + +**Motivatie:** +- Python is het sterkste ecosysteem voor AI/ML +- Scheiding van concerns: Laravel hoeft geen AI-complexiteit te bevatten +- Onafhankelijk schaalbaar +- LangGraph en vergelijkbare frameworks zijn Python-native + +**Communicatie met Laravel:** +- REST API voor synchrone requests (chat, samenvatting) +- Message queue voor asynchrone taken (embedding-generatie, analyse) +- Gedeelde database-toegang voor retrieval + +**Componenten:** +- **Orchestrator** — coördineert agentische workflows (LangGraph) +- **RAG Pipeline** — retrieval-augmented generation over projectdata +- **Agent Skills** — gespecialiseerde tools per domein +- **Embedding Service** — genereert en beheert vectorembeddings + +--- + +## 3. Integratieprincipes + +### API-first + +``` +Frontend ──REST/JSON──▶ Laravel API ──REST──▶ AI-service + │ + ▼ + PostgreSQL +``` + +- Alle functionaliteit is API-first +- Frontend communiceert via Inertia.js (server-side routing) + API-calls voor async operaties +- AI-service heeft een eigen REST API, aangeroepen door Laravel +- Geen directe database-toegang vanuit de frontend + +### Event-driven communicatie + +``` +Statusovergang ──▶ Event ──▶ Queue ──▶ Listeners + ├── Notificatie versturen + ├── Audit log schrijven + ├── Embedding updaten + └── AI-analyse triggeren +``` + +### Autorisatie + +- Laravel Policies voor resource-level autorisatie +- RBAC (Role-Based Access Control) als basis +- Projectrol-gebaseerde permissies als uitbreiding +- API tokens voor service-to-service communicatie + +--- + +## 4. Hostingrichting + +### Voorstel: Intern gehost (on-premise of private cloud) + +**Motivatie:** +- Gevoelige organisatiedata +- Controle over data-locatie +- Waterschapscontext vraagt om beheersbaarheid + +**Minimale infrastructuur:** + +| Component | Specificatie | +|-----------|-------------| +| Applicatieserver | Linux, 4+ cores, 8+ GB RAM | +| Database | PostgreSQL 16+ met pgvector | +| AI-service | Python runtime, eventueel GPU voor lokale modellen | +| Reverse proxy | Nginx of Caddy | +| Queue worker | Laravel Horizon (Redis) | +| Storage | Lokaal of S3-compatible (MinIO) | + +### Containerisatie (aanbevolen) + +``` +docker-compose: + - nginx (reverse proxy) + - laravel-app (PHP-FPM) + - laravel-worker (queue) + - laravel-scheduler (cron) + - vue-app (build artifact, served by nginx) + - ai-service (Python) + - postgresql (+ pgvector) + - redis (cache + queue) +``` + +--- + +## 5. Technische beslissingen en alternatieven + +| Beslissing | Keuze | Alternatief | Motivatie | +|------------|-------|-------------|----------| +| Backend framework | Laravel | Symfony, Django | Laravel biedt de beste balans van productiviteit en structuur voor dit type applicatie | +| Frontend framework | Vue 3 | React, Svelte | Goede integratie met Laravel-ecosysteem (Inertia, Vite), reactief | +| Frontend bridging | Inertia.js | Puur SPA met API | Inertia combineert server-side routing met SPA-ervaring, minder boilerplate | +| Database | PostgreSQL | MySQL | pgvector, betere JSON-support, robuuster voor complexe queries | +| AI orchestratie | LangGraph | LangChain, custom | Grafische workflow-definitie, goed voor complexe agent-flows | +| AI API | Claude API | OpenAI, lokaal | Te bepalen op basis van beschikbaarheid en kwaliteit | +| Queue | Redis + Horizon | Database queue | Betrouwbaarder, monitoring via Horizon | +| Search | pgvector + FTS | Elasticsearch, Meilisearch | Minder operationele complexiteit, voldoende voor MVP | + +--- + +## 6. Beveiligingsbasis + +- HTTPS verplicht +- CSRF-protectie (Laravel standaard) +- Input validatie op alle endpoints +- Prepared statements (Eloquent standaard) +- Rate limiting op API-endpoints +- Audit logging van alle mutaties +- Rolgebaseerde toegangscontrole +- Versleutelde opslag van gevoelige configuratie +- Content Security Policy headers +- Geen gevoelige data in logs + +--- + +## 7. Open architectuurvragen + +1. **AI API-keuze** — Claude, OpenAI, of een lokaal model? Afhankelijk van netwerktoegang en beleid +2. **SSO/LDAP** — Moet er integratie zijn met een bestaande identity provider? +3. **Monitoring** — Welke monitoring-tooling is beschikbaar of gewenst? +4. **Backup-strategie** — Hoe wordt de database gebackupt? +5. **CI/CD** — Is er een bestaande pipeline of moet dit worden opgezet? +6. **Schaalbaarheid** — Is horizontale schaling een vereiste, of volstaat verticaal? + +--- + +## 8. Aannames + +- Er is een Linux-server beschikbaar voor hosting +- Docker is beschikbaar of kan worden geïnstalleerd +- Er is netwerktoegang tot een AI API (Claude of OpenAI) +- PostgreSQL 16+ kan worden geïnstalleerd met pgvector +- Er is geen bestaande SSO die direct moet worden geïntegreerd in de MVP