Validation
Customers operating under a quality system will validate HQ Cortex inside their own framework. This page summarizes the inputs we provide to that exercise: per-module GAMP 5 categorization, the risk-based approach we apply when changing the system, and the CSA-aligned test strategy that runs continuously against it.
This page is a living document and is updated as the product changes. For URS templates, customer-runnable IQ/OQ/PQ scripts, and per-release functional specifications, contact us through your workspace support channel.
GAMP 5 module categorization
GAMP 5 (2nd Edition) classifies software components by category to align validation rigor with risk. Most of HQ Cortex sits at Category 4 (configurable) — the same code path serves every tenant, configured per workspace through formulation versions, label profiles, and org settings.
| Module | GAMP 5 category | Rationale |
|---|---|---|
| Hosting platform (Vercel), database (PlanetScale), auth (Clerk) | Category 1 — Infrastructure | Managed services consumed without modification. Validated by provider audits and operating reliability rather than by HQ Cortex test scripts. |
| Formulation editor, batch production records, QC results, label rendering, traceability graph | Category 4 — Configurable | Customer tenants configure these workflows through formulation versions, label profiles, and org settings. Logic is shared across tenants; configuration is per tenant. |
| Org-level settings (e.g., requireApprovedSupplierCoa, requireQc) | Category 4 — Configurable | Boolean and enumerated settings that gate enforcement on a per-org basis. No bespoke code per customer. |
| AI-assisted authoring (formulation suggestions, prompt library, summarization) | Category 5 — Custom (low GxP impact) | User-invoked, optional, and not part of the regulated record path. Outputs are advisory and require user acceptance before they enter a versioned record. |
| Reporting and exports (PDF labels, BPR exports, traceability) | Category 4 — Configurable | Reusable rendering pipelines parameterized by tenant data and label profile. |
Risk-based validation approach
We apply a risk register per area of the product, with test depth scaled to product-quality and patient-safety impact. Areas with direct labeling, dosing, or release impact receive the deepest scripted coverage; advisory and informational features receive light-touch testing scaled to their real-world risk.
| Area | Patient safety | Product quality | Approach |
|---|---|---|---|
| Formulation math (% sums, basis conversion, COGS) | Indirect (incorrect dosing if formula is wrong) | High | Deterministic server-side calculation covered by unit tests; reproducible from the versioned formulation snapshot. |
| Batch lifecycle (planned → in_progress → qc_passed → released) | Indirect (release of unreviewed batch) | High | Server-side status guards on every transition; integration tests exercise the full lifecycle including QC blocking and stock ledger effects. |
| Lot traceability and stock ledger | Indirect (recall accuracy) | High | Append-only ledger with bidirectional graph queries; integration tests cover forward and reverse trace. |
| Label rendering (Supplement Facts, lot/BUD, claims) | Direct (mislabel) | High | Daily-value calculations covered by unit tests; rendered output reviewable in PDF/PNG/SVG before issue. |
| QC test capture and specification linkage | Indirect | High | Server-side schema validation, structured spec linkage, integration tests for pass/fail flagging. |
| AI-assisted authoring | None (advisory only) | Low | Output never enters a regulated record without user acceptance; surfaced as suggestion, not source of truth. |
CSA-aligned test strategy
FDA Computer Software Assurance (final guidance, September 2025) replaces a one-size-fits-all scripted-testing model with risk-based, critical-thinking-led testing. Our strategy mirrors that intent: deterministic logic is covered by unit tests; type safety and mandatory code review act as continuous controls; and exploratory testing focuses where the risk register says it should. A continuous-integration pipeline that runs the full suite on every pull request is the next investment to bring this control fully online.
Unit tests (scripted)
Deterministic logic — formulation math, daily-value calculations, status transitions, traceability — has automated unit tests that run via the project's `npm test` script. Coverage is selective and focuses on calculation-heavy and high-risk modules.
Integration tests (scripted)
Selected tRPC procedures and database flows are covered by integration tests. Full end-to-end coverage of every regulated workflow is being expanded incrementally.
Type safety and schema validation (continuous)
Strict TypeScript and per-procedure schema validation reject malformed input at the boundary, eliminating an entire class of defects without scripted tests.
Code review (gating)
Every change ships through pull request review on a protected main branch. High-risk areas (release logic, traceability, label math) require explicit reviewer attention.
Exploratory and unscripted testing (CSA-style)
Risk-based exploratory testing on workflows with patient-safety or product-quality impact. Findings are captured in issue tracking and feed back into automated tests when reproducible.
Companion pages
For the controls behind these activities — access management, audit trails, electronic record handling — see the security and compliance pages.