ITWorx-Pulse-Public/docs/product/PRODUCT_REQUIREMENTS.md

# ITWorx Pulse — Product requirements

## 1. Product statement

ITWorx Pulse is a self-hosted operational observability platform for a personal/professional Unraid environment. It combines infrastructure, container, storage, network and service health in a configurable dashboard that is easier to understand and operate than a collection of raw monitoring tools.

Pulse is not a thin Grafana theme. It owns:

- inventory and relationships;
- semantic metrics;
- dashboard composition;
- status reasoning;
- alert lifecycle;
- incident grouping;
- user experience;
- operational documentation and audit.

Prometheus-compatible systems remain the primary source of time-series history in v1.

## 2. Primary user

The primary user is a technically experienced server owner/operator who:

- manages an Unraid host with many Docker applications;
- wants one reliable status surface;
- needs detailed drill-down without constant PromQL work;
- uses desktop, mobile and a possible wallboard;
- values safe automation and read-only monitoring;
- may later link incidents to a separate management platform.

The architecture supports additional viewers/operators but v1 does not need multi-tenant SaaS behavior.

## 3. Goals

1. Determine within seconds whether the environment is healthy.
2. Explain every degraded/critical/unknown state.
3. Allow dashboards to be composed without code.
4. Show smooth live behavior and useful history.
5. Detect container, storage and service failure independently.
6. Prevent alert storms and group related failures.
7. Remain safe when telemetry is stale or unavailable.
8. Deploy without disrupting existing Unraid services.
9. Provide reproducible evidence for operation, backup and recovery.
10. Be portfolio-quality in visual, technical and operational terms.

## 4. Non-goals for v1

- General log aggregation/search platform.
- Kubernetes monitoring.
- Multi-organization SaaS.
- Automatic remediation.
- Container lifecycle management.
- Array/storage write operations.
- Public unauthenticated monitoring.
- AI-required diagnosis.
- Unlimited third-party plugin marketplace.
- Replacing Prometheus or Grafana without measured need.
- Monitoring arbitrary internet targets without an allowlist.

## 5. Functional capabilities

### 5.1 Authentication and access

- Authentik-compatible OIDC login.
- Viewer, Operator, Editor and Administrator roles.
- Disabled-by-default local break-glass recovery.
- Session expiry and logout.
- Audit for security/configuration changes.
- Wallboard uses a constrained read-only mode or authenticated session.

### 5.2 Overview

The default overview shows:

- global status and explanation;
- active incidents/alerts;
- uptime, CPU, memory and load;
- array and pool status/capacity;
- network traffic;
- container/application health;
- service reachability and latency;
- UPS when available;
- recent events;
- freshness of each source.

### 5.3 Dashboards

Users can:

- create, clone, rename, archive and delete dashboards;
- add widgets from a catalog;
- drag, resize, lock, duplicate, hide and remove widgets;
- configure data, visualization, thresholds and behavior;
- preview and edit desktop/tablet/mobile/wallboard layouts;
- use variables and cross-filtering;
- undo/redo during editing;
- save versioned revisions and restore previous versions;
- import/export validated JSON;
- use system templates;
- open widgets fullscreen and drill into entities.

### 5.4 Inventory and relationships

Pulse discovers and maintains:

- host;
- hardware and interfaces;
- array, pools, disks, filesystems and shares;
- containers, images, stacks, volumes and networks;
- applications and services;
- endpoints and certificates;
- data sources, collectors and probes;
- dependency relationships.

Every reconciled field retains source ownership and optional user override.

### 5.5 Metrics and charts

- Historical range queries.
- Live updates with bounded memory.
- Semantic metric catalog.
- Units, transformations and aggregation.
- Zoom, hover, pause, time range and compare.
- Stale/unknown representation.
- Query limits and authorization.
- CSV/image export where appropriate.
- Event annotations.

### 5.6 Alerts and incidents

- Versioned alert rules.
- Pending, firing, acknowledged and resolved lifecycle.
- Unknown, silenced, suppressed and maintenance states.
- Hysteresis, cooldown, grouping and dependency suppression.
- Notification channels with delivery audit.
- Incident creation/grouping from related alerts.
- Timeline, notes, ownership and status.
- Suggested relationships labeled as uncertain unless proven.

### 5.7 Operations

- Datasource health page.
- Self-monitoring page.
- Backup/restore.
- Config export.
- Safe deployment and rollback.
- Maintenance windows.
- Diagnostic bundle with secret redaction.
- Clear runbook.

## 6. Core user journeys

### Journey A — Morning health check

1. User opens Pulse.
2. Global state loads within the performance budget.
3. The page shows Operational or a specific explained deviation.
4. User opens an affected component from the status explanation.
5. Related graph/event context is visible without constructing a query.

### Journey B — Customize overview

1. User enters Edit mode.
2. Adds a network chart.
3. Resizes and positions it.
4. Configures the interface and time range.
5. Previews mobile layout.
6. Saves.
7. Reload preserves all layouts and version history.

### Journey C — Diagnose service failure

1. Application container remains running.
2. HTTP probe returns failure.
3. Service becomes Degraded.
4. Alert transitions pending -> firing after its duration.
5. Related container/network events appear.
6. User acknowledges the incident.
7. Recovery resolves the alert and records duration.

### Journey D — Storage risk

1. SMART/temperature or pool capacity crosses policy.
2. Pulse explains which disk/pool and why.
3. User sees current values and history.
4. No destructive storage action is offered.
5. Optional link opens an external operational workflow later.

### Journey E — Mobile incident view

1. User opens Pulse on mobile.
2. Active incident is immediately accessible.
3. Summary, affected entities, latest values and acknowledgement fit the mobile flow.
4. Complex dashboard editing is not required.

## 7. Status model

Top-level and entity status:

- `operational`
- `attention`
- `degraded`
- `critical`
- `unknown`
- `maintenance`
- `disabled`

Rules:

- `unknown` outranks a false `operational` claim when required data is stale.
- Top-level status includes a list of contributing reasons.
- Optional/non-critical component failures do not automatically become critical.
- Status aggregation is deterministic and tested.
- Color is never the only representation.

## 8. Acceptance-level non-functional requirements

- Clean build/deploy from a new checkout.
- Responsive at target scale.
- At least 17 hours of real wallboard soak without unbounded growth; the
  product owner explicitly replaced the original 24-hour duration for M10-14
  on 2026-08-11 while retaining every other performance budget.
- Graceful source disconnect/reconnect.
- No unrestricted Docker socket in API/web.
- Least privilege and non-root runtime.
- Automated accessibility checks plus keyboard flows.
- Backup/restore and upgrade/rollback.
- Secrets absent from repository, logs and evidence.
- Traceable requirement-to-test-to-evidence mapping.

## 9. Success metrics

- Time to first meaningful overview: under the defined performance budget.
- Time to identify a simulated primary fault: less than two minutes in usability validation.
- Zero false-green results in stale-source tests.
- All baseline failure scenarios detected with expected status and alert behavior.
- Dashboard configuration persists and restores across browser/server restart.
- Production deployment survives planned restart with healthy state and preserved configuration.