66 lines
23 KiB
Markdown
66 lines
23 KiB
Markdown
# 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. |
|