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:

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.