geointel/REQUIREMENTS.md

REQUIREMENTS.md

Project: DockDeck

Functional Requirements

Implementatiestatus 2026-07-14: FR-1 tot en met FR-19 zijn gebouwd en lokaal geverifieerd. De private Gitea-repository bestaat en productie draait op Unraid-poort 1218. Alleen optionele integratiecredentials en een geauthenticeerde externe proxyroute blijven omgevingskeuzes; zie TEST_LOG.md en docs/IMPLEMENTATION_STATUS.md.

ID	Requirement	Source	Status
FR-1	Implementeer de must-haves: Automatische read-only ontdekking van Unraid Docker-containers; nieuwe containers standaard verborgen; instellingenpagina voor zichtbaarheid, naam, icoon, categorie, sortering en URL-overrides; automatische afleiding van lokale WebUI-URL's uit Unraid-templategegevens; read-only containerstatus met verversing bij laden en ongeveer elke 30 seconden; configureerbare categorieën; configureerbare keuze tussen één totaaloverzicht en categoriepagina's of tabbladen; handmatige favorieten voor externe websites; centrale zoekbalk voor apps, favorieten en Google; openen van alle doelen in een nieuw tabblad; licht, donker en aanvullende ingebouwde thema's; persistent bewaren van instellingen in SQLite; export en import van configuratie; Docker- en Docker Compose-configuratie voor Unraid; beperkte Docker-socketproxy zonder beheerrechten; optionele read-only Nginx Proxy Manager-koppeling voor externe URL's met handmatige fallback; duidelijke foutstatus wanneer Unraid, Docker-proxy of Nginx Proxy Manager tijdelijk onbereikbaar is; automatische initialisatie van een private Gitea-repository via environmentvariabelen; en een uitzonderlijk verzorgde professionele UI met premium dashboardlook, consistente componenten, strak kaartdesign, goede witruimte, duidelijke visuele hiërarchie, subtiele hover- en transition-effecten, nette iconografie en een afgewerkte instellingenomgeving.	Intake	Done
FR-2	Ondersteun het kernidee: Bouw een persoonlijke webapp die als standaard startpagina van de browser dient en een prachtig, professioneel en strak afgewerkt overzicht geeft van de diensten op de Unraid-server. De app ontdekt Docker-containers automatisch via Unraid en een beperkte read-only Docker-socketproxy, maar toont nieuwe containers niet automatisch op het hoofddashboard. In het instellingenmenu kan de gebruiker per container zichtbaarheid, categorie, sortering, icoon, naam en URL beheren. Voor Docker-apps wordt standaard de lokale WebUI-URL uit de Unraid-configuratie gebruikt. Daarnaast kunnen handmatig favoriete externe websites worden toegevoegd met naam, URL, icoon, categorie en sorteerpositie. Het dashboard bevat een centrale zoekbalk die zowel zichtbare Docker-apps als favorieten doorzoekt en, wanneer geen lokaal resultaat wordt gekozen, de invoer als Google-zoekopdracht in een nieuw tabblad opent. De gebruiker kan kiezen tussen één overzicht met categorieën onder elkaar en een weergave met afzonderlijke categoriepagina's of tabbladen. Thema's, weergavevoorkeuren en openingsgedrag worden via instellingen beheerd. Externe toegang kan optioneel worden ingeschakeld; wanneer die actief is, haalt een read-only koppeling met Nginx Proxy Manager beschikbare externe URL's op en koppelt die aan de juiste apps, met steeds een handmatige override als terugval. De UI moet aanvoelen als een hoogwaardige, moderne productinterface met sterke visuele hiërarchie, nette details, subtiele animaties en een verzorgde dashboardervaring.	Intake	Done

Users And Roles

• Primaire gebruikers/rollen: Eén primaire gebruiker: de eigenaar en beheerder van de Unraid-server. Deze gebruiker verwacht zonder technische omwegen snel naar lokale Docker-diensten en favoriete websites te kunnen navigeren, zelf te bepalen welke apps zichtbaar zijn, categorieën en sortering te beheren, de startpagina visueel aan te passen en optioneel lokale of externe app-URL's te gebruiken. Er zijn in de MVP geen afzonderlijke gebruikersrollen, accounts of gedeelde profielen.
• Beheerrollen en permissies: Nog in te vullen.

