feat(gui): NiceGUI-webapp als lokale interface voor de volledige pipeline

[Muhammet369]

Doel

Bouw een lokale webinterface bovenop de bestaande CLI zodat data-analisten de studentprognose-pipeline kunnen bedienen zonder terminal-kennis. De GUI omhult de CLI volledig — geen duplicatie van logica, alleen een schil die argumenten samenstelt en subprocessen aanstuurt.

Aanleiding

De pipeline heeft ~40 configuratieparameters verspreid over twee JSON-bestanden, meerdere inputbestanden en drie uitvoercommando's (standaard, benchmark, tune). Nieuwe gebruikers lopen vast op het instellen van paden, het begrijpen van weeknummer-ranges en het interpreteren van Excel-output. Een GUI verlaagt de drempel zonder de CLI-workflow te breken.

Gekozen framework: NiceGUI

Criterium	Reden
Pure Python	Past in bestaande uv-workflow, geen JS-kennis nodig
Lokale bestandskiezer	Vereist voor input-bestanden en configuratie-JSON
Live stdout streaming	Pipeline-runs duren minuten; voortgang moet zichtbaar zijn
Plotly-integratie	Bestaande HTML-dashboards direct inlaadbaar via ui.html
Distributie	uv run --extra gui python gui/app.py — één commando

Architectuur

gui/
├── app.py              # NiceGUI entry point + routing
├── pages/
│   ├── wizard.py       # Init-wizard (stap 1: nieuw project)
│   ├── run.py          # Pipeline-runner (stap 2: uitvoeren)
│   ├── config.py       # Configuratie-editor (stap 3: instellen)
│   ├── output.py       # Resultatenpagina (stap 4: resultaten)
│   └── benchmark.py    # Benchmark & tune tab
└── components/
    ├── file_picker.py  # Herbruikbare bestandskiezer
    ├── log_stream.py   # Live stdout → ui.log component
    └── param_form.py   # Dynamisch formulier uit config-schema

De GUI roept subprocess.Popen aan op de bestaande studentprognose-CLI. Geen import van interne modules — de CLI is het contract.

Gebruikersflow

[1: Init] → [2: Configuratie] → [3: Filteren] → [4: Uitvoeren] → [5: Resultaten]

Nieuwe gebruikers volgen de wizard lineair. Terugkerende gebruikers navigeren vrij via de zijbalk.

Branch-strategie

Al het GUI-werk verzamelt zich op feat/gui — niet op main. Pas als de volledige GUI werkend en getest is, gaat feat/gui → main in één PR.

main
 └── feat/gui                        ← integratiebranch (deze epic)
      ├── feat/gui-265-setup          → PR naar feat/gui
      ├── feat/gui-272-ux-design      → PR naar feat/gui
      ├── feat/gui-266-init-wizard    → PR naar feat/gui
      ├── feat/gui-267-config-editor  → PR naar feat/gui
      ├── feat/gui-271-filtering      → PR naar feat/gui
      ├── feat/gui-268-runner         → PR naar feat/gui
      ├── feat/gui-269-resultaten     → PR naar feat/gui
      └── feat/gui-270-benchmark      → PR naar feat/gui

Conventie per sub-issue:

• Branch aftakken van: feat/gui
• Branch naam: feat/gui-{issuenr}-{korte-naam}
• PR base: feat/gui (niet main)

Sub-issues

Fundament (eerst)

• feat(gui): projectsetup — NiceGUI dependency, mapstructuur, launchscript #265 Projectsetup — NiceGUI dependency, mapstructuur, launchscript
• feat(gui): UX-design — design system, navigatieflow en component-stijlen #272 UX-design — design system, navigatieflow en component-stijlen (referentie voor alle andere issues)

Wizard-stappen

• feat(gui): init-wizard — studentprognose init via stappenplan #266 Init-wizard — studentprognose init via stappenplan
• feat(gui): configuratie-editor — alle parameters uit configuration.json bewerkbaar #267 Configuratie-editor — alle parameters uit configuration.json bewerkbaar
• feat(gui): filtering-editor — filtering JSON bewerken met live preview #271 Filtering-editor — filtering JSON bewerken met live preview

Uitvoeren & resultaten

• feat(gui): pipeline-runner — CLI aanroepen met live log-streaming #268 Pipeline-runner — CLI aanroepen met live log-streaming
• feat(gui): resultatenoverzicht — gelikte samenvatting na pipeline-run #269 Resultatenoverzicht — gelikte samenvatting na pipeline-run

Geavanceerd (later)

• feat(gui): benchmark & tune tab — commando's uitvoeren met resultaatweergave #270 Benchmark & tune tab — commando's uitvoeren met resultaatweergave

Later toegevoegd

• feat(gui): één-klik demo — auto-run met demodata vanaf de startpagina #274 Één-klik demo — auto-run met demodata vanaf de startpagina
• feat(gui): deel-knop op het resultatenoverzicht (dummy) #275 Deel-knop op het resultatenoverzicht (dummy)
• feat(gui): interface stylen volgens CEDA/Npuls-huisstijl #276 Interface stylen volgens CEDA/Npuls-huisstijl

Afronden

Wanneer alle sub-issues afgevinkt zijn en de GUI lokaal end-to-end werkt:

1. feat/gui rebasen op de nieuwste main
2. PR aanmaken: feat/gui → main
3. Smoke test draaien via de GUI (niet alleen CLI)
4. Milestone GUI v1 sluiten

Buiten scope

• Eigen modellogica in de GUI (pipeline blijft in CLI)
• Hosting / multi-user server (lokaal gebruik, één sessie)
• Authenticatie
• Migratie van bestaande CLI-gebruikers (GUI is additioneel)