40 lines
19 KiB
Markdown
40 lines
19 KiB
Markdown
# PROJECT_BRIEF.md
|
|
|
|
## Project
|
|
|
|
- Projectnaam: DockDeck
|
|
- Korte beschrijving: Een premium ogend persoonlijk startdashboard voor Unraid dat Docker-apps automatisch ontdekt, stijlvol groepeert en snelle navigatie biedt naar lokale diensten en eigen favorieten.
|
|
- Projectidee: 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.
|
|
- Probleem: De gebruiker heeft meerdere Docker-diensten op een Unraid-server en moet momenteel afzonderlijke URL's onthouden, bladwijzers beheren of via verschillende beheerinterfaces navigeren. Bestaande startpagina's sluiten niet volledig aan op de gewenste combinatie van automatische Unraid-detectie, configureerbare zichtbaarheid, categorie-indeling, statusweergave, lokale en externe URL's, favoriete websites, geïntegreerde zoekfunctie en een echt professioneel ogende premium UI.
|
|
- Doelgebruikers: 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.
|
|
- 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.
|
|
- Succescriteria: De MVP is klaar wanneer: de applicatie via Docker Compose op Unraid kan worden gestart; beschikbare Docker-containers automatisch worden ontdekt zonder schrijf- of beheerrechten op Docker; nieuw ontdekte containers standaard verborgen blijven; de gebruiker containers zichtbaar of verborgen kan maken; naam, icoon, categorie, sortering en lokale URL per app kunnen worden aangepast; de lokale WebUI-URL waar mogelijk automatisch uit Unraid-templategegevens wordt afgeleid; zichtbare apps naam, icoon en correcte online- of offline-status tonen; status bij het openen en daarna ongeveer elke 30 seconden wordt vernieuwd; categorieën kunnen worden aangemaakt, hernoemd, gesorteerd en toegewezen; zowel een volledig overzicht als categoriegebaseerde navigatie configureerbaar is; favorieten met naam, URL, icoon, categorie en sortering kunnen worden beheerd; de zoekbalk apps en favorieten doorzoekt en overige invoer naar Google stuurt; alle links in een nieuw tabblad openen; licht, donker en minstens één aanvullend thema selecteerbaar zijn; configuratie persistent blijft na container- en serverherstart; back-up en herstel via export en import werken; de app uitsluitend voor lokaal gebruik is ingericht en geen container start-, stop-, restart- of wijzigingsacties bevat; een private Gitea-repository automatisch wordt aangemaakt, lokaal wordt geïnitialiseerd en een eerste bruikbare commit bevat; en de UI een consistent, professioneel en visueel hoogwaardig geheel vormt met nette kaartlay-outs, sterke typografie, duidelijke statusindicatoren, vloeiende maar subtiele interacties en een verzorgde instellingenervaring.
|
|
|
|
## Scope
|
|
|
|
- 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.
|
|
- Nice-to-haves: Drag-and-drop sortering van apps en categorieën; automatisch herkennen van bekende applicatie-iconen; favicon-import voor favorieten; meerdere aanvullende kleurthema's; compacte en ruime tegelweergave; achtergrondafbeeldingen of subtiele dashboard-achtergronden; sneltoets om de zoekbalk te focussen; recente of meest gebruikte apps; optionele statuslatentie en responstijd; import van bestaande browserbladwijzers; meerdere dashboards of profielen; PWA-installatie; mobiele optimalisaties buiten de basisresponsiviteit; geavanceerde automatische matching tussen Nginx Proxy Manager-hosts en Docker-containers; handmatige statuscontrole voor favoriete websites; extra micro-interacties en visuele personalisatieopties zolang die de strakke premium uitstraling ondersteunen.
|
|
- Buiten 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.
|
|
- Constraints: De MVP moet als Docker-container op de bestaande Unraid-server draaien en alleen vanaf het lokale netwerk bereikbaar zijn. De app moet zonder eigen login bruikbaar zijn, omdat netwerktoegang de primaire beveiligingsgrens vormt. Alle Docker-toegang moet read-only verlopen via een beperkte socketproxy; de hoofdcontainer krijgt geen directe onbeperkte Docker-socket. Unraid-templategegevens mogen alleen worden gelezen. Nginx Proxy Manager wordt uitsluitend read-only benaderd. De applicatie moet bruikbaar blijven wanneer Nginx Proxy Manager niet is geconfigureerd of tijdelijk niet bereikbaar is. Er mogen geen betaalde externe diensten nodig zijn. Alle configuratie moet persistent blijven bij herstart en eenvoudig te back-uppen zijn. Codex moet een nieuwe private repository in de persoonlijke Gitea-omgeving aanmaken en mag geen secrets hardcoderen. Visuele kwaliteit is belangrijk, maar de UI mag niet onnodig zwaar of traag worden; professionele polish moet samengaan met vlotte prestaties als browserstartpagina.
|
|
|
|
## Eerste Aannames
|
|
|
|
| Aanname | Status |
|
|
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
|
|
| Het projecttype is webapp. | Te valideren |
|
|
| De voorkeursstack is 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.. | Te valideren |
|
|
| Runtime: Interactieve app. | Te valideren |
|
|
| Update/sync: Polling. | Te valideren |
|
|
| Persistentie: SQLite. | Te valideren |
|
|
| Deployment: Docker op Unraid. | Te valideren |
|
|
| Repository: Repo nog nodig. | Te valideren |
|
|
| De primaire gebruikers zijn 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.. | Te valideren |
|
|
|
|
## Open Questions
|
|
|
|
| Vraag | Waarom dit nodig is |
|
|
| ----------------------------------------------------------------- | ------------------------------------ |
|
|
| Welke randgevallen moeten expliciet ondersteund worden? | Maakt requirements toetsbaar. |
|
|
| Welke data mag lokaal, extern of helemaal niet opgeslagen worden? | Bepaalt security en privacy ontwerp. |
|
|
| Welke definitie van klaar geldt voor de eerste release? | Houdt scope en planning scherp. |
|