Type 4: Integration Repository - Architectuur verkenning

[CorneeldH]

Problem / Opportunity

CEDA heeft meerdere zelfstandige R- en Python-packages (eencijfer, instroomprognose, verrijking, kansengelijkheid) die elk hun eigen simpele UI hebben (Shiny/Streamlit). Wat ontbreekt is een integratie-laag: een unified app waar beheerders pipelines kunnen triggeren (inclusief lang lopende ML-taken) en eindgebruikers resultaten uit meerdere repos in een dashboard kunnen zien.

In standards/project-structure.md staat Type 4 (Integration/Dashboard Repository) als "future, needs exploration". Dit issue documenteert de architectuurverkenning.

Appetite (timebox)

Large (5-6 dagen) voor eerste prototype/validatie. De volledige uitbouw is een doorlopend project.

Solution

API-first architectuur met verwisselbare frontend:

• Backend: FastAPI (Python) - alle logica, job orchestratie, data serving
• Frontend fase 1: NiceGUI - pure Python, snel starten, intern gebruik (<50 users)
• Frontend fase 2: React/Next.js via vibe-coding (v0, Cursor) - visuele kwaliteit, schaalbaarheid
• Integratie: Python packages direct importeren, R packages via subprocess
• Job tracking: SQLite + asyncio (geen Redis/Celery bij 1-3 concurrent jobs)
• Data: Polars leest Parquet uit pipeline output directories

Kritische voorwaarde: strikte scheiding backend/frontend. NiceGUI als "domme client" die alleen API-calls doet, zodat de frontend later vervangbaar is.

Risks / Rabbit holes

• NiceGUI is relatief nieuw (~2022) - moet gevalideerd worden met een spike
• R runtime in Docker container (fat container vs sidecar)
• Package interface contract: downstream packages moeten een consistente run_pipeline() interface bieden
• SURF Developer Platform deployment details nog onbekend

No-Gos

• Geen Celery/Redis - overkill voor deze schaal
• Geen rpy2 voor R-integratie - subprocess is robuuster
• Geen monolithische frontend die niet vervangbaar is
• Geen business logica in de frontend-laag

Gevalideerd met

@corneeldenhartogh

Sparring partner

@corneeldenhartogh

[CorneeldH]

Type 4: Integration Repository - Verkenning

Context

CEDA heeft Type 1 (ingestion) en Type 2 (analyse) repos die elk zelfstandige packages zijn met een eigen simpele UI (Shiny/Streamlit). Wat ontbreekt is een integratie-laag: een app waar beheerders pipelines kunnen triggeren en eindgebruikers resultaten uit meerdere repos in een unified dashboard zien.

De standaard in standards/project-structure.md:20-22 zegt alleen: "This needs to be explored further."

Dit document verkent de architectuurkeuzes.

---

1. Integratiemethode: packages, geen repo-clones

Alle downstream repos zijn packages. De integratie-hub installeert ze als dependency:

• Python packages: uv add instroomprognose → from instroomprognose import run_pipeline
• R packages: aanroepen via subprocess: Rscript -e "eencijfer::run_pipeline()"

Dit betekent:

• Geen gedeeld bestandssysteem met geclonede repos nodig
• Python packages worden gewoon geimporteerd en aangeroepen
• R packages worden via CLI aangeroepen (rpy2 is fragiel en onnodig)
• Datalocatie wordt een expliciete configuratie - packages moeten weten waar ze lezen/schrijven

Data flow patroon

[config.toml]
  data_root = "/data/ceda"

[instroomprognose]
  input_dir = "${data_root}/1cho-output"    # Output van ingestion repo
  output_dir = "${data_root}/instroomprognose-output"

[eencijfer]
  input_dir = "${data_root}/raw/duo"
  output_dir = "${data_root}/1cho-output"

De hub kent de data-paden en geeft ze mee aan package-functies. Packages produceren Parquet in hun output_dir. De hub leest die Parquet files voor visualisatie.

Concrete pipeline-keten: 1CijferHO

Een realistisch voorbeeld van hoe meerdere packages samenwerken:

[1] eencijfer (R, ingestion)          → Ruwe DUO bestanden → schone Parquet
        ↓
