# Verixa — Complete Module Specification Roadmap

**Document ID**: VRX-ROADMAP-001
**Version**: 1.0
**Date**: 2026-04-06
**Classification**: GAMP 5 Category 5 — GxP QMS SaaS
**Status**: Active

---

## Purpose

This document enumerates **every module** in the Verixa platform and assigns a specification number (VRX-SPEC-xxx). Each module will receive a combined URS + Technical Specification + Functional Specification document — the same format used for Login (VRX-SPEC-008) and E-Signature (VRX-SPEC-010).

**Source**: Audit of `packages/backend/src/modules/` (59 directories), `packages/frontend/src/pages/` (60+ pages), and `packages/shared/src/types/` (60 type files).

---

## Completed Specifications

| Spec # | Module | Status | File |
|--------|--------|--------|------|
| VRX-SPEC-007 | Persona Role Context Access Matrix | ✅ Complete | `Verixa_Persona_Role_Context_Access_Matrix.md` |
| VRX-SPEC-008 | Login & Authentication | ✅ Complete | `Verixa_Login_Module_URS_Specification.md` |
| VRX-FEAT-009 | RBAC Configurability (Future Roadmap) | ✅ Complete | `Verixa_RBAC_Configurability_Feature_future roadmap_Specification.md` |
| VRX-SPEC-010 | Electronic Signatures | ✅ Complete | `Verixa_ESignature_Module_URS_Specification.md` |
| VRX-SPEC-011 | Tenant Management | ✅ Complete | `Verixa_Tenant_Management_Module_Specification.md` |

---

## Full Module Registry (63 Modules)

### TIER 1 — Platform Foundation (8 modules)

These are the bedrock modules that every other module depends on. Must be specified first.

| Spec # | Module | Backend Path | Key Entities | Priority |
|--------|--------|-------------|--------------|----------|
| VRX-SPEC-008 | **Login & Authentication** | `auth/` | sessions, tokens, MFA, SSO, password policy, lockout | ✅ Done |
| VRX-SPEC-010 | **Electronic Signatures** | `hitl/esig.*` | electronic_signatures, esig_attempt_log, esig_meanings | ✅ Done |
| VRX-SPEC-011 | **Tenant Management** | `tenants/` | tenants, tenant_settings, tenant lifecycle (provision/suspend/archive) | ✅ Done |
| VRX-SPEC-012 | **User Management** | `users/` | users, user_roles, user_study_assignments, invitations | P0 |
| VRX-SPEC-013 | **Permissions & RBAC Engine** | `permissions/` | roles, permissions, role_permissions, permission checks | P0 |
| VRX-SPEC-014 | **Site Management** | `sites/` | sites, site_users, multi-site context switching | P0 |
| VRX-SPEC-015 | **Study Management** | `studies/` | studies, study_users, study_sites, study context (TDAL) | P0 |
| VRX-SPEC-016 | **Audit Trail** | `audit-log/` | audit_trail table, immutable append-only log, query/export | P0 |

### TIER 2 — Core QMS Event Modules (12 modules)

The primary quality event workflows. These are the modules inspectors audit first.

