# Verixa — User Requirements Specification

# Module 38: Quality Analytics, Dashboards & Inspection-Readiness Scorecard (NEW MODULE)

| Field | Value |
|---|---|
| Document ID | VRX-URS-38 |
| Version | 1.0 (`Draft — not validation-ready`) |
| Document Type | User Requirements Specification (URS) |
| GAMP 5 Category | Category 5 — Custom Application (read-side analytics over GxP records) |
| Origin | Pilot differentiator (no URS existed for the analytics/dashboard capability). Documents an **existing** backend module (`dashboard`) plus the new inspection-readiness scorecard. |
| Code Modules | Existing primary module `dashboard` (verified: `dashboard/routes.ts`, `analytics.routes.ts`, `kpi-engine.ts`, `metric-calculator.ts`, `analytics-aggregation.service.ts`, `industry-benchmark.service.ts`, `root-cause-clustering.service.ts`, `alert-engine.ts`, `export.service.ts`). Read-side over the QMS modules. Implementation evidence subject to repository verification. |
| Regulatory Classification | Read-side analytics / management information. **Advisory** — dashboards and scores are management-information views, NOT system-of-record; quality decisions are made in the source modules. No GxP record is created or mutated here. |
| Approving Authority | Founder / Chairman; QA Head; Validation Head |

---

## 0. Document framing

### 0.1 Purpose
Defines the target state for Verixa's **Quality Analytics, Dashboards & Inspection-Readiness Scorecard** — the read-side "state of quality" layer that aggregates KPIs, trends, ageing/overdue, CAPA-effectiveness, read-acknowledgment completion, and an **Inspection-Readiness score** across the QMS. It is a primary **pilot differentiator** ("the screen that closes deals" and the inspector-facing readiness view).

### 0.2 Plain-English
QA leaders and inspectors want one screen that answers "how healthy is our quality system right now, and are we inspection-ready?". This module reads (never writes) the deviation/CAPA/document/training/inspection records and presents KPIs, trends, overdue work, and a readiness score. Because it only reads and is **advisory management information**, it is lower-risk than the GxP record modules.

### 0.3 Scope
**In scope:** executive / tactical / operational dashboards; KPI engine + metric calculator; trend analysis; ageing/overdue across deviations, CAPAs, document reviews, training, inspection commitments; CAPA-effectiveness and deviation-recurrence trends; read-acknowledgment completion %; **Inspection-Readiness score**; configurable thresholds + alerts (`dashboard_alerts`); snapshots; controlled export of dashboards/reports; industry benchmark comparison; root-cause clustering (advisory).
**Out of scope:** the source QMS records themselves (owned by their modules); any record creation/approval/e-signature (none here); AI generation of decisions (advisory only — any AI insight is labelled + logged per URS-32).

### 0.4 GxP applicability
| Source | Applicable? | Reason |
|---|---|---|
| 21 CFR Part 11 / Annex 11 | Yes (read-side) | controlled export, access control, audit of export/config changes |
| GDocP | Yes | controlled, reproducible report/export |
| ICH Q10 §4 | Yes | management review inputs / state of quality |
| EU AI Act | Limited | only if AI-generated insights are surfaced — advisory + transparency (URS-32) |
| Security/tenant isolation | Yes | analytics must respect scope/tenant boundaries |

---

## 1. Target-state requirements register

