geointel/RISKS.md

# RISKS.md

## Aanvulling 2026-07-22

- Open-Meteo is een externe, ongeauthenticeerde databron. DockDeck cachet tien minuten, gebruikt een korte timeout en laat alleen de weerbadge zonder actuele waarde bij uitval; navigatie, widgets en instellingen blijven volledig bruikbaar.
- Een wallpaper kan de leesbaarheid verminderen. DockDeck beperkt bestandstype en grootte, bewaart het bestand lokaal, gebruikt een rustige uniforme contrastlaag en maakt rails, widgets en tegels doorschijnende glasoppervlakken; de gebruiker kan de afbeelding direct verwijderen. Bij `Passend` vult een vervaagde kopie de ultrawide zijruimte, terwijl het scherpe hoofdbeeld volledig zichtbaar blijft.
- `Passend` behoudt de volledige afbeelding en kan bij een afwijkende beeldverhouding rustige zij- of bovenruimte tonen; `Vullend` benut het vlak volledig maar kan randen afsnijden. De preview, focusregelaars en begrensde zoom maken deze afweging expliciet zonder het originele bestand te bewerken.

Project: DockDeck
Updated: 2026-07-22

## Assumptions

- Eén lokale beheerder; geen accounts of multi-userrollen in de MVP.
- Docker- en Unraid-metadata zijn read-only en bereikbaar vanuit het afgeschermde Compose-netwerk.
- Nginx Proxy Manager is optioneel; een handmatige/lokale URL blijft altijd de fallback.
- SQLite is de persistente bron voor normale configuratie; providercredentials uit Settings staan afzonderlijk als environmentassignments in het named volume.

## Open risks

