clqms-be/PRD.md

CLQMS Product Requirements Document

Clinical Laboratory Quality Management System - Minimum Viable Product

Version: 1.0 Last Updated: 2026-01-28

---

1. Executive Summary

CLQMS is a REST API backend for a Clinical Laboratory Quality Management System designed to manage the complete laboratory workflow from order creation to result reporting. The system integrates with laboratory instruments via the Edge API and provides comprehensive specimen tracking, result management, and quality control capabilities.

Product Vision

To provide a headless, API-first laboratory information system that serves as the backend for any frontend client (web, mobile, desktop) while streamlining laboratory operations, ensuring regulatory compliance, and integrating seamlessly with laboratory instruments.

Core Value Propositions

• API-First Design: Pure REST API with comprehensive endpoints for all laboratory operations
• Complete Workflow Coverage: Order → Collection → Reception → Preparation → Analysis → Verification → Review → Reporting
• Instrument Integration: Standard Edge API for bidirectional communication with laboratory analyzers
• Quality Management: Built-in QC, calibration tracking, and audit trails
• Modern Architecture: RESTful API, JWT authentication, UTC timestamp normalization
• Frontend Agnostic: No view layer - clients consume JSON API responses

---

2. Product Goals

MVP Success Criteria

Goal	Description	Success Metric
Patient Registration	Register patients with demographics	Patient can be created and retrieved
Test Ordering	Generate valid order IDs and test mappings	Order ID format: LLYYMMDDXXXXX
Specimen Tracking	Track specimens through entire lifecycle	Status updates: Collection→Transport→Reception→Prep→Analysis
Result Entry	Enter results with reference range validation	Numeric, text, valueset, and range results supported
Result Verification	Multi-level verification workflow	VER → REV → REP status tracking
Instrument Integration	Receive results via Edge API	Results stored and processed to patient results
Master Data Management	Complete lookup and reference data	All value sets and test definitions manageable

---

3. Target Users

API Consumers

Consumer Type	Description	Key API Needs
Frontend Applications	Web apps, mobile apps, desktop clients consuming the API	Full CRUD operations, authentication, real-time updates
Laboratory Instruments	Analyzers and middleware systems	Edge API for orders/results, status monitoring
Third-Party Systems	HIS, EMR, billing systems	Patient data sync, order/results integration
Integration Partners	External lab networks, reference labs	Order referral, result reporting APIs

API Client Types

• Web Clients: Single-page applications (React, Vue, Angular) consuming REST endpoints
• Mobile Clients: iOS/Android apps for mobile laboratory workflows
• Desktop Clients: Native applications for result entry and verification
• Middleware Systems: Instrument integration layer (tiny-edge)
• Batch Processors: Scheduled jobs, data import/export utilities

---

4. Functional Requirements

4.1 Priority Framework

Priority	Definition	Timeline
P0	Must-have for MVP	Phase 1
P1	Should-have for MVP	Phase 2
P2	Nice-to-have for production	Phase 3
P3	Future enhancement	Phase 4+

4.2 Master Data Requirements (P0 - Foundation)

Rationale: All transactional API workflows depend on complete master data. Master data must be completed before order/test/result API operations can function properly.

4.2.1 Value Sets & Lookups ✅

Requirement	Description	Status
VS-001	Value set definitions management	Complete
VS-002	Value set values management	Complete
VS-003	JSON-based static lookup system	Complete
VS-004	Lookup caching for performance	Complete

Key Value Sets:

• Demographics: sex, marital_status, race, ethnic
• Orders: order_status, order_priority, priority
• Specimens: specimen_type, specimen_status, specimen_condition
• Results: result_type, result_status, result_unit
• Organizations: site_type, location_type
• Technical: test_type, unit, formula_language

4.2.2 Test Definitions ✅

Requirement	Description	Status
TD-001	Test site definitions (testdefsite)	Complete
TD-002	Technical specifications (testdeftech)	Complete
TD-003	Calculated test formulas (testdefcal)	Complete
TD-004	Test groups/panels (testdefgrp)	Complete
TD-005	Test parameters	Complete
TD-006	Instrument test mapping (testmap)	Complete