[2] 1cho_verrijking (Python, analyse) → Afgeleide variabelen voor visualisatie/exploratie
        ↓
[3] kansengelijkheid (Python, analyse)→ Diagnostische analyse (equity)

Parallel daaraan:

[4] instroomprognose (Python, analyse)→ MBO instroomprognose (lang lopend)

De hub orkestreert deze keten:

• Stap 1 moet klaar zijn voordat 2 en 3 kunnen draaien
• Stap 2 en 3 kunnen parallel
• Stap 4 is onafhankelijk
• De hub toont resultaten van alle stappen in een unified dashboard

# config.toml - pipeline dependencies
[eencijfer]
type = "r"
command = "eencijfer::run_pipeline()"
output_dir = "${data_root}/1cho-output"
depends_on = []

[verrijking]
type = "python"
package = "cho_verrijking"
output_dir = "${data_root}/1cho-verrijkt"
depends_on = ["eencijfer"]

[kansengelijkheid]
type = "python"
package = "kansengelijkheid"
output_dir = "${data_root}/kansengelijkheid-output"
depends_on = ["verrijking"]

[instroomprognose]
type = "python"
package = "instroomprognose"
output_dir = "${data_root}/instroomprognose-output"
depends_on = []

---

2. UI Framework: waarom NIET Streamlit

Streamlit is prima voor simpele data-apps in individuele repos (Type 1/2), maar niet geschikt als integratie-hub omdat:

Probleem	Impact
Hele script herstart bij elke interactie	Kan geen achtergrondtaken monitoren
Geen echte state management	Job-status gaat verloren bij page refresh
Beperkte layout (vooral single-column)	Admin interface vereist complexere layouts
Geen ingebouwde authenticatie	Beheerders vs eindgebruikers niet te scheiden
Geen WebSocket/real-time updates	Geen live job-monitoring mogelijk

Alternatieven vergeleken

Framework	Type	Pro	Con	Team fit
FastAPI + NiceGUI	Python-native	Gebouwd op FastAPI, Python-only, goede layout controls, achtergrondtaken, real-time updates	Relatief nieuw (maar actief), kleiner ecosysteem	Hoog - pure Python, geen JS nodig
FastAPI + Jinja2 + htmx	Server-rendered HTML	Maximale flexibiliteit, geen build stap, robuust en bewezen	Vereist HTML/CSS kennis, charts apart (plotly HTML)	Medium - meer webdev kennis nodig
Shiny for Python	Reactive	Team kent Shiny uit R, goed voor dashboards	Nieuw in Python, beperkte community, minder geschikt voor admin/CRUD	Medium - bekend concept, onbekende Python implementatie
Dash (Plotly)	Callback-based	Uitstekend voor dashboards, Plotly-integratie	Callback-hell bij complexe apps, niet ideaal voor admin interfaces	Medium - goed voor charts, minder voor beheer
Django + htmx	Full web framework	Batteries-included (auth, admin, ORM, migrations), enorm ecosysteem, Django Admin gratis erbij voor beheer	Steile leercurve voor datawetenschappers, meer "webdev" dan "data science", templates/views/models paradigma	Laag-Medium - krachtig maar ver van data science workflow
Reflex	Full-stack Python	React onder de motorkap, moderne UI, Python-only	Zwaar framework, veel magie, relatief nieuw	Laag - te complex

Aanbeveling: FastAPI backend + NiceGUI frontend (met groeipad naar React)

Waarom NiceGUI boven de alternatieven:

• vs Streamlit: Kan geen achtergrondtaken, verliest state, geen auth. Geschikt voor Type 1/2 repos, niet voor een beheer-platform.
• vs Dash: Goed voor pure dashboards, maar callback-hell bij admin/CRUD. Geen native achtergrondtaken.
• vs Shiny for Python: Python-versie is jong, kleine community. Minder geschikt voor admin interfaces.
• vs Django + htmx: Meest volwassen optie (auth, admin panel, ORM gratis erbij). Maar het models/views/templates paradigma is ver van data science workflow. Goede keuze met een webdeveloper in het team; minder als het team puur data scientists is.
• vs FastAPI + Jinja2 + htmx: Lichter dan Django, maar vereist HTML/CSS kennis. htmx maakt HTML interactief via server-calls zonder JS te schrijven.
• vs Reflex: Te zwaar en magisch voor een klein team.

