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:**
```sql
-- 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

```bash
# 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

```bash
# 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

```bash
# 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