Core Workflows

1. Gebruiker start met: Bouw een persoonlijke webapp die als standaard startpagina van de browser dient en een prachtig, professioneel en strak afgewerkt overzicht geeft van de diensten op de Unraid-server. De app ontdekt Docker-containers automatisch via Unraid en een beperkte read-only Docker-socketproxy, maar toont nieuwe containers niet automatisch op het hoofddashboard. In het instellingenmenu kan de gebruiker per container zichtbaarheid, categorie, sortering, icoon, naam en URL beheren. Voor Docker-apps wordt standaard de lokale WebUI-URL uit de Unraid-configuratie gebruikt. Daarnaast kunnen handmatig favoriete externe websites worden toegevoegd met naam, URL, icoon, categorie en sorteerpositie. Het dashboard bevat een centrale zoekbalk die zowel zichtbare Docker-apps als favorieten doorzoekt en, wanneer geen lokaal resultaat wordt gekozen, de invoer als Google-zoekopdracht in een nieuw tabblad opent. De gebruiker kan kiezen tussen één overzicht met categorieën onder elkaar en een weergave met afzonderlijke categoriepagina's of tabbladen. Thema's, weergavevoorkeuren en openingsgedrag worden via instellingen beheerd. Externe toegang kan optioneel worden ingeschakeld; wanneer die actief is, haalt een read-only koppeling met Nginx Proxy Manager beschikbare externe URL's op en koppelt die aan de juiste apps, met steeds een handmatige override als terugval. De UI moet aanvoelen als een hoogwaardige, moderne productinterface met sterke visuele hiërarchie, nette details, subtiele animaties en een verzorgde dashboardervaring.
2. Gebruiker voert of beheert de belangrijkste gegevens: Docker-apps met container-ID, technische naam, weergavenaam, afbeelding, ontdekt icoon, online- of offline-status, lokale WebUI-URL, optionele externe URL, zichtbaarheid, categorie, sorteerpositie, detectiebron en laatste statuscontrole; categorieën met naam, icoon, sorteerpositie en weergave-instellingen; favorieten met naam, URL, icoon, categorie en sorteerpositie; dashboardinstellingen met gekozen thema, weergavemodus, openingsgedrag, zoekprovider, pollinginterval en externe-toegangsschakelaar; integratie-instellingen zonder geheime waarden; import- en exportbestand met versieerbaar configuratieschema; synchronisatiestatus en beperkte foutinformatie voor Unraid, Docker-proxy en Nginx Proxy Manager.
3. Systeem levert de gewenste uitkomst: De eerste bruikbare versie draait als Docker-container op Unraid en kan als browserstartpagina worden ingesteld. Na de eerste start ontdekt de app de beschikbare Docker-containers, toont ze in een instellingenoverzicht en laat de gebruiker selecteren welke apps op het dashboard verschijnen. Zichtbare apps staan netjes gegroepeerd in configureerbare categorieën, tonen naam, icoon en actuele online- of offline-status en openen hun lokale WebUI in een nieuw tabblad. Favoriete websites kunnen handmatig worden toegevoegd. De zoekbalk vindt apps en favorieten en kan rechtstreeks een Google-zoekopdracht starten. Alle instellingen blijven na een herstart behouden en kunnen worden geëxporteerd en opnieuw geïmporteerd. De totale ervaring moet eruitzien als een afgewerkt premium product dat de gebruiker met plezier dagelijks als startpagina gebruikt.

Non-Functional Requirements