Test Types Supported:

Code	Type	Description
TEST	Technical	Individual lab test with specs
PARAM	Parameter	Non-lab measurement
CALC	Calculated	Test with formula
GROUP	Panel/Profile	Contains multiple tests
TITLE	Section	Report organization header

4.2.3 Reference Ranges ⚠️

Requirement	Description	Status
RR-001	Numeric reference ranges (refnum)	Complete
RR-002	Threshold ranges (refthold)	Missing migration
RR-003	Text reference ranges (reftxt)	Complete
RR-004	Value set reference ranges (refvset)	Missing migration
RR-005	Age/sex-based criteria	Complete (refnum)
RR-006	Critical value flagging	Needs implementation

Gap Analysis: Missing database migrations for refthold and refvset tables.

4.2.4 Organization Structure ✅

Requirement	Description	Status
ORG-001	Account management	Complete
ORG-002	Site management	Complete
ORG-003	Location management	Complete
ORG-004	Discipline management	Complete
ORG-005	Department management	Complete
ORG-006	Workstation management	Complete

4.2.5 Specimen Types ✅

Requirement	Description	Status
SPEC-001	Container definitions (containerdef)	Complete
SPEC-002	Specimen type catalog	Complete
SPEC-003	Collection methods	Complete
SPEC-004	Container classes and sizes	Complete

4.3 Order Management (P0)

Requirement	Description	Acceptance Criteria
ORD-001	Create order with patient linkage	OrderID generated in LLYYMMDDXXXXX format
ORD-002	Update order details	All fields editable before verification
ORD-003	Delete order (soft delete)	DelDate set, order not displayed
ORD-004	Order status tracking	ORD → SCH → ANA → VER → REV → REP
ORD-005	Priority assignment	Stat/Routine/ASAP
ORD-006	Order attachment handling	Support for ordercom, orderatt tables
ORD-007	Test-to-order mapping	Multiple tests per order
ORD-008	Calculated test auto-selection	Parameters auto-added based on formulas
ORD-009	Provider identification	Ordering provider captured
ORD-010	Order date/time tracking	UTC timestamps normalized

Minimum Data Required for Order Creation:

-- Patient (at least 1 required)
-- Order Status values (VSetID=11): ORD, SCH, ANA, VER, REV, REP
-- Priority values (VSetID=10): S, R, A
-- Counter for Order ID generation

4.4 Specimen Management (P0)

Requirement	Description	Acceptance Criteria
SPM-001	Create specimen from order	SpecimenID = OrderID + SSS + C
SPM-002	Collection status	Specimen marked as collected
SPM-003	In-transit status	Track specimen transport
SPM-004	Reception	Received or Rejected status
SPM-005	Preparation	Centrifuge, Aliquot, Pre-treatment
SPM-006	Storage	Stored status with location
SPM-007	Dispatch	Dispatch status for referral
SPM-008	Condition tracking	HEM, ITC, LIP flag support
SPM-009	Activity logging	Full audit trail via specmenactivity
SPM-010	Specimen-test linking	Tests mapped to specimens

Specimen ID Format: OrderID + SpecimenTypeCode(3) + ContainerCode(1)

Specimen Conditions:

Code	Description
HEM	Hemolysis
ITC	Insufficient
LIP	Lipemic

4.5 Result Management (P0)

Requirement	Description	Acceptance Criteria
RES-001	Numeric result entry	Value with unit, range validation
RES-002	Text result entry	Free text or coded values
RES-003	Value set result entry	Dropdown selection from valueset
RES-004	Range result entry	Min/max with reference
RES-005	Reference range validation	Auto-flag abnormal results
RES-006	Critical value flagging	Threshold-based alerts
RES-007	Result verification (Technical)	First-level verification (VER status)
RES-008	Result verification (Clinical)	Pathologist review (REV status)
RES-009	Result reporting	Final report status (REP)
RES-010	Result rerun	AspCnt tracking for reruns
RES-011	Result comments	Support for patresultcomment
RES-012	Result details	Multiple details per result (patresultdetail)

