Publish ITWorx Pulse source

docs/architecture/adr/0001-read-only-v1.md

@@ -0,0 +1,19 @@
+# ADR 0001 — Pulse v1 is operationally read-only
+
+**Status:** Accepted baseline
+
+## Decision
+
+Pulse may observe, query, configure its own monitoring behavior and create user records such as acknowledgements. It may not mutate Unraid, Docker, storage, containers, host processes or network configuration.
+
+## Rationale
+
+Monitoring and management have different security and failure domains. A compromised dashboard must not become a host control plane. Remediation belongs in a separately controlled AppOps workflow.
+
+## Consequences
+
+- No start/stop/restart/delete APIs.
+- No process kill.
+- No array/pool operations.
+- Optional links may open an external management workflow.
+- Tests enforce absence of mutation routes and dangerous agent capabilities.

docs/architecture/adr/0002-go-react-stack.md

@@ -0,0 +1,17 @@
+# ADR 0002 — Go services and React/TypeScript web application
+
+**Status:** Accepted baseline
+
+## Decision
+
+Use Go for API, worker and agent commands. Use React + TypeScript for the web application, with Vite as the default build tool unless discovery proves a stronger need for server-rendered Next.js behavior.
+
+## Rationale
+
+The product is a highly interactive authenticated dashboard rather than a public content site. Go provides efficient long-lived connections, concurrency and small deployable binaries. React has mature dashboard/grid/chart ecosystems. A static frontend reduces production runtime complexity.
+
+## Consequences
+
+- Shared contracts are generated or validated from schemas.
+- API/worker/agent can share modules but deploy with separate privileges.
+- An ADR is required to add a Node server runtime to production.

docs/architecture/adr/0003-prometheus-v1-history.md

@@ -0,0 +1,17 @@
+# ADR 0003 — Existing Prometheus-compatible source remains v1 metrics history
+
+**Status:** Accepted baseline
+
+## Decision
+
+Use the existing Prometheus-compatible endpoint for instant/range queries and retention in v1. Do not introduce VictoriaMetrics or another time-series database until measurements show a concrete retention, performance or reliability requirement.
+
+## Rationale
+
+Avoid duplicate infrastructure and migration risk. Pulse differentiates through semantic queries, UX, inventory, alerts and incidents.
+
+## Consequences
+
+- Query planner and limits protect the source.
+- Pulse stores no full metric history in PostgreSQL.
+- Long-term storage remains a future measured decision.

docs/architecture/adr/0004-postgresql-domain-state.md

@@ -0,0 +1,18 @@
+# ADR 0004 — PostgreSQL stores Pulse domain state
+
+**Status:** Accepted baseline
+
+## Decision
+
+Use PostgreSQL for configuration, inventory, relationships, dashboards, events, alert state/history, incidents, audit and job coordination.
+
+## Rationale
+
+The data is relational, transactional and queryable. PostgreSQL supports JSONB for bounded extensibility and reliable migrations/backups.
+
+## Consequences
+
+- All schema changes use migrations.
+- Production database is private.
+- Backup/restore is a release gate.
+- Metric samples remain outside PostgreSQL.

docs/architecture/adr/0005-docker-access-boundary.md

@@ -0,0 +1,17 @@
+# ADR 0005 — No unrestricted Docker socket in API/web
+
+**Status:** Accepted baseline
+
+## Decision
+
+The web and API containers never mount the unrestricted Docker socket. Docker/Unraid facts come from the official Unraid API, existing exporters, Portainer read-only endpoints, or a separate constrained agent/socket proxy.
+
+## Rationale
+
+Docker daemon access is effectively host control. Read-only filesystem mount flags do not create a read-only Docker API.
+
+## Consequences
+
+- Collector capability endpoints are allowlisted.
+- Agent runtime is separated and audited.
+- Architecture tests inspect compose mounts and API routes.

docs/architecture/adr/0006-rest-websocket.md

@@ -0,0 +1,17 @@
+# ADR 0006 — REST plus WebSocket
+
+**Status:** Accepted baseline
+
+## Decision
+
+Use versioned REST for requests/configuration/history and one authenticated WebSocket per browser session for bounded live updates.
+
+## Rationale
+
+REST is clear for CRUD/query operations. WebSocket supports low-latency subscriptions and server-side coalescing without repeated polling of full datasets.
+
+## Consequences
+
+- Messages use explicit schema/version/sequence.
+- Reconnect and resync are required.
+- Subscription, rate, size and buffer limits are mandatory.

docs/architecture/adr/0007-localization.md

@@ -0,0 +1,17 @@
+# ADR 0007 — Dutch default, localization-ready architecture
+
+**Status:** Accepted baseline
+
+## Decision
+
+Ship user-facing v1 flows in Dutch (`nl-BE`) and use localization keys/contracts so English can be added without rewriting components.
+
+## Rationale
+
+The primary user is Dutch-speaking, while code and technical contracts benefit from stable English identifiers.
+
+## Consequences
+
+- No hardcoded scattered UI copy.
+- Tests cover missing translation keys.
+- Dates/numbers use locale and Europe/Brussels display defaults while storage remains UTC.

