geointel/docs/PROJECT_PROFESSIONALIZATION_AUDIT_2026-07-27.md

# GeoIntel professionaliseringsaudit — 27 juli 2026

## Managementsamenvatting

GeoIntel is inhoudelijk veel sterker dan de eerste visuele indruk deed
vermoeden. De repository bevat een volwassen, documentatiegestuurde
GIS-architectuur, expliciete bron- en provenancecontracten, uitgebreide
kwaliteitscontrole en een product dat bewust geen resultaten fabriceert wanneer
brondata of modellen ontbreken. De grootste productrisico's zaten niet in de
GIS-kern, maar in de toegangservaring, de presentatie van de functiedichtheid
en de gegroeide frontend-stijllagen.

Deze pass professionaliseert de eerste gebruikerservaring en voegt een veilige
gastdemonstratie toe. Een bezoeker kan nu rechtstreeks vanaf de landingspagina
een tijdelijke demowerkruimte openen. Die sessie is server-side aan één
voorbeeldproject gebonden, heeft een kortere levensduur en kan geen
operatorwijzigingen uitvoeren. De interface toont in gastmodus alleen de kaart
en bestaand kwaliteitsbewijs.

## Wat al sterk was

- **Inhoudelijke geloofwaardigheid.** Officiële bronnen, meeteenheden, CRS,
  dekking, beperkingen en provenance worden als productgegevens behandeld en
  niet als decoratieve metadata.
- **Fail-closed gedrag.** Niet-geconfigureerde bronnen en modellen worden niet
  stilzwijgend vervangen door fixtures of gesimuleerd succes.
- **Map-first productmodel.** Project, gebied, dataset, analyse en QA delen een
  ruimtelijke context, wat veel sterker is dan een verzameling losse dashboards.
- **Operationele discipline.** De repository bevat releasegates, Unraid-assets,
  migraties, herstelpaden, tests en expliciete scope-/beperkingsdocumentatie.
- **Bestaande demofundering.** Het idempotente demoworkflowcontract maakte een
  gecontroleerde gastbeleving mogelijk zonder een tweede fictieve applicatie te
  bouwen.

## Belangrijkste bevindingen

### P0 — Er ontbrak een toegankelijke productdemo

De oorspronkelijke ingang bood alleen een operatorlogin. Voor een recruiter,
stakeholder of eerste beoordelaar was daardoor niet zichtbaar wat het platform
kan zonder vooraf accounts of wachtwoorden uit te wisselen. Een onbegrensde
“login zonder wachtwoord” zou echter toegang tot operationele functies hebben
gegeven.

**Oplossing:** een config-gated `POST /api/v1/auth/guest`, een gesigneerde
gastrol met projectscope, server-side mutatieblokkering en een expliciete knop
**Als gast verkennen**. De demo wordt bij openen idempotent voorbereid.

### P1 — De landingspagina communiceerde de productwaarde onvoldoende snel

De informatie was aanwezig, maar de primaire actie, productbelofte,
betrouwbaarheidssignalen en demonstratiemogelijkheid concurreerden visueel met
elkaar. Op kleinere schermen voelde de ingang langer en minder doelgericht.

**Oplossing:** nieuwe hero- en loginhiërarchie, heldere keuze tussen operator en
gast, compactere capability-sectie, concreter vierstappenproces, betere mobiele
navigatie en begrijpelijke foutmeldingen in plaats van ruwe servicefouten.

### P1 — De workbench was voor een gast te breed en te technisch

De volledige operatornavigatie bevat projectbeheer, imports, AI-taken, exports
en geavanceerde analyses. Dat is gepast voor een beheerder, maar werkt tegen een
snelle demonstratie.

**Oplossing:** de gastrol ziet alleen **Kaart** en **Kwaliteit**, krijgt een
blijvende alleen-lezen contextbanner en ziet geen creatie-, import-, export-,
AI- of beheeracties. De backend blijft de autoritatieve grens.

### P1 — De visuele laag is historisch gegroeid

Vier opeenvolgende workbench-stijlbestanden bevatten samen 13.818 regels CSS:
`app.css`, `premium.css`, `atlas-workbench.css` en `atlas-premium-v2.css`. Over
de volledige actieve stijllaag zijn tientallen mediaqueries aanwezig. Dat
verhoogt de kans op cascadeconflicten, onverwachte responsive afwijkingen en
onnodig moeilijke toekomstige aanpassingen.

**Oplossing in deze pass:** een kleine, als laatste geladen
`professionalization.css` met gerichte correcties voor navigatierail, contextbalk,
werkruimtehoogte, gaststatus, truncation en responsive gedrag. De historische
lagen zijn bewust niet massaal herschreven zonder volledige visuele
regressiebaseline.

**Aanbevolen vervolgstap:** component voor component consolideren naar tokens,
layout primitives en één stylesheet per functioneel domein, telkens beschermd
door desktop-, ultrawide- en mobiele screenshots.

### P2 — Twee frontendcomponenten dragen te veel verantwoordelijkheid

`App.tsx` telt circa 1.400 regels en `MapWorkspace.tsx` circa 3.900 regels. Dat
is nog werkbaar, maar maakt layout-, permissie- en interactiewijzigingen
risicovoller dan nodig.

**Aanbevolen vervolgstap:** splits shell/navigatie, workspace-routing,
gastsessiecontext, kaartselectie, bronresolutie en analysepresentatie in
afzonderlijke domeincomponenten en hooks. Doe dit pas na de huidige
regressietests, zodat gedrag niet tegelijk met structuur wordt gewijzigd.

### P2 — Gastmodus is geen tenantisolatie