| Spec # | Module | Backend Path | Key Entities | Priority |
|--------|--------|-------------|--------------|----------|
| VRX-SPEC-017 | **Deviations** | `deviations/` | deviations, deviation workflow (draft→open→investigation→CAPA→closed), severity classification | P0 |
| VRX-SPEC-018 | **CAPA (Corrective & Preventive Actions)** | `capas/` | capas, capa_actions, effectiveness checks, CAPA workflow | P0 |
| VRX-SPEC-019 | **Complaints** | `complaints/` | complaints, complaint workflow, regulatory reportability, trend analysis | P0 |
| VRX-SPEC-020 | **Change Control** | `change-control/` | change_requests, impact assessments, change workflow, implementation tracking | P0 |
| VRX-SPEC-021 | **OOS/OOT Investigations** | `oos-oot/` | oos_investigations, oot_trends, Phase I/II investigation, lab retest | P0 |
| VRX-SPEC-022 | **Findings (Audit Findings)** | `findings/` | findings, finding workflow, audit association, remediation tracking | P1 |
| VRX-SPEC-023 | **Root Cause Analysis (RCA)** | `rca/` | rca_investigations, rca_methodologies (Ishikawa, 5-Why, FTA), rca_nodes | P1 |
| VRX-SPEC-024 | **Risk Assessments** | `risk-assessments/` | risk_assessments, risk_entries, risk matrices, RPN scoring, FMEA | P1 |
| VRX-SPEC-025 | **Reviews & Approvals** | `reviews/` | reviews, review_assignments, review workflow, multi-level approval | P1 |
| VRX-SPEC-026 | **Batch Records** | `batch/` | batch_records, batch_steps, batch review, disposition | P1 |
| VRX-SPEC-027 | **Inspection Readiness** | `inspection/` | inspections, inspection_items, readiness checklists, mock audit | P1 |
| VRX-SPEC-028 | **HITL Decision Engine** | `hitl/hitl.*` + `hitl/workflow-engine.*` | hitl_decisions, hitl_escalation_log, hitl_gate_config, workflow transitions | P1 |

### TIER 3 — Master Data Modules (5 modules)

Reference data that feeds into quality events.

| Spec # | Module | Backend Path | Key Entities | Priority |
|--------|--------|-------------|--------------|----------|
| VRX-SPEC-029 | **Products** | `products/` | products, product_versions, product_categories | P1 |
| VRX-SPEC-030 | **Suppliers** | `suppliers/` | suppliers, supplier_qualifications, supplier_audits, approved supplier list | P1 |
| VRX-SPEC-031 | **Environmental Monitoring** | `environmental/` | environmental_records, monitoring_locations, excursions, trending | P1 |
| VRX-SPEC-032 | **Stability Studies** | `stability/` | stability_studies, stability_samples, stability_results, shelf-life | P1 |
| VRX-SPEC-033 | **Training Management** | `training/` | training_records, training_plans, training_matrix, competency assessment | P1 |

### TIER 4 — GxP Practice Modules (5 modules)

Domain-specific quality workflows for each GxP practice area. Each is a substantial module with 5-10 sub-entity types.

| Spec # | Module | Backend Path | Key Sub-Entities | Priority |
|--------|--------|-------------|-----------------|----------|
| VRX-SPEC-034 | **GMP — Good Manufacturing Practice** | `gmp/` | manufacturing deviations, OOS investigations, batch dispositions, EM, equipment qualifications, material receipts, batch record reviews, label controls, lab samples, cleaning validations | P1 |
| VRX-SPEC-035 | **GCP — Good Clinical Practice** | `gcp/` | protocol deviations, IRB notifications, monitoring visits, sponsor reports, study sites | P2 |
| VRX-SPEC-036 | **GLP — Good Laboratory Practice** | `glp/` | study protocol deviations, data integrity deviations, specimen accountability, archive integrity, equipment deviations, environmental deviations, animal welfare deviations, dosing deviations, transfer deviations | P2 |
| VRX-SPEC-037 | **GDP — Good Distribution Practice** | `gdp/` | distribution deviations, temperature excursions, shipments, carrier qualifications, storage areas, product quarantine | P2 |
| VRX-SPEC-038 | **GVP — Good Pharmacovigilance Practice** | `gvp/` | PV deviations, QPPV notifications, signal tracking, aggregate reports (PSUR/PBRER), PV agreements, ICSR cases | P2 |

### TIER 5 — Document Management (4 modules)

Controlled document lifecycle — critical for GxP compliance.

