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.

docs/EXTERNAL_ACCESS.md

@@ -0,0 +1,14 @@
+# External access
+
+DockDeck defaults to loopback publication. Keep that default unless network access is intentional.
+
+For a trusted LAN:
+
+1. Generate an operator password hash with `node scripts/hash-operator-password.mjs`.
+2. Set both `DOCKDECK_OPERATOR_USER` and `DOCKDECK_OPERATOR_PASSWORD_HASH`.
+3. Set `DOCKDECK_BIND_ADDRESS` to the intended host interface.
+4. Restrict access with host or network firewall rules.
+
+For access beyond the trusted LAN, place DockDeck behind an authenticated HTTPS reverse proxy. Do not expose the optional Docker socket proxy, AppOps, or provider APIs through that proxy. HTTP Basic credentials must not be sent over plaintext internet connections.
+
+JSON configuration exports exclude credentials but can identify services and URLs. Treat them as sensitive operational data.