• Quality bar: De interface moet eruitzien als een professioneel premium product en niet als een simpel hobbydashboard. Verwacht een moderne, luxueuze en verzorgde UI met uitgebalanceerde witruimte, consistente kaartcomponenten, hoogwaardige iconografie, duidelijke typografie, nette schaduwen of diepte waar passend, subtiele animaties, verzorgde empty states, sterke visuele hiërarchie en een kalme maar rijke look-and-feel. De belangrijkste startpagina moet snel laden en direct bruikbaar zijn wanneer integraties traag of tijdelijk offline zijn. Fouten moeten begrijpelijk worden getoond zonder technische stacktraces. Ontbrekende iconen of URL's moeten nette fallbacks hebben. Instellingen moeten veilig opgeslagen worden en bij foutieve invoer gevalideerde feedback geven. De interface moet responsief zijn voor desktop, tablet en basisgebruik op mobiel. Toetsenbordnavigatie, zichtbare focus, semantische HTML en voldoende kleurcontrast zijn vereist. Statuspolling mag geen zichtbare flikkering veroorzaken en moet stoppen wanneer de pagina niet actief is of verstandig worden vertraagd. De code moet modulair, getypeerd, gedocumenteerd en zonder onnodige complexiteit zijn. Esthetische kwaliteit is voor deze MVP een kernvereiste en niet louter een extra.
• Testing expectations: Unit tests voor URL-normalisatie, categorie- en sorteervoorwaarden, zoekresultaten, configuratievalidatie, import- en exportversies, container-naar-Nginx-hostmatching en permissiegrenzen; backend-integratietests met gemockte Unraid-templategegevens, Docker Socket Proxy en Nginx Proxy Manager; SQLite-migratie- en persistentietests; tests die aantonen dat geen Docker-mutatie-endpoints of beheeracties worden gebruikt; browsertests voor eerste ingebruikname, containers zichtbaar maken, categorieën beheren, favorieten toevoegen, zoeken, Google-fallback, thema wisselen, weergavemodus wijzigen, URL openen en configuratie exporteren en importeren; visuele UI-smoketests voor kernschermen zoals dashboard, categorie-overzicht en instellingen; Docker-buildtest en Compose-smoketest; een live read-only validatie op Unraid waarbij discovery, status en lokale WebUI-URL's worden gecontroleerd zonder containers te wijzigen.
• Performance, toegankelijkheid en observability: Lokale fonts, een compacte productieclient, zichtbare toetsenbordfocus, semantische navigatiestatus, gereduceerde animatie waar gevraagd, visibility-aware polling, gestructureerde serverlogs en /api/health. De UI wordt zonder horizontale overflow getest op 390×844, 768×1024, 1440×900 en 3440×1440.

UX Expectations

• UX verwachtingen: Een rustige premium startpagina die van smalle telefoon tot ultrawide proportioneel schaalt. De gebruiker kan thema, accentkleur, dichtheid, contentbreedte, achtergrond, wallpaperpassing/focus/zoom, dashboardhero, statusbadges en overzichtsmodus aanpassen; voorkeuren blijven persistent. De wallpapereditor toont vóór toepassen een realistische preview van het volledige platformvlak. Een geüploade wallpaper heeft voorrang op Aurora, Blauwdruk en Minimaal en loopt ononderbroken onder alle dashboardkolommen.
• Belangrijkste schermen en interacties: Dashboard met hero, zoekbalk, live overzicht, responsieve apptegels en maximaal acht configureerbare servicewidgets met read-only containerstatistieken; instellingen voor uiterlijk, apps, categorieën, favorieten, integraties en back-up. Appbeheer ondersteunt zoeken, zichtbaarheids- en widgetfilters; iedere canonieke categorie heeft een afzonderlijk semantisch pictogram, categorie-iconen zijn bewerkbaar en favorieticonen worden automatisch first-party geladen met een handmatige override.

Data

• Data involved: Docker-apps met container-ID, technische naam, weergavenaam, afbeelding, ontdekt icoon, online- of offline-status, lokale WebUI-URL, optionele externe URL, zichtbaarheid, categorie, sorteerpositie, detectiebron en laatste statuscontrole; categorieën met naam, icoon, sorteerpositie en weergave-instellingen; favorieten met naam, URL, icoon, categorie en sorteerpositie; dashboardinstellingen met gekozen thema, weergavemodus, openingsgedrag, zoekprovider, pollinginterval en externe-toegangsschakelaar; integratie-instellingen zonder geheime waarden; import- en exportbestand met versieerbaar configuratieschema; synchronisatiestatus en beperkte foutinformatie voor Unraid, Docker-proxy en Nginx Proxy Manager.
• Integrations: Unraid Docker-templatebestanden of beschikbare Unraid-metadata voor containernaam, WebUI en iconen; een beperkte read-only Docker Socket Proxy voor containerinventaris en runtime-status; Nginx Proxy Manager API in read-only modus voor optionele externe hostnamen en URL's; Google Search via een gewone zoek-URL zonder API-key; Gitea API voor het aanmaken van een private repository en het configureren van de Git-remote.

