# Verixa — User Requirements Specification

# Module 38: Quality Analytics, Dashboards & Inspection-Readiness Scorecard

| Field | Value |
|---|---|
| Document ID | VRX-URS-38 |
| Version | **1.1 (`Draft — not validation-ready`)** — peer-grade expansion of v1.0 per VRX-URS38-EXPANSION-001 (E-1…E-10). Authored 2026-06-07. |
| 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`: `dashboard.service.ts`, `analytics.routes.ts`, `kpi-engine.ts`, `metric-calculator.ts`, `analytics-aggregation.service.ts`, `industry-benchmark.service.ts`, `alert-engine.ts`, `export.service.ts`, `audit-registry.ts`. **Re: `root-cause-clustering.service.ts` (cited in v1.0): NOT present in `modules/dashboard/` at `dev-vimal-deploy @ d8ccdb97` — see §0.7 / AN-008.** Read-side over the QMS modules. |
| 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. |
| Code baseline (review currency) | `verixaai/verixa @ dev-vimal-deploy, d8ccdb97` (read-only, 2026-06-07). Pin to the controlled pack baseline (VRX-PACK-BASELINE-001) before freeze; deploy HEAD has since moved to `9829330b`. |
| Approving Authority | Founder / Chairman; QA Head; Validation Head |

> **Authoring note (honest provenance).** This v1.1 preserves verbatim the v1.0 substantive content (header, the AN-001…010 register, the in-scope list, and the §2–§5 notes — now §0.5, §13-source, and folded below) and **adds** the peer-grade sections E-1…E-10. v1.0 §0.1–§0.4 have since been read against the canonical v1.0 (`Target_State_URS_Modules_1-41/`); v1.1 §0.1 is consistent with v1.0 §0.1 in substance, and v1.0 §0.4 GxP applicability is preserved verbatim in §0.4A. No invented text is presented as v1.0.

---

## 0. Document Framing

### 0.1 Purpose (v1.1 — reconcile vs v1.0 §0.1 on mount recovery)
Module 38 provides **read-side quality analytics, dashboards, and an inspection-readiness scorecard** over the Verixa QMS. It aggregates records owned by the source modules (deviations, CAPAs, document control, training, inspections, etc.) into executive/tactical/operational dashboards, KPIs and trends, a configurable alerting surface, controlled exports, and a single **Inspection-Readiness score**. It is **advisory management information**: it creates and mutates **no** GxP record and signs nothing. Every quality decision is made and recorded in the source module, not here.

### 0.2 Audience
QA leadership and reviewers; validation; product; engineering; auditors and inspectors (the scorecard is inspector-facing); pilot/commercial stakeholders.

### 0.3 How to read this document
§0.5 is scope. §1 is the requirements register (AN-###), preserved from v1.0. §1A decomposes compound requirements into atomic rows. §2 is risk classification. §3 is the read-side data model and lineage. §4 is the Inspection-Readiness score definition + versioning. §5 is controlled-export integrity. §6 is AI advisory handling. §7 is cross-tenant aggregation control. §8 is ALCOA+/Part 11 applicability. §9 is cross-module wiring. §10 is the RTM. §11 is OQ acceptance (negative tests). §12 is validation readiness. Anything not evidenced in code is marked `Unknown — evidence required`.

### 0.4 Plain-language primer
A dashboard here is a **read-only window** onto data that already lives in other modules. It does not change anything; it counts, trends, and displays. The one number that matters most to a customer is the **Inspection-Readiness score** — a single roll-up of "how ready are we for an inspection right now" (overdue work, open critical findings, training/read-ack completion, document currency). Because it can influence how people act, it must be **reproducible** (you can recompute it from its inputs), **explainable** (drill down to the records behind it), and **advisory** (a human interprets it; it is not a regulated record).

### 0.4A GxP applicability (preserved verbatim from v1.0 §0.4)
| 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 |

### 0.5 Scope
**In scope (verbatim, v1.0):** 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:** creating/mutating any GxP record or e-signature (owned by the source modules URS-12…35); the source modules' own validation; the tenant-isolation architecture decision (consumed from VRX-PACK-ISO-001, not owned here).

### 0.6 Glossary
| Term | Meaning |
|---|---|
| MI | Management information — advisory views, not system-of-record |
| Snapshot | Point-in-time captured aggregation enabling reproducibility (`/snapshots`) |
| Inspection-Readiness score | Single roll-up readiness metric (AN-003) |
| Read-ack % | Document read-acknowledgment completion (depends on URS-12 DOC-033) |
| Aggregation lineage | The mapping from a displayed number back to its source records |

### 0.7 Current-state verification (`dev-vimal-deploy @ d8ccdb97`, read-only)
| Claim | Verified result |
|---|---|
| AN-004 read-only (no write to source GxP tables) | **CONFIRMED** — `dashboard` writes only to its own MI tables: `dashboard_export_log` (`export.service.ts:213`), `analytics_aggregations` (`analytics-aggregation.service.ts:86/104`), `dashboard_alerts`. No source-GxP write path. |
| AN-008 `root-cause-clustering.service.ts` exists | **NOT FOUND** at this baseline — present files: alert-engine, analytics-aggregation, analytics.routes, audit-registry, dashboard.service, export.service, industry-benchmark, kpi-engine, metric-calculator. Reclassify AN-008 evidence (see §1/§6). |
| AN-001/002/005/006/009 "Built" | Cited files present; behaviour not re-verified line-by-line — re-pin at the controlled baseline. |

---

## 1. Requirements register (AN-### — preserved from v1.0; evidence updated)

| Req ID | Type | Requirement (`shall`) | Risk | Acceptance | Reg/QS trace | Evidence (verified `d8ccdb97`) |
|---|---|---|---|---|---|---|
| AN-001 | Functional | 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: `analytics.routes.ts` / `dashboard.service.ts` |
| AN-002 | Functional | 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 | Present an **Inspection-Readiness score** aggregating readiness signals (overdue work, open critical findings, training/read-ack completion, document currency). | High | Score reproducible from documented inputs; drill-down to contributing records | ICH Q10; FDA inspection readiness | **Partial**: scorecard exists; aggregate score = build (see §4) |
| 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 — CONFIRMED read-only (§0.7)** |
| AN-005 | Reporting | 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: `export.service.ts` + `dashboard_export_log`; integrity-stamp/reproducibility = verify (§5) |
| AN-006 | Functional | 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 | Surface read-acknowledgment completion % 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; binds ARCH-AI-001 v1.0. | High | AI insight labelled + logged; human interprets | EU AI Act Art.13; QS-21; ARCH-AI-001 AC-6/AC-7 | **Cited artifact `root-cause-clustering.service.ts` ABSENT at `d8ccdb97` (§0.7).** Reclassify: feature is **target-state / unverified** at this baseline — confirm presence at the pinned baseline, then verify labelling+logging (§6) |
| AN-009 | Functional | 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** — tie to platform-scoped-RLS decision (VRX-PACK-ISO-001); OQ §11 |

## 1A. Atomic decomposition (resolves compound rows)
| Atomic ID | Requirement (`shall`) | Acceptance |
|---|---|---|
| AN-003a | Define the readiness-score **formula** (inputs + weights) as a versioned artifact | Formula version recorded; change is a controlled change |
| AN-003b | Score **recomputes identically** from a stored snapshot | Recompute = displayed score, bit-stable |
| AN-003c | Score **drills down** to each contributing source record | Every contributing record reachable from the score |
| AN-005a | Export **reproduces** identical data for the same filter context + timezone | Re-export = byte/data-identical |
| AN-005b | Export carries an **integrity stamp** + embedded filter/timezone context, and is **audited** | Integrity verifiable; `dashboard_export_log` row present |
| AN-008a | AI insight is **labelled advisory** in UI and API | Unlabelled AI insight fails |
| AN-008b | AI insight is **logged** per URS-32 (`ai_governance_events`/`llm_audit_log`, `outcome_label`) | One governance + audit entry per AI call |
| AN-010a | Every analytics/benchmark query is **tenant + scope filtered** | No cross-tenant rows in any output |
| AN-010b | Cross-tenant aggregation requires **explicit authorization** | Unauthorized cross-tenant aggregation denied |

## 2. Risk classification
| Function | Failure mode | GxP impact | Severity | Detectability | Risk | Control |
|---|---|---|---|---|---|---|
| Inspection-Readiness score (AN-003) | Non-reproducible / wrong roll-up shown to inspector | Misleads readiness decision | High | Med | **High** | Versioned formula + snapshot recompute + drill-down (§4) |
| Controlled export (AN-005) | Export not reproducible / unstamped | "True copy" doubt | Med | Med | **Med** | Integrity stamp + filter/timezone context + export audit (§5) |
| AI insight (AN-008) | Unlabelled/ unlogged AI insight treated as fact | AI-as-record-of-record | High | Low | **High** | Advisory label + URS-32 logging + ARCH-AI-001 AC-6 (§6) |
| Cross-tenant aggregation (AN-010) | Tenant A sees Tenant B data | Confidentiality / isolation breach | High | Low | **High** | Tenant+scope filter + platform-scoped RLS (VRX-PACK-ISO-001) (§7) |
| KPI/trend (AN-001/002) | KPI mismatches source | Wrong MI | Med | High | **Low–Med** | Reconciliation to source; snapshot |
| Read-ack % (AN-007) | Wrong completion % | Training MI gap | Med | Med | **Med** | Depends on DOC-033 source |

## 3. Read-side data model & lineage
Read-side only — no GxP record store. Module-owned MI tables (verified): `analytics_aggregations`, `dashboard_export_log`, `dashboard_alerts`, plus snapshots. Required model:
| Object | Purpose | Key fields | Notes |
|---|---|---|---|
| Aggregation | Cached/snapshotted roll-up over source modules | source-module refs, scope, tenant_id, computed_at | reconcilable to source |
| Snapshot | Point-in-time reproducibility | snapshot_id, inputs hash, timestamp | enables AN-003b/AN-005a |
| Score record | Inspection-Readiness score instance | formula_version, input set, value, drill-down refs | AN-003 |
| Export manifest | Controlled export descriptor | filter context, timezone, integrity stamp, exporter, time | AN-005 |
| Aggregation lineage | Number → source-record mapping | metric → contributing record IDs | AN-003c drill-down |

## 4. Inspection-Readiness score — definition & versioning (AN-003)
- The score **shall** have a documented, **versioned** formula: enumerated inputs (overdue work, open critical findings, training/read-ack completion %, document currency), weights, and normalization.
- The score **shall** be **reproducible**: recompute from the stored snapshot yields the identical value.
- The score **shall** support **drill-down** to every contributing source record.
- A formula change **shall** be a controlled change (URS-13) with the version recorded on each score record.
- Until the formula is defined + versioned, AN-003 remains **build / `Unknown — evidence required`**.

## 5. Controlled export integrity (AN-005)
- Export **shall** embed filter context + timezone, carry an **integrity stamp/hash**, restrict access, and write a `dashboard_export_log` audit row.
- Re-export of the same context **shall** reproduce identical data.
- Large-dataset and inspector-retrieval behaviour **shall** be defined.

## 6. AI advisory handling (AN-008) — binds ARCH-AI-001 v1.0
- Any AI insight (root-cause clustering or other) **shall** be **labelled advisory**, visually distinguished, **logged** per URS-32 (`ai_governance_events`/`llm_audit_log`, `outcome_label`), and **never** written to a source GxP field (ARCH-AI-001 AC-6; never the decision of record AC-7).
- **Baseline action:** `root-cause-clustering.service.ts` is absent at `d8ccdb97`. Confirm presence at the pinned baseline; if present, verify labelling + logging; if absent, AN-008 is **target-state** (build) and must not be claimed as built.

## 7. Cross-tenant aggregation control (AN-010)
- Every analytics/benchmark/score/export query **shall** be tenant- and scope-filtered; no cross-tenant aggregation without explicit authorization.
- This **shall** align with the authoritative platform-scoped-RLS decision (VRX-PACK-ISO-001); the dashboard is a **consumer** of that decision, not an owner.
- OQ negative test (§11): Tenant A cannot see Tenant B data in any dashboard, score, export, or benchmark — fails closed.

## 8. ALCOA+ / Part 11 applicability
Advisory MI is generally **supporting**, not a Part 11 record of record. However, **exports/snapshots/scores relied upon for a regulated decision or shown to an inspector** may be in scope as "true copies." Determination **shall** come from the pack-level map (VRX-PACK-PART11-MAP-001), not asserted here.
| ALCOA+ | Read-side position |
|---|---|
| Attributable | Exports/alerts attributable to actor; aggregations attributable to source |
| Legible / Available | Dashboard + controlled export |
| Contemporaneous | `computed_at` / snapshot timestamps |
| Original/Accurate | Reconciles to source; score reproducible from snapshot |
| Complete/Consistent | Snapshot + lineage; isolation-consistent |
| Enduring | Snapshot/export retention `Unknown — evidence required` (URS-35) |

## 9. Cross-module wiring
| Module | Relationship |
|---|---|
| URS-12…35 source modules | Own the records; URS-38 reads/aggregates only |
| URS-03 Context Gate | Scope filtering on every query |
| URS-12 DOC-033 | Read-ack % source (AN-007) |
| URS-32 MIRA/AI Gateway | AI insight logging (AN-008) |
| URS-22 Inspection | Scorecard feeds inspection-readiness view |
| URS-06 Audit | Export/alert audit events |
| VRX-PACK-ISO-001 | Authoritative tenant-isolation decision (consumed) |

## 10. Requirements Traceability Matrix (skeleton)
| AN / atomic ID | Risk | Design/code | Test case (OQ) |
|---|---|---|---|
| AN-003a/b/c | High | §4; score service (build) | OQ-38-03 (recompute, drill-down) |
| AN-005a/b | Med | `export.service.ts` | OQ-38-05 (reproduce, integrity, audit) |
| AN-008a/b | High | AI service (verify/build) | OQ-38-08 (label, log, no-record-write) |
| AN-010a/b | High | scoped queries + RLS | OQ-38-10 (Tenant A/B negative) |
| AN-004 | High | read-side | OQ-38-04 (no source write) |
| AN-001/002/006/007/009 | Med/Low | built services | OQ-38-01/02/06/07/09 |

## 11. OQ acceptance — negative tests (mandatory)
- **Cross-tenant (AN-010):** Tenant A cannot read/aggregate Tenant B data in any dashboard/score/export/benchmark — fails closed.
- **Score reproducibility (AN-003b):** recompute from snapshot ≠ displayed → fail.
- **Export reproducibility/integrity (AN-005):** re-export mismatch or missing integrity stamp → fail.
- **AI advisory (AN-008):** an unlabelled or unlogged AI insight → fail; no AI write to a source GxP field.
- **Read-only (AN-004):** any write attempt to a source GxP table from `dashboard` → fail.

## 12. Validation readiness (this URS)
| Gate | Result |
|---|---|
| Requirements atomic + testable | **Pass** (§1A) |
| Risk classification present | **Pass** (§2) |
| Data model + lineage | **Pass** (§3) |
| Score definition + versioning | **Defined as requirement** (§4); formula `Unknown — evidence required` until authored |
| Export integrity rules | **Pass** (§5); reproducibility/stamp = verify |
| AI advisory labelling + logging | **Open** — artifact absent at baseline (§6) |
| Cross-tenant control | **Open** — pending VRX-PACK-ISO-001 decision (§7) |
| ALCOA+/Part 11 applicability | **Assessed** (§8); determination from pack map |
| RTM | **Skeleton present** (§10) |
| OQ negative tests | **Defined** (§11); not executed |
| Baseline pin | **Pending** (VRX-PACK-BASELINE-001) |
| Overall | **`Draft — not validation-ready`.** Peer-grade structure now present; residual: score formula, AN-008 baseline, AN-010 isolation decision, baseline pin, OQ execution. |

## 13. Change history
| Version | Date | Change |
|---|---|---|
| 1.0 | (v1.0 issue) | Initial — 79-line read-side analytics + scorecard URS (AN-001…010). |
| 1.1 | 2026-06-07 | Peer-grade expansion per VRX-URS38-EXPANSION-001 (E-1…E-10): added framing, atomic decomposition (§1A), risk classification (§2), data model/lineage (§3), score definition+versioning (§4), export integrity (§5), AI advisory handling (§6), cross-tenant control (§7), ALCOA+/Part 11 (§8), wiring (§9), RTM (§10), OQ negative tests (§11), validation readiness (§12). Verified current-state at `d8ccdb97`: AN-004 read-only confirmed; AN-008 clustering artifact absent (reclassified). v1.0 §0.1 purpose prose to be reconciled verbatim on mount recovery. |

| Boundary Check | Result |
|---|---|
| Primary skill | URS authoring + CSV/CSA structure + DI (export/record) + AI Governance (AN-008) |
| Owned deliverable | URS-38 v1.1 peer-grade target-state spec (draft) |
| Out-of-scope (deferred) | Tenant-isolation decision → VRX-PACK-ISO-001 owners; Part 11 determination → pack map; OQ protocols → Test Architect; final approval → Head of QA |
| Repo | Read-only; verified, not modified |
| Final status | `Draft — not validation-ready`; Head of QA review required; reconcile §0.1 vs v1.0 on mount recovery |

*Status: `Draft — not validation-ready`. New version expanding an existing thin URS to peer grade. Read-only analysis; no Verixa repo files modified.*