Result Verification Workflow:

Entry → VER (Technical) → REV (Clinical) → REP (Reported)

4.6 Patient Visit (P1)

Requirement	Description	Acceptance Criteria
VIS-001	Create patient visit	Visit linked to patient
VIS-002	Visit-to-order linkage	Orders associated with visits
VIS-003	ADT tracking	Admission, Discharge, Transfer
VIS-004	Diagnosis linking	patdiag table support
VIS-005	Insurance tracking	patinsurance table support

4.7 Instrument Integration (P1)

Requirement	Description	Acceptance Criteria
EDGE-001	Receive instrument results	POST /api/edge/results
EDGE-002	Store raw results	edgeres table
EDGE-003	Status logging	edgestatus tracking
EDGE-004	Order acknowledgment	edgeack confirmation
EDGE-005	Fetch pending orders	GET /api/edge/orders
EDGE-006	Acknowledge order delivery	POST /api/edge/orders/:id/ack
EDGE-007	Instrument status updates	POST /api/edge/status

Edge API Flow:

Instrument → tiny-edge → /api/edge/results → edgeres table → Processing → patresult table

4.8 Quality Control (P2)

Requirement	Description	Acceptance Criteria
QC-001	QC result entry	calres table storage
QC-002	Levey-Jennings data	Data preparation endpoints
QC-003	QC validation	2SD auto-validation rules
QC-004	Sigma metrics	Calculation endpoint
QC-005	QC history	Trend analysis support

4.9 Calibration (P2)

Requirement	Description	Acceptance Criteria
CAL-001	Calibration result entry	Factor tracking
CAL-002	Calibration history	Historical query endpoint
CAL-003	Calibration validation	Rule-based validation

4.10 Audit Trail (P2)

Requirement	Description	Acceptance Criteria
AUD-001	Audit logging middleware	Automatic change capture
AUD-002	What/who/when tracking	Complete change record
AUD-003	Security logging	Authentication attempts
AUD-004	Audit query endpoint	Searchable audit logs

4.11 Inventory & Billing (P3)

Requirement	Description	Acceptance Criteria
INV-001	Counter management	ORDER, SID, etc.
INV-002	Product catalog	Reagents, consumables
INV-003	Reagent tracking	Lot numbers, expiration
INV-004	Consumables usage	Usage logging
INV-005	Billing export	Tariff-based billing
INV-006	Service class selection	Billing tiers

---

5. Non-Functional Requirements

5.1 Security

Requirement	Description
AUTH-001	JWT-based authentication for all API endpoints
AUTH-002	Role-based access control (RBAC)
AUTH-003	Password hashing with bcrypt
AUTH-004	Login attempt tracking
AUTH-005	Device registration (userdevices)

5.2 Data Integrity

Requirement	Description
DATA-001	Soft delete (DelDate) on all transactional tables
DATA-002	UTC timezone normalization for all datetime fields
DATA-003	Automatic date conversion (UTC ↔ ISO 8601)
DATA-004	Referential integrity via foreign keys
DATA-005	Transactional data consistency

5.3 Performance

Requirement	Description	Target
PERF-001	Standard query response time	< 2 seconds
PERF-002	API endpoint latency	< 500ms (p95)
PERF-003	Lookup cache hit rate	> 95%
PERF-004	Database indexing	All foreign keys indexed

5.4 Reliability

Requirement	Description
REL-001	Graceful error handling
REL-002	Database transaction support
REL-003	API rate limiting
REL-004	Request validation

5.5 Maintainability

Requirement	Description
MAIN-001	PSR-12 coding standards
MAIN-002	RESTful API design
MAIN-003	Comprehensive documentation
MAIN-004	Unit test coverage > 80%
MAIN-005	Migration-based schema management

