clqms-be/README.md

# CLQMS (Clinical Laboratory Quality Management System)

> **The core backend engine for modern clinical laboratory workflows.**

CLQMS is a robust, mission-critical API suite designed to streamline laboratory operations, ensure data integrity, and manage complex diagnostic workflows. Built on a foundation of precision and regulatory compliance, this system handles everything from patient registration to high-throughput test resulting.

---

## 🏛️ Core Architecture & Design

The system is currently undergoing a strategic **Architectural Redesign** to consolidate legacy structures into a high-performance, maintainable schema. This design, spearheaded by leadership, focuses on reducing technical debt and improving data consistency across:

- **Unified Test Definitions:** Consolidating technical, calculated, and site-specific test data.
- **Reference Range Centralization:** A unified engine for numeric, threshold, text, and coded results.
- **Ordered Workflow Management:** Precise tracking of orders from collection to verification.

---

## 🛡️ Strategic Pillars

- **Precision & Accuracy:** Strict validation for all laboratory parameters and reference ranges.
- **Scalability:** Optimized for high-volume diagnostic environments.
- **Compliance:** Built-in audit trails and status history for full traceability.
- **Interoperability:** Modular architecture designed for LIS, HIS, and analyzer integrations.

---

## 🛠️ Technical Stack

| Component      | Specification |
| :------------- | :------------ |
| **Language**   | PHP 8.1+ (PSR-compliant) |
| **Framework**  | CodeIgniter 4 |
| **Security**   | JWT (JSON Web Tokens) Authorization |
| **Database**   | MySQL (Optimized Schema Migration in progress) |


---

## 📂 Documentation & Specifications

For detailed architectural blueprints and API specifications, please refer to the internal documentation:

👉 **[Internal Documentation Index](./docs/README.md)**

Key documents:
- [Database Schema Redesign Proposal](./docs/20251216002-Test_OrderTest_RefRange_schema_redesign_proposal.md)
- [API Contract: Patient Registration](./docs/api_contract_patient_registration.md)
- [Database Design Review (Reference)](./docs/20251212001-database_design_review_sonnet.md)

---

## 🔧 Valueset Reference (VSetDefID)

When working on UI components or dropdowns, **always check for existing ValueSets** before hardcoding options. Use the API endpoint `/api/valueset/valuesetdef/{ID}` to fetch options dynamically.

| VSetDefID | Purpose | Usage |
|-----------|---------|-------|
| 27 | Test Types | TEST, PARAM, GROUP, CALC, TITLE |
| 28 | Methods | Lab test methods |
| 29 | Specimen Types | Blood, Urine, etc. |
| 30 | Ref Types | NMRC (Numeric), TEXT, LIST |
| 31 | Range Types | STD (Standard), AGSX (Age/Sex), COND |

> **Important:** Always use ValueSet lookups for configurable options. This ensures consistency and allows administrators to modify options without code changes.

---

## 📚 Static Lookups Library (`app/Libraries/Lookups.php`)

For frequently used lookup values, CLQMS provides a **static library** with all values hardcoded. This eliminates database queries for common dropdowns and improves performance.

### Available Lookups

| Constant | VSetID | Description |
|----------|--------|-------------|
| `WS_TYPE` | 1 | Workstation type (Primary, Secondary) |
| `ENABLE_DISABLE` | 2 | Enable/disable flags |
| `GENDER` | 3 | Gender (Female, Male, Unknown) |
| `MARITAL_STATUS` | 4 | Marital status (A/D/M/S/W/B/U/O) |
| `DEATH_INDICATOR` | 5 | Death indicator (Y/N) |
| `IDENTIFIER_TYPE` | 6 | ID types (KTP, Passport, SSN, SIM) |
| `OPERATION` | 7 | CRUD operations (Create, Read, Update, Delete) |
| `ORDER_PRIORITY` | 10 | Order priority (S=Stat, A=ASAP, R=Routine, P=Preop, etc.) |
| `ORDER_STATUS` | 11 | Order status (A/CA/CM/DC/ER/HD/IP/RP/SC/CL/AC/DL) |
| `SPECIMEN_TYPE` | 15 | Specimen types (BLD, SER, PLAS, UR, CSF, etc.) |
| `SPECIMEN_STATUS` | 20 | Specimen status (STC, SCtd, SArrv, SRcvd, SAna, etc.) |
| `SPECIMEN_CONDITION` | 21 | Specimen condition (HEM, ITC, LIP, etc.) |
| `TEST_TYPE` | 27 | Test types (TEST, PARAM, CALC, GROUP, TITLE) |
| `RESULT_UNIT` | 28 | Result units (g/dL, mg/dL, x10^6/mL, etc.) |
| `RACE` | 30 | Ethnicity/race (Jawa, Sunda, Batak, etc.) |
| `RELIGION` | 31 | Religion (Islam, Kristen, Katolik, Hindu, Budha, etc.) |
| `SITE_TYPE` | 37 | Site type (GH, PH, GHL, PHL, GL, PL) |
| `SITE_CLASS` | 38 | Site class (A/B/C/D/Utm/Ptm) |
| `RESULT_TYPE` | 43 | Result type (NMRIC, RANGE, TEXT, VSET) |
| `RANGE_TYPE` | 45 | Range type (REF, CRTC, VAL, RERUN) |
| `HIV_RESULT` | 1001 | HIV results (NEG, POS, GZ) |

