innovatieplatform/wiki/architecture/system-architecture.md

title, created, updated, status, tags, sources

title	created	updated	status	tags	sources
System Architecture	2026-04-08	2026-04-08	evolving	architecture stack docker layers	docker-compose.yml composer.json package.json ai-service/app/main.py

System Architecture

Stack

Layer	Technology	Version
Backend	Laravel (PHP)	13.0 / PHP 8.3+
Frontend	Vue 3 + Inertia.js	Vue 3.5, Inertia 3
Build	Vite	8.0
Styling	Tailwind CSS	4.2
Visualization	D3.js	7.9
Database	PostgreSQL + pgvector	16
Cache / Queue	Redis	alpine
AI Service	Python FastAPI	0.1.0
Auth	Laravel Fortify + Sanctum	Fortify 1.36, Sanctum 4.0
Fonts	VT323, Press Start 2P, IBM Plex Mono	—

Architecture Principles

1. Service-oriented — domain logic lives in service classes (app/Services/), not controllers
2. Event-driven — status transitions go through transactional methods with audit logging
3. API-first — all functionality reachable via REST endpoints
4. Audit trail — all mutations logged to audit_logs table (append-only)
5. AI content labeled — AI-generated content marked and requires human confirmation
6. Inertia SPA — server-side routing (Laravel) with client-side rendering (Vue 3), no separate API layer needed for pages

Docker Topology

┌─────────────────────────────────────────────────────────┐
│  nginx:alpine  ─────────────────────────────→  :80      │
│      │                                                   │
│      ▼                                                   │
│  laravel-app (PHP 8.4-FPM)                              │
│      │                                                   │
│      ├── laravel-worker (queue:work)                     │
│      ├── laravel-scheduler (cron)                        │
│      │                                                   │
│  ┌───▼────────────┐    ┌─────────────────┐              │
│  │ postgresql:16   │    │  redis:alpine   │              │
│  │ + pgvector      │    │  cache/queue    │              │
│  │        :5432    │    │       :6379     │              │
│  └─────────────────┘    └─────────────────┘              │
│                                                          │
│  ai-service (Python FastAPI)  ──────────────→  :8000     │
│      └── connects to postgresql for embeddings           │
└─────────────────────────────────────────────────────────┘

7 services total. All on innovatieplatform bridge network.

Data Flow

Page Rendering (Inertia)

Browser → nginx → PHP-FPM → Laravel Router → Controller
    → Service (business logic)
    → Inertia::render('Page', $data)
    → Vue component receives props
    → D3.js renders metro map canvas

API Calls (Map data)

Vue component → axios GET /api/map/strategy
    → MapController::apiStrategy()
    → MapDataService::getStrategyMap()
    → Eloquent queries (Thema → Speerpunten → Projects)
    → JSON response {lines, nodes, connections, level}
    → D3 re-renders canvas

AI Integration (planned)

CliBar.vue → POST /api/chat
    → Laravel proxy → ai-service:8000/api/chat
    → LangGraph agent → Anthropic Claude
    → RAG: pgvector similarity search on documents
    → Response with source attribution
    → CliBar displays with [AI] prefix

Key Service Classes

Service	LOC	Responsibility
ProjectService	186	Project CRUD, lifecycle transitions, park/stop, audit logging
MapDataService	165	Build metro map data structures (Level 1: strategy, Level 2: project)
ThemaService	60	Theme CRUD operations

Configuration

• Session/Cache/Queue: All Redis-backed (config/session.php, config/cache.php, config/queue.php)
• Database: PostgreSQL with pgvector extension for embedding vectors
• Auth: Fortify handles registration/login/password flows, Sanctum for API tokens
• OPcache: Production-optimized (docker/php/opcache.ini)
• Gzip: Enabled in nginx config