---

6. API Workflow Examples

6.1 Core Laboratory API Workflow

POST /api/patient           → Create patient
POST /api/ordertest         → Create order with tests
POST /api/specimen          → Create specimen from order
PATCH /api/specimen/status  → Update specimen status
POST /api/patresult         → Enter results
PATCH /api/patresult/status → Verify results (VER → REV → REP)
GET  /api/patresult/:id     → Retrieve final report

6.2 Order Creation API Sequence

# 1. Create/Register Patient
POST /api/patient
{
  "NameFirst": "John",
  "NameLast": "Doe",
  "Sex": "1",
  "Birthdate": "1990-05-15"
}
# Response: { "InternalPID": 123, "PatientID": "PT001" }

# 2. Create Order with Tests
POST /api/ordertest
{
  "InternalPID": 123,
  "Priority": "R",
  "OrderingProvider": "Dr. Smith",
  "Tests": [{ "TestID": 10 }, { "TestID": 15 }]
}
# Response: { "OrderID": "00250112000001", "OrderStatus": "ORD" }

# 3. Create Specimens (if applicable)
POST /api/specimen
{
  "OrderID": "00250112000001",
  "SpecimenType": "BLD",
  "SpecimenStatus": "COLLECTED"
}
# Response: { "SID": "00250112000001BLDA" }

6.3 Result Entry & Verification API Sequence

# 1. Enter Results
POST /api/patresult
{
  "OrderID": "00250112000001",
  "TestID": 10,
  "ResultValue": "5.2",
  "ResultUnit": "g/dL",
  "ResultStatus": "ENTRY"
}

# 2. Technical Verification
PATCH /api/patresult/status
{
  "ResultID": 456,
  "ResultStatus": "VER",
  "VerifierID": 7
}

# 3. Clinical Review
PATCH /api/patresult/status
{
  "ResultID": 456,
  "ResultStatus": "REV",
  "VerifierID": 8
}

# 4. Report Finalization
PATCH /api/patresult/status
{
  "ResultID": 456,
  "ResultStatus": "REP"
}

6.4 Instrument Integration API Workflow

# 1. Fetch Pending Orders for Instrument
GET /api/edge/orders?instrument=coulter_counter

# 2. Instrument Acknowledges Order
POST /api/edge/orders/123/ack

# 3. Instrument Sends Results
POST /api/edge/results
{
  "SampleID": "00250112000001",
  "Results": [
    { "TestCode": "HGB", "Value": "14.5", "Unit": "g/dL" },
    { "TestCode": "WBC", "Value": "7.2", "Unit": "x10^9/L" }
  ]
}

# 4. System Processes Results (automatic or manual)
# Results stored in edgeres → processed to patresult

---

7. Technical Architecture

7.1 Technology Stack

Layer	Technology	Version
Backend	PHP	8.1+
Framework	CodeIgniter	4.x
Database	MySQL	8.0+
Authentication	JWT (firebase/php-jwt)	Latest
Testing	PHPUnit	10.5+
API Format	JSON	RESTful

7.2 Architecture Pattern

┌─────────────────────────────────────────────────────────┐
│                   API Consumers                         │
│  (Web Apps, Mobile Apps, Desktop Clients, Instruments)  │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP/HTTPS (JSON)
┌────────────────────┴────────────────────────────────────┐
│                   REST API Layer                         │
│  (Controllers: Patient, Order, Specimen, Result, etc.)  │
│  - JWT Authentication Filter                            │
│  - Request Validation                                   │
│  - Response Formatting                                  │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────┐
│                   Business Logic Layer                   │
│              (Models + Libraries + Services)            │
│  - ValueSet Library (JSON-based lookups)                │
│  - Base Model (UTC normalization)                       │
│  - Edge Processing Service                              │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────┐
│                   Data Access Layer                      │
│              (CodeIgniter Query Builder)                 │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────┐
│                   MySQL Database                         │
│           (Migration-managed schema)                     │
└─────────────────────────────────────────────────────────┘

