geointel/DECISIONS.md

DECISIONS.md

Project: DockDeck

Decision Log

ID	Decision	Rationale	Status
D-001	DockDeck is een interactieve webapp.	Past bij browserstartpagina en lokaal beheer.	Accepted
D-002	TypeScript, React/Vite, Fastify, Drizzle/SQLite, Zod, Vitest en Playwright in één repository.	Kleinste stack die de bindende brief volledig en testbaar dekt.	Accepted
D-003	Fastify serveert in productie REST en de gebouwde React-client.	Eén container en één poort beperken Unraid-complexiteit.	Accepted
D-004	Statuspolling is configureerbaar, standaard 30 seconden, en pauzeert op verborgen tabs.	Actuele status zonder flikkering of onnodige achtergrondbelasting.	Accepted
D-005	SQLite staat in /data/dockdeck.db; een idempotente migratie draait vóór serverstart.	Eenvoudige persistente back-up zonder externe database.	Accepted
D-006	De hoofdapp krijgt geen Docker-socket; discovery verloopt via een server-side GET-adapter en alleen de optionele fallbackproxy ziet de socket.	Handhaaft de expliciete veiligheidsgrens.	Accepted
D-007	Git gebruikt lokaal main; private Gitea-initialisatie gebeurt via een apart environmentgestuurd script.	Credentials waren lokaal niet beschikbaar en worden nooit opgeslagen.	Accepted
D-008	Integraties rapporteren connected, degraded of disabled; opgeslagen navigatie blijft beschikbaar.	Externe uitval mag het dashboard niet blokkeren.	Accepted
D-009	Exportformaat versie 1 bevat alleen gebruikersconfiguratie, nooit secrets.	Veilige en toekomstig migreerbare back-up.	Accepted
D-010	Visuele voorkeuren worden als uitbreidbare velden in SQLite opgeslagen en bij oudere databases idempotent toegevoegd.	Personalisatie blijft na updates behouden zonder een breaking exportwijziging.	Accepted
D-011	DM Sans en Newsreader worden lokaal uit het applicatiepakket geladen.	De startpagina blijft visueel stabiel en heeft geen externe fontrequest nodig.	Accepted
D-012	Servicewidgets gebruiken read-only runtimegegevens voor maximaal acht expliciet gekozen containers; standaard via AppOps en in de optionele fallback via Dockerstats.	Levert CPU-, geheugen- en statusinformatie zonder appcredentials of Dockerbeheerrechten.	Accepted
D-013	Favorieten leiden zonder override hun icoon af als <origin>/favicon.ico en vallen bij fouten terug op een monogram.	Automatische first-party iconen zonder externe favicon- of trackingdienst.	Accepted
D-014	De standaard Unraid-widget combineert AppOps-inventaris met minimale hostmounts; providers gebruiken expliciete server-side minimum-scope credentials en runtimefallbacks.	Levert echte dienstfunctionaliteit zonder container-environments te inspecteren, secrets op te slaan of de read-only grens te verruimen.	Accepted
D-015	Providercredentials kunnen in Settings worden geschreven naar een atomisch vervangen 0600-environmentbestand in het persistente volume; de API echoot waarden nooit terug.	Maakt app-specifieke widgets configureerbaar zonder secrets in SQLite, export, logs, frontendbundel of Git te plaatsen.	Accepted
D-016	Widget Studio gebruikt niet-persistente capabilitymetadata; provideradapters mogen de ontdekte lokale app-origin als URL gebruiken en vragen alleen ontbrekende secrets.	Maakt rijke widgets vindbaar en vaak zero-config zonder dubbel URL-beheer of automatische wijziging van gebruikersvoorkeuren.	Accepted
D-017	Een uit DockDeck verwijderde app wordt op technische containernaam persistent onderdrukt; de Docker-container zelf blijft onaangeraakt.	Geeft echte, restartbestendige opruiming binnen het platform zonder de read-only Dockergrens te doorbreken.	Accepted
D-018	De zoekindex is volledig afgeleid uit de actuele dashboardpayload en bevat ook verborgen apps, aliases, URL's, categorieën, favorieten en de Unraid-host.	Hernoemen en configuratiewijzigingen worden direct vindbaar zonder een aparte stale zoekdatabase.	Accepted
D-019	Widgetformaat en informatielagen zijn expliciete, persistente app-/hostvelden; providerdetectie gebruikt servicetokens en sluit supportcontainers uit.	Geeft echte inhoudscontrole en voorkomt dat brede substringmatches een verkeerde providerkaart opleveren.	Accepted
D-020	Widgetvolgorde staat los van apptegelvolgorde; directe editbediening gebruikt semantische knoppen en blijft zonder drag-and-drop volledig bruikbaar.	Behoudt voorspelbare toetsenbord- en schermlezervolgorde in responsive dense grids.	Accepted
D-021	App- en servergrafieken bewaren maximaal zestig punten alleen in serverprocesgeheugen; iedere widget heeft een begrensde refreshcadans, configureerbaar venster en expliciete freshness.	Geeft nuttige korte trends zonder een monitoringdatabase of onbegrensde hostbelasting.	Accepted
D-022	Unraid-native status komt uit specifieke read-only runtime- en hwmonmounts, nooit uit een verruimde Dockerproxy of mutatie-API.	Levert array- en hostdiepgang met een minimale, controleerbare trust boundary.	Accepted
D-023	Beveiligde applicaties zonder GET-only native API gebruiken optioneel een door de gebruiker beheerde metrics bridge.	Houdt DockDeck aantoonbaar GET-only en maakt toch app-specifieke widgets mogelijk.	Accepted
D-024	Layoutpresets zijn afzonderlijke records en exports; toepassen wijzigt alleen widgetpresentatie, nooit appzichtbaarheid, credentials of containers.	Maakt contextwissels veilig en draagbaar zonder een volledige configuratierestore.	Accepted
D-025	De PWA-serviceworker cachet uitsluitend de applicatieshell en weigert API-caching; diagnostics zijn secretvrij.	Voorkomt dat operationele data of credentials als offline autoriteit in de browser blijven staan.	Accepted
D-026	Iedere ontdekte app krijgt capabilitymetadata en een optionele GET-only JSON-koppeling wanneer geen native adapter bestaat.	Dekt ook eigen en niche-apps af zonder onveilige beheer-API's, containerspecifieke secrets of generieke schijnmetrics.	Accepted
D-027	Zichtbaarheid en volgorde van appmetrics worden per widget als labels opgeslagen en met live providerlabels samengevoegd.	Laat inhoud aanpassen zonder het opslagmodel aan iedere nieuwe provider of metric te koppelen.	Accepted
D-028	Tower-identiteit is gebruikersconfiguratie; een ontbrekende poort in de Unraid-basis-URL wordt als 5000 geïnterpreteerd.	Herstelt de werkelijke lokale WebUI-link en houdt toekomstige hostnaam- of poortwijzigingen in de UI beheerbaar.	Accepted
D-029	De standaard Unraid-deployment bestaat uit één branded DockDeck-container en gebruikt de bestaande AppOps GET-inventaris; een losse socketproxy is uitsluitend een optionele overlay.	Voldoet aan eenvoudig Unraid-beheer zonder de Docker-socket of mutatierechten aan DockDeck te geven.	Accepted
D-030	Capabilitymetadata bepaalt ook de niet-gekoppelde kaartinhoud; ontbrekende appdata wordt expliciet als te koppelen getoond en nooit vervangen door generieke schijnmetrics.	Houdt iedere widget domeinspecifiek zonder waarden te verzinnen en scheidt echte Docker-infrastructuurtelemetrie duidelijk.	Accepted
D-031	Unraid-listmetadata gebruikt een echt transparant PNG-bestand, ook al blijft de PWA vrij om het schaalbare SVG-asset te gebruiken.	Sluit aan op Unraids vaste .png-cache en voorkomt een onzichtbaar icoon door een fout MIME-/bestandsformaat.	Accepted
D-032	De Unraid-deployment ververst na een icoonwijziging zowel Dockermans persistente als actieve RAM-cache en valideert vooraf het echte PNG-MIME-type.	DockerMan hergebruikt anders een bestaand actief cachebestand, waarna zijn onerror het bedoelde icoon stilzwijgend door question.png vervangt.	Accepted
D-033	DockDeck Canon v1 is de bindende visuele bron; conflicterende Obsidian Control-, Core Modernist- en oudere Stitch-varianten worden niet gecombineerd.	Eén expliciet ontwerpsysteem voorkomt een hybride interface en houdt tokens, componentvormen en responsive gedrag onderhoudbaar.	Accepted
D-034	Launcherinhoud en Quick Launch vormen de primaire dashboardhiërarchie; bestaande read-only widgets, presets en diagnostics blijven behouden onder een secundair uitklapbaar inzicht en Algemeen.	Behoudt alle operationele functionaliteit zonder de rustige dagelijkse startflow van Canon v1 te verdringen.	Accepted
D-035	Geist wordt lokaal gebundeld en alle Canon-kleuren, spacing, radii en states lopen via semantische tokens voor dark, light en Harbor.	Voorkomt externe fontafhankelijkheden en maakt themagedrag consistent zonder Canon-waarden door component-CSS te verspreiden.	Accepted
D-036	Playwright draait lokaal op de geïsoleerde API-/webpoorten 3101 en 5174, configureerbaar via environmentvariabelen.	Vermijdt botsing met de bestaande WSL-relay op poort 3000 zonder de productiestandaardpoort of runtimearchitectuur te wijzigen.	Accepted
D-037	De Stitch-launcher combineert op desktop een permanente favorietenrail met zichtbare read-only servicepanelen; op tablet en mobiel blijven favorieten en apps vóór de panelen staan.	Herstelt de sterke dagelijkse navigatie en widgetmogelijkheden uit het oorspronkelijke DockDeck zonder de rustige mobiele Canon-hiërarchie te verliezen.	Accepted
D-038	Appiconen gebruiken eerst expliciete Unraid-/gebruikersmetadata, daarna een lokaal gebundeld merkicoon en ten slotte een semantisch service-icoon; lettermonogrammen vervallen.	Geeft iedere app een herkenbare visuele identiteit zonder CDN-afhankelijkheid en houdt onbekende of eigen diensten toch betekenisvol.	Accepted
D-039	Instellingen zijn centraal doorzoekbaar; verversingsinterval en verminderde beweging zijn expliciete, persistente voorkeuren die ook in versie 1-export/import meegaan.	Maakt de volledige instellingenoppervlakte vindbaar en voorkomt dat bereikbaarheid of polling alleen als verborgen backendcontract bestaan.	Accepted
D-040	Nieuwe discovery-records krijgen een persistente discoveredAt-tijd en isNew-status; bestaande databases migreren records als erkend en een zichtbaarheidshandeling erkent een nieuw record.	Houdt de ontdekbanner en het filter “Nieuw ontdekt” waarheidsgetrouw zonder bewust verborgen bestaande apps als nieuw te presenteren.	Accepted
D-041	Dashboard en instellingen delen voortaan dezelfde gecentreerde platformcanvas; vanaf 1900 px wordt de widgetlaag automatisch als rechterdock geopend en de appgrid vult ultrawide ruimte vloeiend.	Herstelt de visuele consistentie met de nette instellingenzijbalk, gebruikt brede schermen doelgericht en houdt widgets zichtbaar zonder de launcher te verdringen.	Accepted
D-042	Een geslaagde Docker/AppOps-inventaris is autoritatief: ontbrekende apprecords worden automatisch uit DockDeck verwijderd en naamvergelijking is hoofdletterongevoelig; bij een degraded inventaris wordt niets opgeschoond.	Houdt Instellingen gelijk aan de werkelijk bestaande containers, herstelt actuele status zonder duplicaten en voorkomt dat tijdelijke integratie-uitval opgeslagen configuratie wist.	Accepted
D-043	Unraid DockerMan-iconen worden uit een minimale read-only hostmount naar een tijdelijke containercache gekopieerd; daarna draait de applicatie als de niet-geprivilegieerde dockdeck-gebruiker en serveert alleen gekende afbeeldingsformaten.	De persistente Unraid-iconen zijn root-only en de runtimecache is niet volledig. Een begrensde initkopie levert alle echte iconen zonder hostpermissies te wijzigen of blijvende rootrechten te geven.	Accepted
D-044	Slimme categorie-indeling is een expliciete gebruikersactie met geordende, geteste serviceregels; alleen bekende services worden verplaatst en onbekende containers en favorieten blijven ongewijzigd.	Corrigeert aantoonbare bulkfouten zonder automatische heartbeats of toekomstige discovery de bewuste persoonlijke indeling van onbekende apps te laten overschrijven.	Accepted