| Req ID | Type | Requirement (`shall`) | Risk | Acceptance | Reg/QS trace | Evidence |
|---|---|---|---|---|---|---|
| AN-001 | Functional | The system **shall** provide executive / tactical / operational dashboards over the QMS, scoped per tenant and active scope (URS-03). | Med | Each dashboard renders scoped data; out-of-scope data not shown | Annex 11 §12; QS-5/6 | Built: `dashboard/routes.ts:/executive,/tactical,/operational` |
| AN-002 | Functional | The system **shall** compute KPIs and trends (ageing/overdue for deviations, CAPAs, document reviews, training, inspection commitments; CAPA-effectiveness; deviation recurrence). | Med | KPIs match source records; trend over selectable period | ICH Q10 §4 | Built: `kpi-engine.ts`, `metric-calculator.ts`, `analytics.routes.ts:/trend` |
| AN-003 | Functional | The system **shall** present an **Inspection-Readiness score** aggregating readiness signals (overdue work, open critical findings, training/read-ack completion, document currency). | High | Score is reproducible from documented inputs; drill-down to contributing records | ICH Q10; FDA inspection readiness | Partial: inspection-readiness scorecard exists; aggregate readiness score = build |
| AN-004 | Data | Dashboards **shall** be read-only over source records; the module **shall not** create or mutate any GxP record or e-signature. | High | No write path to source GxP tables from `dashboard` | QS-1; data integrity | Built (read-side) |
| AN-005 | Reporting | The system **shall** support **controlled export** of dashboards/reports (access-controlled, reproducible, integrity-stamped, with filter context + timezone). | Med | Export reproduces same data; export audited | Annex 11 §12; GDocP | Built: `dashboard/routes.ts:/export`, `export.service.ts` |
| AN-006 | Functional | The system **shall** support configurable thresholds and **alerts** on KPI breach (`dashboard_alerts`), with acknowledgment. | Med | Threshold breach raises alert; ack audited | Annex 11 §16 | Built: `alert-engine.ts`, `/alerts`, `/alerts/:id/acknowledge` |
| AN-007 | Functional | Read-acknowledgment completion % **shall** be surfaced as a KPI. | Med | reflects DOC-033 ack data | Annex 11 §4 | Depends on URS-12 DOC-033 (distribution build) |
| AN-008 | AI | Any AI-generated insight (e.g., root-cause clustering) **shall** be **advisory**, labelled, and logged per URS-32; **shall not** be a system-of-record fact. | High | AI insight labelled + logged; human interprets | EU AI Act Art.13; QS-21 | Built: `root-cause-clustering.service.ts` (confirm advisory labelling) |
| AN-009 | Functional | The system **shall** provide industry-benchmark comparison as advisory context. | Low | benchmark shown with source + caveat | — | Built: `industry-benchmark.service.ts` |
| AN-010 | Security | Analytics **shall** respect tenant isolation + scope; no cross-tenant/cross-scope aggregation without authorization. | High | scoped queries; isolation test passes | QS-5/6; Annex 11 §12 | Verify |

## 2. Workflow / data note
This is a **read-side** module: no lifecycle state machine, no e-signature, no record mutation. The "workflow" is: source modules emit/own records → analytics aggregates (cached/snapshotted) → dashboards + scorecard render → controlled export. Snapshots (`/snapshots`) provide point-in-time reproducibility.

## 3. Pilot relevance
This is the **"screen that closes deals"** and the inspector-facing readiness view. Backend is largely built; the pilot work is a **frontend readiness-scorecard view (AN-003)** tuned to the six pilot workflows, plus surfacing read-ack % (AN-007, depends on DOC-033). Lower validation burden because it is read-only advisory MI.

## 4. Inspection-readiness gate (this URS)
| Gate | Pass/Fail |
|---|---|
| Evidence map / GxP applicability | Pass |
| Requirements atomic + testable | Pass |
| No invented behavior (code cited) | Pass |
| Read-only / no GxP write asserted | Pass |
| AI advisory labelling | Pass (confirm AN-008) |

## 5. Open evidence requests
- Aggregate **Inspection-Readiness score** definition + reproducibility (AN-003).
- Read-ack % source (AN-007, DOC-033).
- AI-insight advisory labelling in root-cause clustering (AN-008).
- Tenant/scope isolation test for analytics (AN-010).

**Status:** `Draft — not validation-ready`. New module documenting an existing capability + the differentiator scorecard. Requires QMS SME + validation + QA review (§50 Tier 2). Read-only analysis; no Verixa repo files modified.

**END OF VRX-URS-38 — QUALITY ANALYTICS, DASHBOARDS & INSPECTION-READINESS SCORECARD — VERSION 1.0**