lmxopcua/docs/reqs/StatusDashboardReqs.md

# Status Dashboard — Component Requirements

Parent: [HLR-009](HighLevelReqs.md#hlr-009-status-dashboard)

Reference: LmxProxy Status Dashboard (see `dashboard.JPG` in project root).

## DASH-001: Embedded HTTP Endpoint

The service shall host a lightweight HTTP listener on a configurable port serving a self-contained HTML status dashboard page (no external dependencies).

### Acceptance Criteria

- Uses `System.Net.HttpListener` on a configurable port (`Dashboard:Port`, default 8081).
- Routes:
  - `GET /` → HTML dashboard
  - `GET /api/status` → JSON status report
  - `GET /api/health` → 200 OK if healthy, 503 if unhealthy
- Only GET requests accepted; other methods return 405.
- Unknown paths return 404.
- All responses include `Cache-Control: no-cache, no-store, must-revalidate` headers.
- Dashboard can be disabled via config (`Dashboard:Enabled`, default true).

### Details

- HTTP prefix: `http://+:{port}/` to bind to all interfaces.
- If HttpListener fails to start (port conflict, missing URL reservation), log Error and continue service startup without the dashboard.
- HTML page is self-contained: inline CSS, no external resources (no CDN, no JavaScript frameworks).

---

## DASH-002: Connection Panel

The dashboard shall display a Connection panel showing MXAccess connection state.

### Acceptance Criteria

- Shows: **Connected** (True/False), **State** (Connected/Disconnected/Reconnecting/Error), **Connected Since** (UTC timestamp).
- Green left border when Connected, red when Disconnected/Error, yellow when Reconnecting.
- "Connected Since" shows "N/A" when not connected.
- Data sourced from MXAccess client's connection state properties.

### Details

- Timestamp format: `yyyy-MM-dd HH:mm:ss UTC`.
- Panel title: "Connection".

---

## DASH-003: Health Panel

The dashboard shall display a Health panel showing overall service health.

### Acceptance Criteria

- Three states: **Healthy** (green text), **Degraded** (yellow text), **Unhealthy** (red text).
- Includes a health message string explaining the status.
- Health rules:
  - Not connected to MXAccess → Unhealthy
  - Success rate < 50% with > 100 total operations → Degraded
  - Connected with acceptable success rate → Healthy

### Details

- Health message examples: "LmxOpcUa is healthy", "MXAccess client is not connected", "Average success rate is below 50%".
- Green left border for Healthy, yellow for Degraded, red for Unhealthy.

---

## DASH-004: Subscriptions Panel

The dashboard shall display a Subscriptions panel showing subscription statistics.

### Acceptance Criteria

- Shows: **Clients** (connected OPC UA client count), **Tags** (total variable nodes in address space), **Active** (active MXAccess subscriptions), **Delivered** (cumulative data change notifications delivered).
- Values update on each dashboard refresh.
- Zero values shown as "0", not blank.

### Details

- "Tags" is the count of variable nodes, not object/folder nodes.
- "Active" is the count of distinct MXAccess item subscriptions (after ref-counting — the number of actual AdviseSupervisory calls, not the number of OPC UA monitored items).
- "Delivered" is a running counter since service start (not reset on reconnect).

---

## DASH-005: Operations Table

The dashboard shall display an operations metrics table showing performance statistics.

### Acceptance Criteria

- Table with columns: **Operation**, **Count**, **Success Rate**, **Avg (ms)**, **Min (ms)**, **Max (ms)**, **P95 (ms)**.
- Rows: Read, Write, Subscribe, Browse.
- Empty cells show em-dash ("—") when no data available (count = 0).
- Success rate displayed as percentage (e.g., "99.8%").
- Latency values rounded to 1 decimal place.

### Details

- Metrics sourced from the PerformanceMetrics component (1000-entry rolling buffer for percentile calculation).
- "Browse" row tracks OPC UA browse operations.
- "Subscribe" row tracks OPC UA CreateMonitoredItems operations.

---

## DASH-006: Footer

The dashboard shall display a footer with last-updated time and service identification.

### Acceptance Criteria

- Format: "Last updated: {timestamp} UTC | Service: ZB.MOM.WW.LmxOpcUa.Host v{version}".
- Timestamp is the server-side UTC time when the HTML was generated.
- Version is read from the assembly version (`Assembly.GetExecutingAssembly().GetName().Version`).

---

## DASH-007: Auto-Refresh

The dashboard page shall auto-refresh to show current status without manual reload.

### Acceptance Criteria

- HTML page includes `<meta http-equiv="refresh" content="10">` for 10-second auto-refresh.
- No JavaScript required for refresh (pure HTML meta-refresh).
- Refresh interval: configurable via `Dashboard:RefreshIntervalSeconds`, default 10 seconds.

---

## DASH-008: JSON Status API

The `/api/status` endpoint shall return a JSON object with all dashboard data for programmatic consumption.

### Acceptance Criteria

- Response Content-Type: `application/json`.
- JSON structure includes: connection state, health status, subscription statistics, and operation metrics.
- Same data as the HTML dashboard, structured for machine consumption.
- Suitable for integration with external monitoring tools.

---

## DASH-009: Galaxy Info Panel

The dashboard shall display a Galaxy Info panel showing Galaxy Repository state.

### Acceptance Criteria

- Shows: **Galaxy Name** (e.g., ZB), **DB Status** (Connected/Disconnected), **Last Deploy** (timestamp from `galaxy.time_of_last_deploy`), **Objects** (count), **Attributes** (count), **Last Rebuild** (timestamp of last address space rebuild).
- Provides visibility into the Galaxy Repository component's state independently of MXAccess connection status.

### Details

- "DB Status" reflects whether the most recent change detection poll succeeded.
- "Last Deploy" shows the raw `time_of_last_deploy` value from the Galaxy database.
- "Objects" and "Attributes" show counts from the most recent successful hierarchy/attribute query.