De sessie is cryptografisch gesigneerd, kort geldig, projectgebonden en
alleen-lezen. Toch blijft GeoIntel architecturaal een single-operatorproduct. De
gastrol is bedoeld voor een aparte demo-installatie, niet om operationele en
publieke gebruikers veilig in dezelfde datastore te mengen.

## Geleverde wijzigingen

| Domein | Professionalisering |
|---|---|
| Toegang | Nieuwe gastactie, wachtwoordzichtbaarheid, heldere operator/gastkeuze en bruikbare foutmeldingen |
| Sessies | Versie 2-sessietoken met expliciete `operator`/`guest`-rol, TTL en optionele projectscope |
| Backendgrens | Positieve read-allowlist, gastprojectfilter, cross-projectblokkering en mutatieblokkering met stabiele foutcodes |
| Demo | Canonieke demoworkflow wordt idempotent voorbereid bij gastlogin |
| Workbench | Gereduceerde gastnavigatie, alleen-lezen statusbanner en verborgen beheerfuncties |
| Kaart | Alleen-lezen variant zonder on-demand acquisitie of geavanceerde operatorcontrole |
| Layout | Rustigere desktop-shell, betere truncation, responsieve gaststatus en reduced-motion ondersteuning |
| Deployment | Gastvariabelen in Compose, Unraid-env, DockerMan-template en runtimevalidatie |
| Documentatie | API-contract, README, Unraid-instructies, beperkingen, TODO en uitvoeringslog bijgewerkt |

## Configuratie

Gasttoegang staat standaard ingeschakeld zodra de operator-login actief is.
Voor een afzonderlijke demo-installatie:

```env
GEOINTEL_AUTH_ENABLED=true
GEOINTEL_AUTH_USERNAME=operator
GEOINTEL_AUTH_PASSWORD_HASH=pbkdf2_sha256$...
GEOINTEL_AUTH_SESSION_SECRET=<minstens-32-willekeurige-tekens>
GEOINTEL_GUEST_ACCESS_ENABLED=true
GEOINTEL_GUEST_DISPLAY_NAME=Gast
GEOINTEL_GUEST_SESSION_TTL_SECONDS=7200
```

Zet `GEOINTEL_GUEST_ACCESS_ENABLED=false` om gasttoegang expliciet uit te schakelen.
Gebruik een afzonderlijke container, database en storage-root wanneer de demo
van buiten het vertrouwde LAN bereikbaar wordt. Plaats geen private, klant- of
operationele datasets in die omgeving.

## Validatie

De volgende controles zijn op 27 juli 2026 uitgevoerd:

| Controle | Resultaat |
|---|---|
| Gerichte backend auth-/gastbeveiligingstests | **Geslaagd — 6/6** |
| Python compile van `backend/app` en de nieuwe authtests | **Geslaagd** |
| Volledige frontend TypeScript-typecheck | **Geslaagd** |
| Gerichte frontend-interactiesmokes: gast/operator-login en beperkte bootstrap | **Geslaagd — 2/2** |
| CSS-syntax van de vernieuwde landing en professionaliseringslaag | **Geslaagd** |
| Compose YAML, Unraid XML en DockerMan-shellsyntax | **Geslaagd** |
| Whitespacecontrole op alle in deze pass gewijzigde bestanden | **Geslaagd** |

De gerichte backendtests draaiden met SQLite en een tijdelijke minimale
`geoalchemy2`-importstub buiten de repository, omdat de reviewcontainer de
PostGIS-runtimepackages niet bevatte. Daarmee zijn tokenvalidatie, cookies,
login/logout, gastscope, cross-projectblokkering en route-/mutatieblokkering
wel rechtstreeks getest; het is geen vervanging voor de bestaande volledige
PostgreSQL/PostGIS-integratiegate.

De nieuwe logincomponent en de beperkte workbench-bootstrap zijn aanvullend
rechtstreeks in JSDOM uitgevoerd via een tijdelijke TypeScript-loader buiten de
repository. Daarmee zijn de zichtbaarheid van gastacties, de `POST` naar de
gastendpoint, de operatorlogin en het uitschakelen van operator-only
bootstrapcalls interactief gecontroleerd.

De aangeleverde `node_modules` bevat alleen Windows-native Rollup- en
esbuildpakketten. Daardoor konden de normale Vitest-runner en de
Vite-productiebundel in deze Linux-reviewcontainer niet starten. Een schone
dependency-installatie was niet mogelijk doordat de beschikbare packageproxy
tijdens de controle 503-responses en time-outs gaf. De TypeScript-compiler voltooide wel zonder fouten. De
frontend-unit- en productiebuildgates moeten daarom na `npm ci` op Windows of
in de normale Linux CI-/Dockeromgeving nogmaals worden uitgevoerd.

## Aanbevolen roadmap

1. Leg visuele regressiesnapshots vast voor login, kaart, kwaliteit en alle
   primaire workspaces op mobiel, desktop en ultrawide.
2. Consolideer de vier historische workbench-CSS-lagen incrementeel; verwijder
   pas selectors nadat screenshots en interactietests gelijkwaardig zijn.
3. Splits `App.tsx` en `MapWorkspace.tsx` langs domeingrenzen, zonder API- of
   analysegedrag te wijzigen.
4. Voeg een expliciete demo-reset/refreshstrategie en misbruiktelemetrie toe
   wanneer de demo publiek wordt blootgesteld.
5. Bouw alleen bij echte multi-userbehoefte een afzonderlijk identiteits-,
   autorisatie- en tenantmodel; breid gastmodus daar niet ad hoc voor uit.