**Plus 25+ more categories** - see [`app/Libraries/Lookups.php`](app/Libraries/Lookups.php) for complete list.

### Usage

```php
use App\Libraries\Lookups;

// Get all lookups formatted for frontend
$allLookups = Lookups::getAll();

// Get single lookup (returns [{value: 'X', label: 'Y'}, ...])
$gender = Lookups::get('GENDER');

// Get raw associative array
$priorities = Lookups::getRaw('ORDER_PRIORITY');
// Returns: ['S' => 'Stat', 'A' => 'ASAP', 'R' => 'Routine', ...]

// Get label by key
$label = Lookups::getLabel('GENDER', '1'); // Returns 'Female'
```

### Frontend Usage (Alpine.js)

```php
// In your PHP view file
<script>
const LOOKUPS = <?= json_encode(\App\Libraries\Lookups::getAll()) ?>;
console.log(LOOKUPS.gender);
// Output: [{"value":"1","label":"Female"},{"value":"2","label":"Male"},{"value":"3","label":"Unknown"}]
</script>
```

### When to Use

| Approach | Use Case |
|----------|----------|
| **Static Lookups** | Frequently used values that rarely change (gender, status, types) |
| **API `/api/valueset*`** | Dynamic values that may be modified by admins at runtime |

---

## 📋 Master Data Management

CLQMS provides comprehensive master data management for laboratory operations. All master data is accessible via the V2 UI at `/v2/master/*` endpoints.

### 🧪 Laboratory Tests (`/v2/master/tests`)

The Test Definitions module manages all laboratory test configurations including parameters, calculated tests, and test panels.

#### Test Types

| Type Code | Description | Table |
|-----------|-------------|-------|
| `TEST` | Individual laboratory test with technical specs | `testdefsite` + `testdeftech` |
| `PARAM` | Parameter value (non-lab measurement) | `testdefsite` + `testdeftech` |
| `CALC` | Calculated test with formula | `testdefsite` + `testdefcal` |
| `GROUP` | Panel/profile containing multiple tests | `testdefsite` + `testdefgrp` |
| `TITLE` | Section title for report organization | `testdefsite` |

#### API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/tests` | List all tests with optional filtering |
| `GET` | `/api/tests/{id}` | Get test details with type-specific data |
| `POST` | `/api/tests` | Create new test definition |
| `PATCH` | `/api/tests` | Update existing test |
| `DELETE` | `/api/tests` | Soft delete test (sets EndDate) |

#### Filtering Parameters

- `TestSiteName` - Search by test name (partial match)
- `TestType` - Filter by test type VID (1-5)
- `VisibleScr` - Filter by screen visibility (0/1)
- `VisibleRpt` - Filter by report visibility (0/1)

#### Test Response Structure

```json
{
  "status": "success",
  "message": "Data fetched successfully",
  "data": [
    {
      "TestSiteID": 1,
      "TestSiteCode": "CBC",
      "TestSiteName": "Complete Blood Count",
      "TestType": 4,
      "TypeCode": "GROUP",
      "TypeName": "Group Test",
      "SeqScr": 50,
      "VisibleScr": 1,
      "VisibleRpt": 1
    }
  ]
}
```

### 📏 Reference Ranges (`/v2/master/refrange`)

Reference Ranges define normal and critical values for test results. The system supports multiple reference range types based on patient demographics.

#### Reference Range Types

| Type | Table | Description |
|------|-------|-------------|
| Numeric | `refnum` | Numeric ranges with age/sex criteria |
| Threshold | `refthold` | Critical threshold values |
| Text | `reftxt` | Text-based reference values |
| Value Set | `refvset` | Coded reference values |

#### Numeric Reference Range Structure

| Field | Description |
|-------|-------------|
| `NumRefType` | Type: REF (Reference), CRTC (Critical), VAL (Validation), RERUN |
| `RangeType` | RANGE or THOLD |
| `Sex` | Gender filter (0=All, 1=Female, 2=Male) |
| `AgeStart` | Minimum age (years) |
| `AgeEnd` | Maximum age (years) |
| `LowSign` | Low boundary sign (=, <, <=) |
| `Low` | Low boundary value |
| `HighSign` | High boundary sign (=, >, >=) |
| `High` | High boundary value |
| `Flag` | Result flag (H, L, A, etc.) |