| Spec # | Module | Backend Path | Key Entities | Priority |
|--------|--------|-------------|--------------|----------|
| VRX-SPEC-039 | **Document Control (Core DMS)** | `documents/` | documents, document_versions, document lifecycle (draft→review→approved→effective→retired) | P1 |
| VRX-SPEC-040 | **Document Library & RAG** | `document-library/` | document_library, document embeddings, RAG search, knowledge retrieval | P2 |
| VRX-SPEC-041 | **Document Review** | `document-review/` | document_reviews, review_assignments, review_comments, collaborative review | P2 |
| VRX-SPEC-042 | **Document Quality Gateway** | `document-quality-gateway/` | DQG assessments, quality scoring, compliance checks, ingest pipeline | P2 |

### TIER 6 — AI/ML Modules (7 modules)

Subject to EU Annex 22, EU AI Act, FDA CSA, and GMLP constraints. Specifications must include intended use statements, risk classification, and explainability requirements.

| Spec # | Module | Backend Path | Key Entities | Priority |
|--------|--------|-------------|--------------|----------|
| VRX-SPEC-043 | **Mira AI Copilot** | `ai/mira.*` | ai_requests, llm_audit_log, mira_contexts, copilot sessions, prompt templates | P1 |
| VRX-SPEC-044 | **AI Gateway & Model Registry** | `ai/ai-gateway.*` + `ai/model-registry.*` | ai_model_config, model versions, provider routing, rate limiting | P1 |
| VRX-SPEC-045 | **Classification AI** | `ai/classification.*` | classification_results, auto-categorization, confidence scoring | P2 |
| VRX-SPEC-046 | **Prediction Engine** | `ai/prediction.*` + `competitive/prediction-engine.*` | prediction_log, trend predictions, quality predictions, drift monitoring | P2 |
| VRX-SPEC-047 | **Scoring AI** | `scoring-ai/` | ai_scoring_results, automated risk scoring, severity prediction | P2 |
| VRX-SPEC-048 | **Agentic Panel (AI Deliberation)** | `agentic-panel/` | panel_sessions, agent_registry, deliberations, dossiers, composite scores | P2 |
| VRX-SPEC-049 | **AI Governance & LLM Audit** | `hardening/ai-governance.*` + `hardening/llm-audit.*` | llm_audit_log, model_drift alerts, bias testing, periodic reviews | P2 |

### TIER 7 — Analytics & Dashboards (5 modules)

| Spec # | Module | Backend Path | Key Entities | Priority |
|--------|--------|-------------|--------------|----------|
| VRX-SPEC-050 | **Executive & Operational Dashboards** | `dashboard/` | dashboard_configs, dashboard_alerts, KPI calculations, metric aggregations | P2 |
| VRX-SPEC-051 | **Analytics & Trend Engine** | `dashboard/analytics.*` + `dashboard/kpi-engine.*` | analytics_snapshots, trend_data, benchmarks, drill-down | P2 |
| VRX-SPEC-052 | **Scoring & SPC (Statistical Process Control)** | `scoring/` | scoring_formulas, scoring_thresholds, SPC charts, control limits | P2 |
| VRX-SPEC-053 | **Cross-Site Intelligence** | `competitive/cross-site.*` | cross_site_alerts, site_comparisons, inter-site trending | P3 |
| VRX-SPEC-054 | **Regulatory Impact Analysis** | `competitive/regulatory-impact.*` | regulatory_impacts, impact assessments, regulatory change tracking | P3 |

### TIER 8 — Configuration & Workflow Engine (6 modules)

| Spec # | Module | Backend Path | Key Entities | Priority |
|--------|--------|-------------|--------------|----------|
| VRX-SPEC-055 | **System Configuration** | `config/` | auth_config, workflow_config, module_options, config cache, provisioner | P1 |
| VRX-SPEC-056 | **Workflow Engine & Builder** | `config/workflow-builder.*` + `config/workflow-plugin.*` | workflow_definitions, workflow_states, workflow_transitions, workflow templates | P1 |
| VRX-SPEC-057 | **Context Gate (Contextual UI/Access)** | `context-gate/` | context_gate_profiles, context hierarchy, conditional field visibility | P2 |
| VRX-SPEC-058 | **Notifications & Alerts** | `notifications/` | notifications, notification_templates, email transport, event subscribers | P1 |
| VRX-SPEC-059 | **i18n (Internationalization)** | `i18n/` | translation_keys, locales, namespace management | P3 |
| VRX-SPEC-060 | **Bulk Operations** | `bulk-ops/` | bulk_jobs, batch entity operations, progress tracking | P3 |