| D-045 | Wallpapers worden als één gevalideerd lokaal PNG/JPEG/WebP-bestand naast de database opgeslagen; weerdata komt server-side en tien minuten gecachet van Open-Meteo. Publieke healthroutes leveren een zero-secret status, terwijl tokens alleen optionele detailstatistieken ontsluiten. | Houdt beelddata en integraties uit SQLite, exports en browserbundels, voorkomt secretlekken en levert toch een rijke dagelijkse startpagina met minimale externe belasting. | Accepted | | D-046 | Een wallpaper wordt in een sticky stage ter hoogte van het zichtbare centrale viewport gerenderd. Passing, X-/Y-focus en zoom zijn afzonderlijke persistente voorkeuren met contain als veilige standaard. | Voorkomt dat lange dashboardinhoud de afbeelding sterk afsnijdt, houdt de volledige afbeelding standaard zichtbaar en geeft de gebruiker gecontroleerde compositievrijheid zonder het bronbestand te wijzigen. | Accepted | | D-047 | Zodra een wallpaper bestaat, vervangt die de achtergrondpreset op het volledige platformvlak onder de topbalk. Een scherpe instelbare beeldlaag ligt boven een zachte cover-kopie; rails, widgets en tegels zijn leesbare glaslagen erboven. | Laat de afbeelding ononderbroken van de linker- tot de rechterkolom lopen en tegelijk volledig zichtbaar blijven bij contain, zonder Blauwdruk-, Aurora- of Minimaal-lagen door de wallpaper heen te mengen. | Accepted | | D-048 | Canonieke categorie-iconen gebruiken één gedeelde catalogus voor keuzelijst én renderer; iedere huidige categorie resolveert naar een unieke Lucide-component en nieuwe categorieën kiezen eerst een ongebruikt icoon. | Voorkomt dat geldige opgeslagen waarden stil naar hetzelfde generieke Layers3-beeld terugvallen en houdt toekomstige categorieën visueel onderscheidbaar zonder data te herschrijven. | Accepted |

Decision Rules

Rule	Reason
Leg architectuurkeuzes vast voordat ze breed doorwerken.	Voorkomt impliciete afhankelijkheden.
Kies de kleinste oplossing die aan de must-haves voldoet.	Beschermt scope en snelheid.
Heropen beslissingen wanneer requirements of risico's wijzigen.	Houdt het dossier betrouwbaar.