7.3 API Design Principles

Principle	Implementation
Resource-Based	URLs represent resources (patients, orders, specimens)
HTTP Methods	GET (read), POST (create), PATCH (update), DELETE (soft delete)
Stateless	Each request contains all necessary context (JWT token)
JSON Responses	All API responses use consistent JSON format
Versioning	API versioning via URL prefix (/api/v1/, /api/v2/)
Error Handling	Standardized error responses with status codes
Pagination	List endpoints support pagination parameters

7.3 Database Schema

Core Transaction Tables:

Table	Purpose	Key Fields
patient	Patient registry	InternalPID, PatientID, NameFirst, NameLast, Sex, Birthdate
porder	Laboratory orders	OrderID, InternalPID, OrderStatus, Priority

| specimen | Specimens | SID, SpecimenID, SpecimenStatus | | patresult | Patient results | ResultID, OrderID, TestID, ResultValue | | patresultdetail | Result details | ResultID, ParameterID, Value |

Master Data Tables:

Table	Purpose
valueset	Static lookup values
valuesetdef	Value set definitions
testdefsite	Test definitions by site
testdeftech	Technical test specifications
testdefcal	Calculated test formulas
testdefgrp	Test groups/panels
refnum	Numeric reference ranges
reftxt	Text reference ranges

Integration Tables:

Table	Purpose
edgeres	Raw instrument results
edgestatus	Instrument status
edgeack	Order acknowledgment

7.4 API Specifications

Authentication Endpoint:

POST /api/login
Request: { "username": "...", "password": "..." }
Response: { "token": "jwt-token", "expires": 3600 }

Demo Order Endpoint (No Auth):

POST /api/demo/order
Request: {
  "PatientID": "PT001",
  "NameFirst": "John",
  "NameLast": "Doe",
  "Sex": "1",
  "Birthdate": "1990-05-15",
  "Priority": "R",
  "OrderingProvider": "Dr. Smith"
}
Response: {
  "status": "success",
  "data": {
    "PatientID": "DEMO1736689600",
    "InternalPID": 1,
    "OrderID": "00250112000001",
    "OrderStatus": "ORD"
  }
}

Order Endpoints:

GET    /api/ordertest        - List orders
POST   /api/ordertest        - Create order
GET    /api/ordertest/:id    - Get order
PUT    /api/ordertest/:id    - Update order
DELETE /api/ordertest/:id    - Delete order
POST   /api/ordertest/status - Update status

Edge API Endpoints:

POST /api/edge/results         - Receive results
GET  /api/edge/orders          - Fetch pending orders
POST /api/edge/orders/:id/ack  - Acknowledge order
POST /api/edge/status          - Log status

---

8. Implementation Roadmap

Phase 0: Master Data Completion (P0)

Prerequisite: All master data must be complete before transactional workflows

Task	Effort	Dependencies
Complete reference range migrations	2 days	None
Create reference range CRUD controllers	3 days	Migrations
Verify all value sets populated	1 day	None
Complete test definitions data entry	2 days	None
Total	8 days	-

Phase 1: Core Lab Workflow (P0)

Task	Effort	Dependencies
Order CRUD complete	5 days	Phase 0
Order ID generation	2 days	Order CRUD
Order status tracking	2 days	Order CRUD
Specimen API complete	5 days	Phase 0
Specimen status workflow	3 days	Specimen API
Result CRUD	5 days	Phase 0
Result entry with validation	4 days	Result CRUD
Result verification workflow	4 days	Result CRUD
Result report generation	3 days	Result verification
Total	33 days	Phase 0

Phase 2: Instrument Integration (P1)

Task	Effort	Dependencies
Edge API results endpoint	4 days	Phase 1
Edge API orders endpoint	3 days	Phase 1
Test mapping management	3 days	Phase 0
Order acknowledgment	2 days	Edge orders
Status logging	2 days	Edge results
Total	14 days	Phase 1