### TIER 9 — Integrations & Connectors (4 modules)

| Spec # | Module | Backend Path | Key Entities | Priority |
|--------|--------|-------------|--------------|----------|
| VRX-SPEC-061 | **Integrations & Webhooks** | `integrations/` | integration_configs, webhook_endpoints, pipeline_events, crypto (secret management) | P2 |
| VRX-SPEC-062 | **External Connectors (Slack/Teams/Google Chat)** | `external-connectors/` | connector_configs, Slack/Teams/Google Chat adapters, webhook connectors | P3 |
| VRX-SPEC-063 | **Connector Framework** | `connector/` + `connectors/` | connector_registry, approval tokens, DLQ (dead letter queue), SoR resolver | P3 |
| VRX-SPEC-064 | **Regulatory Submissions** | `regulatory/` | regulatory_submissions, submission_documents, filing status, authority tracking | P2 |

### TIER 10 — Platform Hardening & Security (5 modules)

| Spec # | Module | Backend Path | Key Entities | Priority |
|--------|--------|-------------|--------------|----------|
| VRX-SPEC-065 | **Platform Hardening (Security)** | `platform-hardening/` | security audits, data retention policies, sanitization rules, soft-delete, tenant quotas, failed operations | P1 |
| VRX-SPEC-066 | **Regulatory Intelligence & Export** | `hardening/regulatory-intelligence.*` + `hardening/regulatory-export.*` | regulatory_alerts, compliance exports, intelligence feeds | P2 |
| VRX-SPEC-067 | **Audit Readiness & Validation** | `competitive/audit-readiness.*` + `competitive/validation.*` + `competitive/self-validation.*` | validation_plans, audit_readiness_scores, self-validation results | P2 |
| VRX-SPEC-068 | **Investigation Autopilot** | `competitive/investigation-autopilot.*` | automated investigation workflows, AI-assisted root cause, copilot-driven investigations | P3 |
| VRX-SPEC-069 | **Migration & Data Import** | `competitive/migration.*` | migration_jobs, data transformation, legacy system import | P3 |

### TIER 11 — Specialized Modules (4 modules)

| Spec # | Module | Backend Path | Key Entities | Priority |
|--------|--------|-------------|--------------|----------|
| VRX-SPEC-070 | **APQR (Annual Product Quality Review)** | `apqr/` | apqr_reports, apqr_sections, statistical summaries, trend data | P2 |
| VRX-SPEC-071 | **QA Sessions (Quality Assurance)** | `qa/` | qa_sessions, qa_checklists, qa_findings | P2 |
| VRX-SPEC-072 | **Projects** | `projects/` | projects, project_phases, project_tasks | P3 |
| VRX-SPEC-073 | **Handover Bridge** | `handover-bridge/` | handover_sessions, cascade_engine, intent_classifier, payload_transformer, handover_registry | P3 |

### TIER 12 — Infrastructure & Utilities (5 modules)

| Spec # | Module | Backend Path | Key Entities | Priority |
|--------|--------|-------------|--------------|----------|
| VRX-SPEC-074 | **Infrastructure Monitoring** | `infrastructure/` | infrastructure_metrics, health_checks, system status | P3 |
| VRX-SPEC-075 | **Screen Reader (Accessibility)** | `screen-reader/` | OCR extraction, screen reading, accessibility support | P3 |
| VRX-SPEC-076 | **WebSocket (Real-time)** | `websocket/` | ws connections, real-time events, presence tracking | P3 |
| VRX-SPEC-077 | **Health Check** | `health/` | health routes, dependency checks, readiness/liveness probes | P3 |
| VRX-SPEC-078 | **Admin Jobs** | `admin/` | background jobs, scheduled tasks, maintenance operations | P3 |