NiceGUI als startpunt omdat:

1. Pure Python - past bij datawetenschappers, laagste instapdrempel
2. Gebouwd op FastAPI - API-laag is er al
3. Real-time updates via WebSockets - job monitoring
4. Goede layout controls - tabs, cards, grids, dialogs

NiceGUI's beperking: WebSocket per gebruiker + server-side UI state. Prima voor <50 gelijktijdige gebruikers (intern gebruik). Wordt problematisch bij 500+. Visuele vrijheid is beperkt vergeleken met React.

Groeipad: NiceGUI nu → React/Next.js later

Fase 1 (nu):     FastAPI  ←→  REST/WebSocket API  ←→  NiceGUI
Fase 2 (later):  FastAPI  ←→  REST/WebSocket API  ←→  React/Next.js

Waarom dit werkt: vibe-coding tools (v0, Cursor, Lovable) maken React/Next.js haalbaar voor een Python-team. De frontend wordt grotendeels gegenereerd. React + Tailwind + shadcn/ui levert professionele dashboards op die er veel beter uitzien dan NiceGUI.

Wanneer overstappen: als visuele kwaliteit prioriteit wordt, je meer dan ~50 gelijktijdige gebruikers verwacht, of het dashboard complexer wordt dan NiceGUI comfortabel aankan.

Kritische voorwaarde: de overstap werkt alleen als NiceGUI zich gedraagt als een domme client:

GOED:  NiceGUI → HTTP request naar /api/jobs/ → toont resultaat
FOUT:  NiceGUI → roept direct Python functie aan → toont resultaat

Regels:

• Alle data en logica → FastAPI endpoints
• NiceGUI doet alleen: tonen + gebruikersinput doorsturen naar de API
• NiceGUI praat met FastAPI via httpx of fetch, niet door Python-functies direct aan te roepen
• Geen database-aanroepen vanuit NiceGUI
• Zo kan React later dezelfde API aanspreken zonder backend-wijzigingen

---

3. Architectuur

API-first: backend en frontend strikt gescheiden

┌─────────────────────────────────────────────────┐
│ FastAPI Backend (de kern)                        │
│                                                  │
│  /api/jobs/        → pipeline triggeren/status   │
│  /api/data/        → Parquet data ophalen        │
│  /api/pipelines/   → pipeline registry           │
│  /api/auth/        → authenticatie                │
│                                                  │
│  runner.py         → subprocess/import execution │
│  job_store.py      → SQLite job tracking         │
│  data_reader.py    → Polars Parquet reading      │
└──────────────────────┬──────────────────────────-┘
                       │ REST / WebSocket
          ┌────────────┴────────────┐
          │                         │
   ┌──────┴──────┐          ┌──────┴──────┐
   │  NiceGUI    │          │ React/Next  │
   │  (fase 1)   │          │ (fase 2)    │
   │  domme      │          │ vibe-coded  │
   │  client     │          │ via v0 etc  │
   └─────────────┘          └─────────────┘

Alle logica zit in de FastAPI backend. De frontend (NiceGUI of later React) is een presentatielaag die alleen API-calls doet.

Twee rollen

• Beheerders (/admin/): pipelines triggeren, jobs monitoren, logs bekijken
• Eindgebruikers (/dashboard/): grafieken, rapporten, data verkenner

Auth scheidt de twee via de API (role-based).

Job execution

Beheerder klikt "Start instroomprognose"
  → Frontend POST /api/jobs/ {pipeline: "instroomprognose"}
  → FastAPI maakt Job record in SQLite (status: running)
  → Start pipeline in achtergrondtaak:
      Python: instroomprognose.run_pipeline(config)
      R: subprocess Rscript -e "eencijfer::run_pipeline()"
  → Frontend pollt GET /api/jobs/{id} of luistert via WebSocket
  → Bij completion: update SQLite, frontend toont notificatie

SQLite voor job tracking (geen Redis/Celery):

• Max 1-3 concurrent jobs, team van 2-3 mensen
• SQLite met WAL mode is meer dan voldoende

API endpoints (kern)

