Add "Architectuurvoorstel"
240
Architectuurvoorstel.md
Normal file
240
Architectuurvoorstel.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user