---

## Summary by Priority

| Priority | Count | Description |
|----------|-------|-------------|
| ✅ Done | 5 | VRX-SPEC-007, 008, FEAT-009, SPEC-010, SPEC-011 |
| P0 — Critical Path | 5 | Foundation modules every other module depends on (012–016) |
| P1 — Must Have | 16 | Core QMS events, master data, AI core, config, hardening (017–021, 026, 028–030, 033, 034, 039, 043–044, 055–056, 058, 065) |
| P2 — Should Have | 18 | Extended QMS, GxP practices, documents, analytics, integrations (022–025, 027, 031–032, 035–038, 040–042, 045–047, 050–052, 057, 061, 064, 066–067, 070–071) |
| P3 — Nice to Have | 15 | Utilities, connectors, specialized (048–049, 053–054, 059–060, 062–063, 068–069, 072–078) |
| **Total** | **63 + 4 done = 67** | |

---

## Recommended Specification Sequence

### Phase A — Foundation (Weeks 1–3)
Complete foundation specs so engineering has full context on platform infrastructure.

1. VRX-SPEC-011 — Tenant Management
2. VRX-SPEC-012 — User Management
3. VRX-SPEC-013 — Permissions & RBAC Engine
4. VRX-SPEC-014 — Site Management
5. VRX-SPEC-015 — Study Management
6. VRX-SPEC-016 — Audit Trail

### Phase B — Core QMS (Weeks 3–6)
The modules inspectors audit first. Critical for FDA/EMA readiness.

7. VRX-SPEC-017 — Deviations
8. VRX-SPEC-018 — CAPA
9. VRX-SPEC-019 — Complaints
10. VRX-SPEC-020 — Change Control
11. VRX-SPEC-021 — OOS/OOT

### Phase C — Workflow, Config & Notifications (Weeks 6–7)
Cross-cutting concerns that affect every QMS module.

12. VRX-SPEC-055 — System Configuration
13. VRX-SPEC-056 — Workflow Engine & Builder
14. VRX-SPEC-058 — Notifications & Alerts

### Phase D — Extended QMS (Weeks 7–10)
Second-priority quality modules.

15. VRX-SPEC-022 — Findings
16. VRX-SPEC-023 — RCA
17. VRX-SPEC-024 — Risk Assessments
18. VRX-SPEC-025 — Reviews & Approvals
19. VRX-SPEC-026 — Batch Records
20. VRX-SPEC-027 — Inspection Readiness
21. VRX-SPEC-028 — HITL Decision Engine

### Phase E — Master Data & Documents (Weeks 10–12)

22. VRX-SPEC-029 — Products
23. VRX-SPEC-030 — Suppliers
24. VRX-SPEC-031 — Environmental Monitoring
25. VRX-SPEC-032 — Stability Studies
26. VRX-SPEC-033 — Training Management
27. VRX-SPEC-039 — Document Control
28. VRX-SPEC-040 — Document Library & RAG
29. VRX-SPEC-041 — Document Review
30. VRX-SPEC-042 — Document Quality Gateway

### Phase F — GxP Practice Modules (Weeks 12–14)

31. VRX-SPEC-034 — GMP
32. VRX-SPEC-035 — GCP
33. VRX-SPEC-036 — GLP
34. VRX-SPEC-037 — GDP
35. VRX-SPEC-038 — GVP

### Phase G — AI/ML Modules (Weeks 14–16)

36. VRX-SPEC-043 — Mira AI Copilot
37. VRX-SPEC-044 — AI Gateway & Model Registry
38. VRX-SPEC-045 — Classification AI
39. VRX-SPEC-046 — Prediction Engine
40. VRX-SPEC-047 — Scoring AI
41. VRX-SPEC-048 — Agentic Panel
42. VRX-SPEC-049 — AI Governance & LLM Audit