- Unraid WebUI-templatevelden verschillen per communitytemplate. De parser ondersteunt de gangbare `[IP]`, `[HOST]`, `[PORT]` en `[PORT:n]` vormen; onbekende vormen vragen een handmatige URL-override.
- Een container zonder WebUI of icoon gebruikt een nette fallback maar kan pas navigeren na een URL-override.
- Automatische NPM-matching accepteert alleen één ondubbelzinnige hostname; complexe namen blijven bewust handmatig.
- DockDeck heeft geen eigen authenticatie. De standaardbind is daarom `127.0.0.1`; een LAN-bind of reverse proxy vereist bewuste netwerktoegangscontrole.
- Credentialinvoer over de huidige LAN-HTTP-deployment is niet transportversleuteld. Gebruik dit scherm alleen op het vertrouwde LAN; zet voor toegang buiten dat segment een geauthenticeerde HTTPS-reverse proxy in.
- `/data/integrations.env` bevat plaintext providercredentials met bestandmodus `0600`. JSON-exports sluiten dit bestand uit, maar een ruwe volumeback-up bevat het wel en moet als secretmateriaal worden beschermd.
- De Unraid-host heeft zijn automatische Docker-address-pools opgebruikt. DockDeck gebruikt daarom twee expliciete, kleine subnetten (`172.31.240.0/28` en `172.31.240.16/28`); controleer deze opnieuw bij netwerkherconfiguratie.
- Unraid-templates kunnen secrets bevatten. De app krijgt uitsluitend een gegenereerde metadata-mirror met `Name`, `WebUI` en `Icon`; voer de sanitizer opnieuw uit nadat templates wijzigen.
- Niet iedere website publiceert een bruikbaar icoon op `/favicon.ico`; zulke favorieten en apps vallen terug op een lokaal merk- of semantisch service-icoon en kunnen in Settings nog steeds een expliciete icoon-URL krijgen.
- De standaard single-containerdeployment is voor discovery afhankelijk van de bestaande AppOps-gateway. Bij uitval blijven alle opgeslagen navigatie en instellingen bruikbaar en krijgt de integratie een degraded status; discovery hervat automatisch zodra AppOps terug is.
- AppOps levert actuele CPU- en geheugenwaarden, maar momenteel geen netwerkdoorvoer of PID-aantal. Native providers en GET-only metrics bridges blijven die app-specifieke lagen leveren; zonder zo'n koppeling toont DockDeck voor die velden een eerlijke unavailable-status.
- Provider-API's verschillen per versie en vereisen credentials met uiteenlopende scopes. DockDeck gebruikt alleen gedocumenteerde GET-routes en korte timeouts; zonder endpoint toont de kaart haar eigen capabilitylabels met een expliciete connectiestatus naast gescheiden echte Dockertelemetrie. Configureer waar mogelijk een afzonderlijke minimum-scope token en roteer die periodiek via Settings of de deploymentenvironment.
- Custom widgetendpoints zijn een expliciet lokaal vertrouwensbesluit: DockDeck doet alleen een GET met korte timeout, begrenst labels/waarden en echoot tokens niet, maar de gebruiker blijft verantwoordelijk voor een read-only endpoint en een minimum-scope token. Gebruik geen URL die bij een GET een mutatie veroorzaakt.
- App-specifieke profielen beschrijven mogelijke metriekvelden; eigen applicaties moeten het gedocumenteerde JSON-contract zelf aanbieden voordat deze waarden live worden. Zonder endpoint blijft de kaart volledig bruikbaar met read-only Dockertelemetrie.
- Grafiekhistoriek is bewust procesgeheugen: maximaal zestig samples per reeks, geen geheimen en geen langdurige opslag. Een containerrestart wist de trend zonder configuratie of navigatie te verliezen.
- Unraid cachet containericonen tweemaal onder een vaste `.png`-naam: persistent in `/var/lib/docker/unraid/images` en actief onder `/usr/local/emhttp/state`. Alleen de persistente cache vervangen is onvoldoende zolang de actieve cache bestaat; `deploy/refresh-unraid-icon.sh` valideert daarom het echte PNG-MIME-type en vervangt uitsluitend beide DockDeck-bestanden.
- Gemengde widgetformaten gebruiken CSS-grid-dense plaatsing. De onafhankelijke widgetvolgorde blijft gelijk aan de DOM-/toetsenbordvolgorde; directe editknoppen behouden deze toegankelijkheidsregel zonder drag-and-drop.
- Unraid hwmon-classlinks kunnen buiten de beperkte mount wijzen. DockDeck behandelt iedere onleesbare sensor afzonderlijk als optioneel en behoudt array-/disktemperaturen uit `disks.ini`; de Dockerproxy wordt niet verruimd.
- Ollama en Glances gebruiken standaard de ontdekte lokale app-origin zonder credential. Een reverse-proxysubpad of afwijkende API-root vraagt een expliciete URL-override in Settings; een fout valt terug op app-specifieke Dockertelemetrie.
- Tautulli plaatst zijn API-key volgens het officiële contract in de querystring van de uitgaande LAN-request. DockDeck logt die URL niet, maar de doelserver kan dat wel doen; gebruik daarom een afzonderlijke key en bescherm targetlogs.
- De huidige AdGuard API is met Basic Auth beveiligd en JDownloader publiceert alleen noVNC; zonder aanvullende credentials/API-activering tonen deze kaarten daarom veilige app-specifieke live Dockertelemetrie (waaronder transfersnelheid), maar geen querylog, blocktotalen of downloadqueue.
- Een verwijderde app blijft onderdrukt zolang de technische containernaam gelijk blijft. Als Docker de container later bewust onder een andere naam aanbiedt, behandelt DockDeck dit als een nieuw ontdekte app en blijft die standaard verborgen.
- LAN-adresdetectie gebruikt alleen expliciete `br0`-netwerken. Afwijkende macvlan-netwerknamen of meerdere gepubliceerde poorten blijven bewust handmatig overschrijfbaar om geen onzekere URL te kiezen.
- Nieuwe apps blijven als “nieuw ontdekt” gemarkeerd totdat hun zichtbaarheid bewust wordt gewijzigd. Dat is een eenvoudige erkenningshandeling zonder aparte inbox; een gebruiker die alleen andere metadata bewerkt, blijft de ontdekmarkering zien.
- De directe Stitch-pass ligt bewust als laatste, geïsoleerde presentatielaag in `stitch-direct.css` boven de oudere stylesheets. Dat houdt de gedragswijziging klein en reviewbaar, maar een toekomstige frontendopschoning kan de nu overschreven legacyregels veilig verwijderen zodra alle zeldzame settingsstates opnieuw visueel zijn geïnventariseerd.
- De herkenbare merkfallbacks komen uit de vastgepinde MIT-package `@icons-pack/react-simple-icons@13.8.0`. Expliciete appiconen uit Unraid of Settings blijven leidend; niet-afgedekte eigen diensten gebruiken bewust een semantisch Lucide-icoon.
- De lokale Windows-omgeving heeft geen `docker`-CLI/runtime. Compose-config en de klassieke imagebuild zijn daarom op Tower uitgevoerd en voor release `72879e1` groen; de bekende inconsistente BuildKit-cache blijft hostbrede technische schuld.

