ITWorx-Pulse-Public/docs/architecture/SYSTEM_ARCHITECTURE.md

System architecture

1. Context

ITWorx Pulse sits between the browser/operator and existing telemetry/inventory sources. It provides no operational write path to Unraid or Docker in v1.

M0 environment binding

The discovered target is one Unraid 7.2.2 host with the native Unraid GraphQL API online, existing Nginx Proxy Manager and Authentik services, Grafana and host telemetry endpoints, and no local Prometheus container/listener identified during read-only discovery. Pulse therefore remains an additive, isolated Compose project. Host port, DNS name, appdata path, proxy record, and Docker network names are intentionally runtime discovery outputs and are not hardcoded in this architecture document.

The API/web trust boundary is unchanged by discovery: neither service receives a Docker socket or host filesystem privilege. The agent uses an allowlisted read-only Unraid API capability path. A separately configured Prometheus-compatible endpoint is queried only server-side; if it is unavailable or stale, the datasource and dependent status are Unknown.

Browser
  |
  | HTTPS / OIDC / REST / WebSocket
  v
Pulse Web + API
  |              \
  |               \ PostgreSQL
  |                 config, inventory, events,
  |                 alerts, incidents, audit
  |
  +--> Prometheus-compatible source
  |      historical metrics and range queries
  |
  +--> Pulse Worker
  |      discovery, reconciliation, alert evaluation,
  |      probes, retention, notifications
  |
  +--> Pulse Agent / constrained adapters
         read-only Unraid, host, storage and container facts

2. Deployable units

pulse-web

Preferred outcome: static React application served by a minimal web server or the API gateway. It has no secrets beyond public OIDC configuration and no direct infrastructure access.

pulse-api

Responsibilities:

• authenticated REST API;
• WebSocket authentication and subscriptions;
• dashboard/config CRUD;
• inventory and event reads;
• query planning and limits;
• alert/incident user actions;
• audit;
• health/readiness.

No Docker socket and no host filesystem privilege.

pulse-worker

Responsibilities:

• scheduled discovery/reconciliation;
• alert rule evaluation;
• service probes;
• incident correlation;
• notification delivery;
• retention/cleanup;
• periodic self-checks.

Jobs are idempotent and database-coordinated.

pulse-agent

Responsibilities:

• host/Unraid/storage/container discovery that cannot be safely obtained through existing APIs/exporters;
• normalized event/metric/status collection;
• capability reporting.

The agent has the minimum read-only access required. It does not expose a general shell or mutation endpoint.

The API, worker and agent may share one Go module and image with separate commands while retaining runtime privilege separation.

PostgreSQL

Stores:

• users/external identities and roles;
• settings and secrets references;
• datasource metadata/health;
• inventory and relationships;
• dashboards/versions/widgets/layouts;
• events;
• alert rules/state/occurrences;
• incidents/notes;
• audit;
• job coordination and migrations.

It does not duplicate full Prometheus time-series data.

Prometheus-compatible source

Provides:

• metric metadata;
• instant/range query;
• historical retention;
• existing exporter scrape state.

Pulse queries it through a constrained server-side adapter. Browser access is forbidden.

3. Logical modules

identity
authorization
configuration
datasources
inventory
metrics
dashboards
live
events
alerts
incidents
probes
notifications
audit
operations

Each module defines domain types and interfaces. HTTP/database/Prometheus/Unraid implementations are adapters.

4. Data flows

Dashboard load

1. Browser requests dashboard definition.
2. API authorizes user and returns validated config.
3. Browser sends a batched semantic historical query.
4. API query planner validates bounds, translates to PromQL and deduplicates.
5. Prometheus returns series.
6. API normalizes units/metadata and returns bounded points.
7. Browser opens one WebSocket and subscribes to visible live streams.
8. Live broker coalesces equivalent subscriptions.

Discovery

1. Worker requests capability/inventory snapshots from adapters/agent.
2. Payloads are validated and source-stamped.
3. Reconciler maps stable identities and relationships.
4. User overrides remain separate.
5. Changes create normalized events.
6. Datasource freshness/status is updated.

Alert evaluation

1. Worker selects due rules with a coordination lock.
2. Rule queries semantic metric/event/status inputs.
3. State machine applies pending/hysteresis/cooldown.
4. Occurrence/event/audit records persist transactionally.
5. Suppression/grouping is calculated.
6. Incident correlation and notifications run.
7. UI receives a live state update.

5. Trust boundaries

1. Browser <-> web/API.
2. Pulse runtime <-> OIDC provider.
3. API/worker <-> PostgreSQL.
4. API/worker <-> Prometheus.
5. Agent/adapters <-> host/Unraid/Docker.
6. Probe worker <-> configured network targets.
7. Notification worker <-> external channels.

Each boundary requires authentication/authorization, timeouts, validation, redaction and least privilege.

6. Availability model

Pulse may run as a single instance in v1. It must recover from restarts without losing configuration or alert history.

• Web/API failure: external health check detects.
• Worker failure: heartbeats and dead-man alert.
• Agent failure: datasource unknown/stale; no false green.
• Prometheus failure: historical/live metrics unknown; inventory remains available.
• Database failure: API not ready; no in-memory claim of health.
• OIDC failure: existing sessions follow policy; break-glass recovery remains controlled.

7. Scaling limits

Target:

• one host;
• 150 containers;
• 40 disks;
• 300 service probes;
• 2,500 active dashboard series;
• 10 concurrent users;
• long-running wallboard.

The architecture must bound:

• Prometheus concurrency;
• series/points;
• browser ring buffers;
• WebSocket subscriptions;
• event payloads;
• probe concurrency/response size;
• inventory snapshots;
• audit retention.

8. Configuration

Configuration layers:

1. secure runtime environment/secrets;
2. validated application config;
3. database-managed settings;
4. user/dashboard preferences.

Startup fails clearly for invalid mandatory config. Optional integrations report disabled/unavailable capabilities.

9. Extensibility

Connectors implement a capability interface:

discover
health
inventory
metrics bindings
events
capabilities

No connector receives arbitrary access to core storage or bypasses authorization. Version connector contracts.

10. Architecture fitness tests

Automated tests must enforce:

• no Docker socket mount on web/API service;
• no mutation operation in public v1 API;
• migrations present for schema changes;
• OpenAPI/schema compatibility;
• package/module dependency direction;
• bounded query defaults;
• stale -> unknown mapping;
• non-root container configuration;
• secrets absent from image/repo.