Phase 3: Quality Management (P2)

Task	Effort	Dependencies
QC result entry	4 days	Phase 2
QC validation rules	3 days	QC entry
Calibration tracking	3 days	None
Audit trail implementation	5 days	Phase 1
Total	15 days	Phase 2

Phase 4: Additional Features (P3)

Task	Effort	Dependencies
Inventory management	8 days	None
Billing integration	6 days	Phase 1
Advanced reporting	5 days	Phase 1
Total	19 days	Phase 1

Total MVP Timeline: ~89 days (~4 months)

• Phase 0: 2 weeks
• Phase 1: 7 weeks
• Phase 2: 3 weeks
• Phase 3: 3 weeks
• Phase 4: 4 weeks

---

9. Success Criteria

9.1 API Endpoint Acceptance

A REST API endpoint is considered complete when:

• HTTP methods implemented (GET, POST, PATCH, DELETE)
• Request validation implemented (input sanitization, type checking)
• JSON response format consistent with API standards
• Error responses include status code and error message
• JWT authentication/authorization configured
• Soft delete implemented (where applicable)
• UTC date normalization working
• Unit tests written (PHPUnit)
• API documented (request/response examples)
• Pagination support (list endpoints)
• Filtering/sorting support (where applicable)

9.2 MVP Definition of Done

The MVP is considered complete when:

1. ✅ Patient can be registered and retrieved
2. ✅ Order can be created with valid OrderID
3. ✅ Specimen can be tracked through all statuses
4. ✅ Results can be entered with range validation
5. ✅ Results can be verified (VER → REV → REP)
6. ✅ Instruments can send results via Edge API
7. ✅ All master data is manageable
8. ✅ JWT authentication protects all endpoints
9. ✅ Soft delete works on all transactions
10. ✅ UTC timestamps are normalized

9.3 Performance Benchmarks

Metric	Target	Measurement
API response time (p95)	< 500ms	Apache Bench
Database query time	< 200ms	EXPLAIN analysis
Lookup cache hit rate	> 95%	Application metrics
Test coverage	> 80%	PHPUnit --coverage

---

10. Open Questions & Risks

10.1 Open Questions

Question	Impact	Target Date

| Multi-site deployment requirements? | High | Phase 0 | | Specific instrument integrations needed? | High | Phase 2 | | Report format requirements (PDF/HTML)? | Medium | Phase 1 | | HL7/FHIR integration requirements? | Low | Phase 4 |

10.2 Technical Risks

Risk	Probability	Impact	Mitigation
Edge API protocol mismatches	Medium	High	Early instrument testing
Reference range complexity	Low	Medium	Start with refnum only
Performance at scale	Low	Medium	Database indexing, caching
Test definition data entry	High	Medium	Provide templates/bulk import

10.3 Business Risks

Risk	Probability	Impact	Mitigation
Scope creep	High	High	Strict MVP definition
Resource constraints	Medium	High	Phased delivery
Instrument compatibility	Medium	High	Edge API abstraction layer

---

11. Appendix

11.1 Glossary

Term	Definition
OrderID	Laboratory order identifier: LLYYMMDDXXXXX (Lab+Date+Sequence)
SID	Specimen identifier: OrderID + SpecimenType + Container
VSetID	Value set definition ID
VID	Value set value ID
Edge API	Standardized interface for laboratory instrument integration
ADT	Admission, Discharge, Transfer
QC	Quality Control
LLYYMMDD	Lab location (LL) + Year (YY) + Month (MM) + Day (DD)
UTC	Coordinated Universal Time

11.2 Reference Documents

Document	Location
Technical Architecture	CLAUDE.md
Implementation Tasks	TODO.md
API Documentation	README.md
Database Migrations	app/Database/Migrations/

11.3 Revision History

Version	Date	Author	Changes
1.0	2026-01-28	Claude	Initial PRD from TODO.md

---

Document Status: Draft for Review Next Review: Upon Phase 0 completion Approvals: Pending