Initial curated DockDeck source from 26772208f608782e88c736dc70878e7b5abd3916

docs/ARCHITECTURE.md

@@ -0,0 +1,45 @@
+# DockDeck architecture
+
+## Runtime
+
+DockDeck is one deployable Node.js process. Fastify owns the REST API and serves the compiled React client in production. React/Vite provides the development UI. SQLite is mounted at `/data`; Drizzle ORM owns typed reads and writes while a small idempotent SQL migration creates the first schema before Fastify starts.
+
+```text
+Browser → Fastify API → domain rules → Drizzle → SQLite
+                       ↘ discovery service → AppOps inventory (GET only)
+                                           → Unraid XML/runtime mounts (read only)
+                                           → NPM API (read only, optional)
+```
+
+## Trust boundaries
+
+- The `dockdeck` container never receives `/var/run/docker.sock`.
+- The standard deployment is exactly one `DockDeck` container. A separate `dockerproxy` exists only in the optional fallback overlay; there it is private, has `POST=0` and disables all mutation families.
+- Unraid templates are mounted read-only.
+- NPM, Gitea and provider credentials exist only as server-side process environment. Values entered in Settings are persisted in the permission-restricted environment file and remain excluded from API responses, SQLite and JSON exports.
+- Fastify validates every user-controlled mutation with Zod. External integration errors are reduced to non-sensitive connection states.
+- New discoveries are inserted with `visible=false`. Subsequent syncs update runtime fields but preserve user choices and overrides.
+- A DockDeck-only app removal records the technical name in `removed_apps`; later discovery ignores that name and never calls a Docker mutation endpoint.
+
+## Modules
+
+- `src/shared`: Zod contracts and pure URL/search/matching/sorting rules.
+- URL resolution prefers an explicit `br0` LAN address, then the configured Unraid host, and uses a single unambiguous published TCP port when template metadata is stale.
+- Dashboard search is a derived client index over the latest payload, so renames, removals, category changes and URL changes require no separate search persistence.
+- `src/server/database.ts`: persistence, migration, import/export and user preference invariants.
+- Widget layout is stored as validated size/content, metric order/visibility/style, statistic limit, warning and chart fields on app and preference records. Legacy rows receive safe standard/all-content defaults; version 1 backups remain compatible because added backup fields are optional on import.
+- `src/server/integrations`: read-only external adapters, provider capability metadata and deterministic mocks. Provider URLs default to an already discovered local app origin; explicit environment overrides remain available. Provider recognition is token-based and excludes known support-container roles.
+- `src/server/integrations/unraid-status.ts`: parseert een minimale read-only view van Unraid runtime- en hwmondata naar array-, parity-, opslag-, temperatuur- en optionele UPS-metrics.
+- Provideradapters bewaren alleen de laatst succesvolle gereduceerde metricresponse en een korte tijdreeks in procesgeheugen; geen van beide overleeft een procesrestart.
+- `src/server/app.ts`: narrow REST surface; no Docker control routes.
+- `src/client`: accessible responsive UI and design tokens.
+
+## Layout and offline model
+
+Widgetvolgorde staat los van apptegelvolgorde. App- en hostrecords bewaren hun eigen volgorde; layoutpresets bevatten alleen presentatievelden, inclusief metricselectie, value/gauge/progress, waarschuwing en lijn-/vlak-/staafgrafiek. Provider- en hosthistoriek bevat maximaal zestig punten per numerieke reeks en blijft uitsluitend in procesgeheugen. Het toepassen van een preset kan geen appzichtbaarheid, navigatie-URL, credential of Dockerstaat wijzigen.
+
+De serviceworker cachet alleen statische applicatieshellassets. Requests onder `/api/` worden volledig overgeslagen, zodat offline content nooit als actuele runtime- of providerdata wordt gepresenteerd.
+
+## Failure behavior
+
+Saved data is always returned independently of integration health. A failed AppOps inventory, missing Unraid mount or unavailable NPM instance produces a degraded integration card/banner without blocking navigation. Polling runs only while the browser tab is visible. AppOps inventory is read immediately; its slower all-container resource sample refreshes in the background so it cannot delay navigation.