geointel/docs/ARCHITECTURE.md

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.

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.