Clone
1
Architectuurvoorstel
vps1_gitea_admin edited this page 2026-03-31 15:48:38 +00:00
Table of Contents
- Architectuurvoorstel
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
- AI API-keuze — Claude, OpenAI, of een lokaal model? Afhankelijk van netwerktoegang en beleid
- SSO/LDAP — Moet er integratie zijn met een bestaande identity provider?
- Monitoring — Welke monitoring-tooling is beschikbaar of gewenst?
- Backup-strategie — Hoe wordt de database gebackupt?
- CI/CD — Is er een bestaande pipeline of moet dit worden opgezet?
- 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