Deployment And Runtime

• Preferred stack/runtime: TypeScript als hoofdtaal; React met Vite voor de frontend; Node.js met Fastify voor de backend; SQLite met Drizzle ORM voor persistentie en migraties; gedeelde types en validaties met Zod; een eenvoudige REST-API tussen frontend en backend; een zorgvuldig opgebouwd design system met design tokens, CSS-variabelen en herbruikbare UI-componenten; een moderne componentbibliotheek of headless aanpak voor toegankelijke basiscomponenten; iconenset van hoge kwaliteit; subtiele motion via lichte animatielogica; Docker multi-stage build en Docker Compose voor Unraid; Vitest voor unit- en integratietests; Playwright voor browsertests. Gebruik een overzichtelijke repository met duidelijk gescheiden frontend-, backend- en shared-mappen. Richt de frontend expliciet in op een premium dashboardervaring met consistente spacing, kaartsystemen, typografie, kleurgebruik, statusbadges en instellingenpanelen.
• Runtime model: Interactieve app
• Update/sync strategy: Polling
• Persistence: SQLite
• Deployment target: Docker op Unraid
• Repository state: private Gitea-repository NuklearRabbit/DockDeck; lokale main volgt de remote.
• Omgevingen: lokale development, geïsoleerde Vitest/Playwright-tests en productie op Unraid 192.168.10.150:1218.

Security And Privacy

• Credentials verwacht: Ja
• Security/privacy notes: Gebruik uitsluitend environmentvariabelen voor gevoelige configuratie. Voorzie minimaal variabelen zoals GITEA_URL, GITEA_TOKEN en GITEA_OWNER voor repository-initialisatie en optionele NPM_URL, NPM_USERNAME en NPM_PASSWORD of een ondersteund read-only token voor Nginx Proxy Manager. Gebruik voor de Docker-koppeling geen onbeperkte socketmount in de applicatiecontainer, maar een afzonderlijke proxy met alleen de minimaal noodzakelijke read-endpoints. Sla secrets nooit op in SQLite, exports, logs, frontendbundels, testfixtures of Git. Toon gevoelige integratiewaarden gemaskeerd in de UI. De app mag geen Docker-mutaties uitvoeren en mag nooit containers starten, stoppen, herstarten, verwijderen of aanpassen. De MVP heeft geen eigen authenticatie en moet daarom standaard alleen op een lokaal bindadres of afgeschermd Docker-netwerk worden gepubliceerd. Externe toegang via Nginx Proxy Manager wordt alleen voorbereid; correcte authenticatie en toegangscontrole via bijvoorbeeld Authentik blijven de verantwoordelijkheid van een latere deploymentstap.
• Secrets mogen nooit worden gecommit.

Out Of Scope

Containers starten, stoppen, herstarten, verwijderen of wijzigen; Docker Compose-stacks beheren; Unraid-systeembeheer; terminal- of shelltoegang; logviewer; resourcegrafieken en uitgebreide monitoring; notificaties en incidentbeheer; publieke internettoegang configureren; Authentik- of andere SSO-integratie; eigen gebruikersaccounts, rollen of multi-userondersteuning; opslag van echte API-tokens in de repository of browser; automatische wijzigingen aan Nginx Proxy Manager; cloudhosting; mobiele native apps; AI-functionaliteit; synchronisatie tussen meerdere Unraid-servers; automatische publicatie van diensten naar het internet.

Open Questions

• Welke requirements zijn release-blocking?
• Welke externe systemen moeten eerst gevalideerd worden?

Widget Extension 2026-07-14