- De gedeelde ultrawide-canvas en rechter widgetdock zijn bewust in dezelfde presentatielaag geimplementeerd. De E2E-suite valideert geen horizontale overflow en open dock-state op 3440 px, maar zeldzame combinaties van veel brede widgets kunnen later nog een fijnere masonry-/virtualisatielaag vragen.
- Automatische inventarisopschoning verwijdert alleen DockDeck-records die ontbreken in een aantoonbaar verbonden AppOps/Docker-respons. Een foutief maar succesvol leeg antwoord van de externe inventarisbron zou daardoor als autoritatief gelden; maak voor deployment een secretvrije export en bewaak de gerapporteerde containertelling. De Docker-containers zelf worden nooit gewijzigd.
- De Unraid-iconcache wordt bij containerstart uit de root-only DockerMan-iconenmap gevuld en is bewust niet persistent. Een gewijzigd icoon wordt daarom na een containerrecreate zichtbaar; de hostbron blijft read-only en het blijvende applicatieproces draait als UID 100.
- De slimme categorieactie is bewust niet onderdeel van discovery of heartbeat. Nieuwe of hernoemde niche-services blijven in hun bestaande categorie tot de beheerder de actie opnieuw uitvoert of ze handmatig wijzigt; regels moeten bij nieuwe canonical servicetypen expliciet en getest worden uitgebreid.
- Een geïmporteerd of handmatig opgeslagen categorie-icoon buiten de ondersteunde catalogus gebruikt bewust `Layers3` als fallback. Het blijft in Instellingen als aangepast zichtbaar en kan daar zonder dataverlies naar een van de afzonderlijke ondersteunde pictogrammen worden omgezet.

## Blockers

- Geen releaseblockers. Live NPM/providerdiepgang en UPS-status wachten uitsluitend op optionele minimum-scope omgevingsconfiguratie.

## Technical debt

- De eerste migratie is idempotente SQL naast Drizzle-schema's; bij een volgende schemawijziging hoort een genummerde migratietabel/runner.
- NPM-auth met username/password vraagt tijdelijk een token op; een expliciet read-only `NPM_TOKEN` blijft de aanbevolen productieconfiguratie.
- Playwright gebruikt één sequentiële testdatabase. Een toekomstige grotere suite kan per worker een geïsoleerde databasefixture gebruiken.
- De voorkeurenmigratie voegt kolommen idempotent toe aan bestaande databases. Bij verdere schema-uitbreiding blijft een genummerde migratierunner de gewenste vervolgstap.
- De Unraid-host heeft een inconsistente BuildKit-cachelaag. DockDeck kon veilig met de klassieke builder worden gebouwd; herstel van de hostbrede BuildKit-cache valt buiten dit project.

## Security and privacy

- DockDeck leest nooit container-environments of applicatieconfiguratie om providercredentials automatisch te vinden; provider-URL's en tokens worden expliciet als server-side environmentvariabelen aangeleverd.

- Secrets bestaan uitsluitend als procesenvironment en, bij invoer via Settings, in het permission-restricted environmentbestand. Ze worden niet in SQLite of JSON-export opgeslagen en nooit via een API-response teruggegeven.
- De appcontainer krijgt geen Docker-socket. De standaardroute leest alleen AppOps `GET /api/containers`; de optionele fallbackproxy is niet gepubliceerd, heeft `POST=0`, minimale GET-families en een intern netwerk.
- De app definieert geen start-, stop-, restart-, delete-, exec- of andere Docker-mutaties.
- NPM wordt alleen gelezen; DockDeck wijzigt of publiceert geen proxyhosts.
- De sanitizer schrijft alleen toegestane metadata en verifieert de resulterende XML voordat DockDeck die leest.