#### API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/refnum` | List numeric reference ranges |
| `GET` | `/api/refnum/{id}` | Get reference range details |
| `POST` | `/api/refnum` | Create reference range |
| `PATCH` | `/api/refnum` | Update reference range |
| `DELETE` | `/api/refnum` | Soft delete reference range |

### 📑 Value Sets (`/v2/master/valuesets`)

Value Sets are configurable dropdown options used throughout the system. Each Value Set Definition (VSetDef) contains multiple Value Set Values (ValueSet).

#### Value Set Hierarchy

```
valuesetdef (VSetDefID, VSName, VSDesc)
    └── valueset (VID, VSetID, VValue, VDesc, VOrder, VCategory)
```

#### Common Value Sets

| VSetDefID | Name | Example Values |
|-----------|------|----------------|
| 1 | Priority | STAT (S), ASAP (A), Routine (R), Preop (P) |
| 2 | Enable/Disable | Disabled (0), Enabled (1) |
| 3 | Gender | Female (1), Male (2), Unknown (3) |
| 10 | Order Status | STC, SCtd, SArrv, SRcvd, SAna, etc. |
| 15 | Specimen Type | BLD, SER, PLAS, UR, CSF, etc. |
| 16 | Unit | L, mL, g/dL, mg/dL, etc. |
| 27 | Test Type | TEST, PARAM, CALC, GROUP, TITLE |
| 28 | Result Unit | g/dL, g/L, mg/dL, x10^6/mL, etc. |
| 35 | Test Activity | Order, Analyse, VER, REV, REP |

#### API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/valuesetdef` | List all value set definitions |
| `GET` | `/api/valuesetdef/{id}` | Get valueset with all values |
| `GET` | `/api/valuesetdef/{id}/values` | Get values for specific valueset |
| `POST` | `/api/valuesetdef` | Create new valueset definition |
| `PATCH` | `/api/valuesetdef` | Update valueset definition |
| `DELETE` | `/api/valuesetdef` | Delete valueset definition |

#### Value Set Response Structure

```json
{
  "status": "success",
  "data": {
    "VSetDefID": 27,
    "VSName": "Test Type",
    "VSDesc": "testdefsite.TestType",
    "values": [
      { "VID": 1, "VValue": "TEST", "VDesc": "Test", "VOrder": 1 },
      { "VID": 2, "VValue": "PARAM", "VDesc": "Parameter", "VOrder": 2 },
      { "VID": 3, "VValue": "CALC", "VDesc": "Calculated Test", "VOrder": 3 },
      { "VID": 4, "VValue": "GROUP", "VDesc": "Group Test", "VOrder": 4 },
      { "VID": 5, "VValue": "TITLE", "VDesc": "Title", "VOrder": 5 }
    ]
  }
}
```

### 📊 Database Tables Summary

| Category | Tables | Purpose |
|----------|--------|---------|
| Tests | `testdefsite`, `testdeftech`, `testdefcal`, `testdefgrp`, `testmap` | Test definitions |
| Reference Ranges | `refnum`, `refthold`, `reftxt`, `refvset` | Result validation |
| Value Sets | `valuesetdef`, `valueset` | Configurable options |

---

## 🔌 Edge API - Instrument Integration

The **Edge API** provides endpoints for integrating laboratory instruments via the `tiny-edge` middleware. Results from instruments are staged in the `edgeres` table before processing into the main patient results (`patres`).

### Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/edge/results` | Receive instrument results (stored in `edgeres`) |
| `GET` | `/api/edge/orders` | Fetch pending orders for an instrument |
| `POST` | `/api/edge/orders/:id/ack` | Acknowledge order delivery to instrument |
| `POST` | `/api/edge/status` | Log instrument status updates |

### Workflow

```
Instrument → tiny-edge → POST /api/edge/results → edgeres table → [Manual/Auto Processing] → patres table
```

**Key Features:**
- **Staging Table:** All results land in `edgeres` first for validation
- **Rerun Handling:** Duplicate `SampleID` + `TestSiteCode` increments `AspCnt` in `patres`
- **Configurable Processing:** Auto or manual processing based on settings
- **Status Tracking:** Full audit trail via `edgestatus` and `edgeack` tables

---

### 📜 Usage Notice
This repository contains proprietary information intended for the 5Panda Team and authorized collaborators.

---
*© 2025 5Panda Team. Engineering Precision in Clinical Diagnostics.*