• FR-3 (Done): toon standaard een configureerbare Unraid-hostwidget met host-, CPU-, geheugen-, image- en containerinformatie uit Docker /info.
• FR-4 (Done): verrijk geselecteerde AdGuard-, Plex-, Immich-, Home Assistant-, Sonarr-, Radarr- en Lidarr-widgets met provider-specifieke read-only gegevens wanneer uitsluitend server-side environmentcredentials beschikbaar zijn.
• FR-5 (Done): een ontbrekende of falende provider-API valt altijd terug op generieke Dockerstats en blokkeert discovery of navigatie nooit.
• FR-6 (Done): apps kunnen uit DockDeck worden verwijderd zonder Docker te wijzigen; de technische containernaam blijft persistent onderdrukt bij discovery en wordt meegenomen in back-ups.
• FR-7 (Done): de dashboardzoekfunctie indexeert actuele appnamen, technische namen, categorieën, URL's, images, favorieten en de Unraid-host en beweegt direct mee met configuratiewijzigingen.
• FR-8 (Done): iedere servicewidget ondersteunt persistent een compact, standaard of breed formaat en afzonderlijke inhoudslagen voor samenvatting, appmetrics, Dockertelemetrie en voortgang.
• FR-9 (Done): de Unraid-hostwidget heeft eigen persistente formaat- en inhoudsinstellingen; alle widgetconfiguratie blijft exporteerbaar, legacy-compatibel en responsief.
• FR-10 (Done): widgets hebben een onafhankelijke volgorde met toetsenbordbediening en een directe dashboardbewerkingsmodus.
• FR-11 (Done): iedere widget ondersteunt metricvolgorde, primaire metric, aangepast label, waarschuwingsdrempel, sparkline en een veilige eigen verversingscadans.
• FR-12 (Done): de Unraid-hostwidget leest read-only array-, parity-, disk-/pool-, temperatuur- en optionele UPS-status uit minimaal gemounte hostbronnen.
• FR-13 (Done): app-specifieke providers zijn uitgebreid met Gitea, Jellyfin, Seerr, Prowlarr, Authentik, NPM, Portainer, Grafana, Prometheus en Nextcloud; beveiligde POST-gebaseerde API's gebruiken optionele GET-only metrics bridges.
• FR-14 (Done): widgets tonen expliciet fresh, stale of unavailable en behouden laatst succesvolle providergegevens bij tijdelijke uitval.
• FR-15 (Done): layoutpresets kunnen afzonderlijk worden opgeslagen, toegepast, verwijderd, geëxporteerd en geïmporteerd.
• FR-16 (Done): het platform biedt secretvrije diagnostics en een installable PWA-shell die nooit /api-responses cachet.
• FR-17 (Done): de Unraid-hostnaam en WebUI-URL zijn persistent instelbaar onder Widgets; Tower gebruikt standaard expliciet poort 5000 en de aangepaste waarde stuurt zowel de hostkaart als de dynamische zoekindex.
• FR-18 (Done): iedere ontdekte app staat in Widget Studio. Native providers krijgen gedocumenteerde read-only adapters; overige apps krijgen een optionele, server-side GET-only JSON-koppeling met configureerbare URL en bearer-token.
• FR-19 (Done): per widget kan de gebruiker afzonderlijke appmetrics tonen/verbergen, tot 24 metrics rangschikken, de primaire metric kiezen en alle keuzes meenemen in presets en back-ups. De live inventaris heeft specifieke profielen voor applicaties, workers, databases, caches, queues, mail, GPU, media, downloads en eigen projecten.
• FR-20 (Done): de standaard Unraid-installatie bestaat uit precies één container met de vaste naam DockDeck, eigen icoon en correcte WebUI op poort 1218. Discovery gebruikt uitsluitend GET-verzoeken naar de bestaande AppOps-inventaris en mount nooit de Docker-socket; voor hosts zonder AppOps blijft een expliciete, afgescheiden socket-proxyoverlay beschikbaar.
• FR-21 (Done): iedere appwidget kan een echte provider- of infrastructuurreeks als lijn-, vlak- of staafgrafiek tonen, 10–60 samples kiezen, de legenda schakelen, het aantal stats begrenzen, iedere metric als waarde/gauge/progress presenteren en op iedere numerieke metric boven of onder een configureerbare drempel waarschuwen.
• FR-22 (Done): de Tower-widget ondersteunt dezelfde diepe configuratie voor zichtbare serverstats, volgorde, statlimiet en grafieken van containers, images, opslag, temperatuur, parity en UPS. Provider- en serverhistoriek blijft maximaal 60 punten uitsluitend in procesgeheugen.
• FR-23 (Done): Unraid krijgt een werkelijk PNG-gecodeerd transparant DockDeck-icoon; de Compose-label en het gebruikerssjabloon verwijzen niet langer naar SVG-inhoud die Unraid foutief als .png cachet, en de deployment ververst zowel de persistente als actieve DockerMan-cache.