### Phase H — Analytics, Scoring & Intelligence (Weeks 16–18)

43. VRX-SPEC-050 — Dashboards
44. VRX-SPEC-051 — Analytics & Trend Engine
45. VRX-SPEC-052 — Scoring & SPC
46. VRX-SPEC-053 — Cross-Site Intelligence
47. VRX-SPEC-054 — Regulatory Impact Analysis

### Phase I — Platform Hardening & Security (Weeks 18–19)

48. VRX-SPEC-065 — Platform Hardening
49. VRX-SPEC-066 — Regulatory Intelligence & Export
50. VRX-SPEC-067 — Audit Readiness & Validation

### Phase J — Integrations & Connectors (Weeks 19–20)

51. VRX-SPEC-061 — Integrations & Webhooks
52. VRX-SPEC-062 — External Connectors
53. VRX-SPEC-063 — Connector Framework
54. VRX-SPEC-064 — Regulatory Submissions

### Phase K — Specialized & Utilities (Weeks 20–22)

55. VRX-SPEC-057 — Context Gate
56. VRX-SPEC-059 — i18n
57. VRX-SPEC-060 — Bulk Operations
58. VRX-SPEC-068 — Investigation Autopilot
59. VRX-SPEC-069 — Migration & Data Import
60. VRX-SPEC-070 — APQR
61. VRX-SPEC-071 — QA Sessions
62. VRX-SPEC-072 — Projects
63. VRX-SPEC-073 — Handover Bridge
64. VRX-SPEC-074 — Infrastructure Monitoring
65. VRX-SPEC-075 — Screen Reader
66. VRX-SPEC-076 — WebSocket
67. VRX-SPEC-077 — Health Check
68. VRX-SPEC-078 — Admin Jobs

---

## Specification Template (Per Module)

Each module specification follows the established format from VRX-SPEC-008 (Login) and VRX-SPEC-010 (E-Signature):

1. **Header** — Document ID, version, regulatory classification, related specs
2. **Executive Summary** — Module purpose, current state, gap count
3. **URS Requirements** — Numbered URS-{MODULE}-001..N with regulatory traceability
4. **Non-Functional Requirements** — Performance, scalability, accessibility
5. **Current Implementation Audit** — What exists in code today
6. **Gap Analysis** — GAP-{ID} with severity (Critical/High/Medium/Low)
7. **Database Schema** — Tables (existing + new), columns, RLS, indexes, constraints
8. **API Specification** — Every endpoint: method, path, auth, request/response schemas
9. **Audit Trail Events** — Every logged event with what's missing
10. **Permission Strings** — RBAC permissions required
11. **Frontend Specification** — Pages, components, state management
12. **Security Threat Model** — Threats, mitigations, residual risk
13. **Remediation Plan** — Phased dev-day estimates (Pass 1.5 / 2.0 / 2.5)
14. **Appendices** — Workflow diagrams, entity type catalogs, cross-references

---

## Notes

- **Backend module count**: 59 directories in `packages/backend/src/modules/`
- **Frontend page count**: 60+ pages in `packages/frontend/src/pages/`
- **Shared type files**: 60 in `packages/shared/src/types/`
- **Shared schema files**: 43 in `packages/shared/src/schemas/`
- **Database migrations**: 94 migration files (001–094)
- Some backend modules map 1:1 to a specification (e.g., `deviations/` → VRX-SPEC-017)
- Some specifications combine multiple backend modules (e.g., VRX-SPEC-050 covers `dashboard/` services + frontend dashboard pages)
- The `competitive/` backend module contains 8 sub-services that map to 5 different specifications (053, 054, 067, 068, 069)
- GxP practice modules (GMP/GCP/GLP/GDP/GVP) each have 5–10 sub-entity types and are substantial specifications