POST   /api/jobs/                    → Start een pipeline
GET    /api/jobs/                    → Lijst van alle jobs
GET    /api/jobs/{id}                → Status van een job
GET    /api/jobs/{id}/logs           → Logs van een job
GET    /api/data/{pipeline}/datasets → Beschikbare output datasets
GET    /api/data/{pipeline}/{name}   → Data ophalen (JSON of Parquet)
GET    /api/pipelines/               → Pipeline registry
POST   /api/auth/login               → Login

---

4. Projectstructuur

ceda-hub/
├── .devcontainer/
│   └── devcontainer.json
├── src/
│   └── ceda_hub/                      # Package
│       ├── __init__.py
│       ├── config.py                  # TOML configuratie laden
│       ├── data_reader.py             # Lees Parquet van pipeline outputs
│       ├── job_store.py               # SQLite job tracking
│       ├── runner.py                  # Pipeline execution (Python import + R subprocess)
│       ├── pipelines/                 # Pipeline-specifieke wrappers
│       │   ├── __init__.py
│       │   ├── instroomprognose.py    # Wraps instroomprognose package
│       │   └── eencijfer.py           # Wraps eencijfer R package
│       ├── pages/                     # NiceGUI pagina's
│       │   ├── __init__.py
│       │   ├── dashboard.py           # Eindgebruiker: overzicht grafieken
│       │   ├── admin_pipelines.py     # Beheer: pipelines triggeren/monitoren
│       │   ├── admin_logs.py          # Beheer: logs bekijken
│       │   └── data_explorer.py       # Data verkenner (tabel + filter)
│       └── metadata/
│           └── __init__.py
├── app/
│   ├── main.py                        # NiceGUI entrypoint
│   └── config.toml                    # Pad configuratie
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml
├── db/                                # SQLite (gitignored)
├── tests/
├── pyproject.toml
├── CLAUDE.md
├── README.md
├── LICENSE
└── uv.lock

---

5. Open vragen voor later

1. NiceGUI validatie - Bouw een mini-prototype (1 pagina met een knop die een pipeline triggert + chart) om te valideren dat het framework past. Kost ~1 dag.
2. R runtime in Docker - Fat container (R+Python in 1 image) is simpelst voor start. Sidecar pattern alleen als dependency conflicts ontstaan.
3. Package versioning - Pin Python packages in pyproject.toml. R packages via pak met versie-pinning. Update-cyclus afstemmen op release-ritme van downstream repos.
4. SURF deployment - Persistent volumes voor data, Docker Compose voor services. Exacte SURF configuratie moet verkend worden.
5. Auth model - Start simpel (username/password), koppeling met instellings-SSO kan later.
6. Package interface contract - Downstream packages moeten een consistente interface bieden (bijv. run_pipeline(input_dir, output_dir) in Python, run_pipeline(input_dir, output_dir) als R functie). Dit moet als conventie in de standaard.

---

Samenvatting keuzes

Beslissing	Keuze	Reden
Backend	FastAPI (Python)	API-first, async, team kent Python
Frontend fase 1	NiceGUI	Pure Python, snel starten, intern gebruik
Frontend fase 2	React/Next.js (vibe-coded)	Visuele kwaliteit, schaalbaarheid, via v0/Cursor
Architectuur	API-first, strikte scheiding	Frontend vervangbaar, backend blijft
Integratie	Package imports + R subprocess	Downstream repos zijn packages
Job queue	SQLite + asyncio	Simpel, passend bij schaal (1-3 jobs)
Data format	Polars leest Parquet	CEDA standaard
Deployment	Docker Compose op SURF	Container runtime

[CorneeldH]

@Tomeriko96 @asewnandan @oinkspook

Hoi, dit kwam vandaang in de stand-up ter sprake. Dit is wat ik eerder hierover heb geschreven (input en bedenkingen zijn welkom).

Tegelijkertijd, dit is wmb niet iets om in komende sprints uit te werken. Ik denk dat we tot de zomer met de individuele repo's, scoop en 'data professional gebruikers' bezig zijn.

Dan kunnen we dat met key users testen en indien haalbaar nog voor de zomer een workshop. Vervolgens feedback verwerken en dan 'staat' dat.