docs/architecture/adr/0008-stale-is-unknown.md

@@ -0,0 +1,18 @@
+# ADR 0008 — Stale or missing required telemetry is Unknown
+
+**Status:** Accepted baseline
+
+## Decision
+
+When required telemetry is unavailable beyond its freshness policy, Pulse reports Unknown rather than retaining or inferring Healthy.
+
+## Rationale
+
+False green status is more dangerous than explicit uncertainty.
+
+## Consequences
+
+- Responses carry freshness metadata.
+- Alert rules define unknown behavior.
+- UI shows last known value only with age.
+- Tests inject stale/missing sources throughout the product.

docs/architecture/adr/0009-upstream-dependency-baseline.md

@@ -0,0 +1,42 @@
+# ADR 0009 — Upstream and dependency baseline after M0 research
+
+**Status:** Accepted for M1 planning; exact package versions remain pinned during M1 implementation.
+
+## Context
+
+M0 must verify current upstream capabilities and avoid selecting unsupported or abandoned dependencies. The target Unraid host is 7.2.2 with its native Unraid API online. The local development host has Node.js 24.18.1 and pnpm 10.33.0 but no Go toolchain.
+
+## Decision
+
+- Use the native Unraid GraphQL API as the first inventory adapter. Unraid 7.2+ includes the API in the OS, and programmatic access supports API keys, cookies, and SSO/OIDC. Pulse uses a least-privilege read-only API key or equivalent controlled identity; it must not use mutation capabilities.
+- Keep Prometheus-compatible history as an external server-side datasource. Pulse uses the stable `/api/v1/query` and `/api/v1/query_range` APIs through bounded semantic queries; the browser never contacts Prometheus directly.
+- Use Authentik OIDC/OAuth2 as the production identity integration. The server performs authorization-code exchange and token validation; public/browser flows use PKCE where applicable. Per-provider issuer/discovery is the default because authentik documents it as the recommended issuer mode.
+- Implement the frontend with React + TypeScript + Vite, using the current React documentation baseline (19.2) and Vite's supported Node requirement. Use GridStack as the dashboard-grid candidate; retain a measured-equivalent escape hatch. Do not commit exact package versions until M1 lockfile/bootstrap work.
+- Prefer Go's standard library for the initial backend transport and pin a currently supported Go release in M1. The official Go release policy supports a major release until two newer majors exist. The baseline is maintained at Go 1.26.6 after the M13 release image gate identified fixed standard-library findings in 1.26.5.
+
+## License and support record
+
+| Component | Upstream license observed | Support/compatibility note |
+|---|---|---|
+| Go toolchain | BSD-style (official Go distribution) | Use an official currently supported release; Go is not installed locally yet. |
+| React | MIT | Official React docs list 19.2 as latest major baseline. |
+| Vite | MIT | Official docs require Node 20.19+ or 22.12+; local Node 24.18.1 satisfies the documented floor. |
+| GridStack | MIT | Candidate only; verify package release and transitive dependencies during M1. |
+| Prometheus API/source | Apache 2.0 | External source; Pulse does not redistribute Prometheus in the application image. |
+| authentik integration | MIT core with documented directory/component exceptions | Pulse integrates with the deployed provider; it does not embed or redistribute authentik. |
+
+## Consequences
+
+- M1 must provision Go, generate lockfiles, run license/dependency checks, and pin exact versions from official release metadata.
+- Prometheus location remains unresolved in the actual Unraid environment: no local 9090 listener/container was found. Datasource onboarding must support an explicitly configured external endpoint and report Unknown when absent/stale.
+- The frontend runtime remains a static React/Vite artifact served behind the API/reverse proxy, preserving the no-infrastructure-access browser boundary.
+
+## Sources accessed 2026-08-01
+
+- [Unraid API overview](https://docs.unraid.net/API/) and [Unraid API usage](https://docs.unraid.net/API/how-to-use-the-api/)
+- [Go release history](https://go.dev/doc/devel/release)
+- [Prometheus HTTP API](https://prometheus.io/docs/prometheus/latest/querying/api/) and [PromQL basics](https://prometheus.io/docs/prometheus/latest/querying/basics/)
+- [authentik OAuth 2.0/OIDC provider](https://docs.goauthentik.io/add-secure-apps/providers/oauth2)
+- [React versions](https://react.dev/versions) and [React reference](https://react.dev/reference/react)
+- [Vite getting started and compatibility](https://vite.dev/guide/)
+- [React MIT license](https://raw.githubusercontent.com/react/react/main/LICENSE), [Vite MIT license](https://raw.githubusercontent.com/vitejs/vite/main/LICENSE), [GridStack MIT license](https://raw.githubusercontent.com/gridstack/gridstack.js/master/LICENSE), [Prometheus Apache 2.0 license](https://raw.githubusercontent.com/prometheus/prometheus/main/LICENSE), and [authentik license](https://raw.githubusercontent.com/goauthentik/authentik/main/LICENSE)