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)

---

## Lookups Library (`app/Libraries/ValueSet.php`)

CLQMS uses a **JSON file-based lookup system** loaded via `App\Libraries\Lookups` class. All lookup data is stored as JSON files in `app/Libraries/Data/valuesets/` for easy maintenance and versioning.

### How It Works

- `Lookups` class extends `ValueSet` which handles caching and file loading
- Each lookup is stored as `app/Libraries/Data/valuesets/{name}.json`
- Lookup names are lowercase with underscores (e.g., `gender.json`, `order_priority.json`)

### Available Lookups

| Lookup File | Description | Example Values |
|-------------|-------------|----------------|
| `gender` | Patient gender | Female, Male, Unknown |
| `order_priority` | Order priority levels | Stat, ASAP, Routine, Preop |
| `order_status` | Order lifecycle status | STC, SCtd, SArrv, SRcvd |
| `specimen_type` | Specimen types | BLD, SER, PLAS, UR, CSF |
| `specimen_status` | Specimen status | Ordered, Collected, Received |
| `specimen_condition` | Specimen quality flags | HEM, ITC, LIP, CLOT |
| `specimen_activity` | Specimen workflow events | COLLECT, RECEIVE, REJECT |
| `result_type` | Result data types | NMRIC, RANGE, TEXT, VSET |
| `result_unit` | Common measurement units | g/dL, mg/dL, x10^6/mL |
| `result_status` | Result validation status | Preliminary, Final, Corrected |
| `test_type` | Test definition types | TEST, PARAM, CALC, GROUP |
| `test_activity` | Test workflow activities | Order, Analyse, VER, REV |
| `test_status` | Test active status | Active, Inactive, Discontinued |
| `priority` | General priority values | STAT, HIGH, NORMAL, LOW |
| `race` | Ethnicity/race categories | Jawa, Sunda, Batak, etc. |
| `religion` | Religious affiliations | Islam, Kristen, Katolik, Hindu |
| `marital_status` | Marital status | Single, Married, Divorced |
| `death_indicator` | Death status flags | Yes, No |
| `identifier_type` | ID document types | KTP, Passport, SSN, SIM |
| `operation` | CRUD operation types | Create, Read, Update, Delete |
| `site_type` | Healthcare facility types | GH, PH, GHL, PHL, GL, PL |
| `site_class` | Facility classification | A, B, C, D, Utm, Ptm |
| `ws_type` | Workstation types | Primary, Secondary |
| `enable_disable` | Boolean toggle states | Enabled, Disabled |
| `entity_type` | Entity classification | Patient, Provider, Site |
| `requested_entity` | Requestor types | Physician, Nurse, Lab |
| `location_type` | Location categories | OPD, IPD, ER, LAB |
| `area_class` | Geographic classifications | Urban, Rural, Suburban |
| `adt_event` | ADT event types | Admission, Transfer, Discharge |
| `body_site` | Collection sites | Left Arm, Right Arm, Finger |
| `collection_method` | Specimen collection methods | Venipuncture, Fingerstick |
| `container_size` | Tube/container volumes | 3mL, 5mL, 10mL |
| `container_class` | Container types | Vacutainer, Tube, Cup |
| `container_cap_color` | Tube cap colors | Red, Purple, Blue, Green |
| `additive` | Tube additives | EDTA, Heparin, Fluoride |
| `fasting_status` | Fasting requirement flags | Fasting, Non-Fasting |
| `ethnic` | Ethnicity categories | Various regional groups |
| `math_sign` | Mathematical operators | +, -, *, /, =, <, > |
| `formula_language` | Formula expression types | Formula, Expression |
| `generate_by` | Generation methods | Auto, Manual, Import |
| `did_type` | Device identification types | Serial, MAC, UUID |
| `activity_result` | Activity outcomes | Success, Fail, Retry |
| `reference_type` | Reference value types | NMRIC, TEXT, LIST |
| `range_type` | Range calculation types | REF, CRTC, VAL, RERUN |
| `numeric_ref_type` | Numeric ref types | Reference, Critical, Valid |
| `text_ref_type` | Text reference types | Normal, Abnormal, Critical |
| `request_status` | Request status | Pending, Approved, Rejected |
| `v_category` | ValueSet categories | Various categories |

### Usage

```php
use App\Libraries\Lookups;

// Get all lookups (loads all JSON files, cached)
$allLookups = Lookups::getAll();

// Get single lookup formatted for dropdowns
$gender = Lookups::get('gender');
// Returns: [{"value":"1","label":"Female"},{"value":"2","label":"Male"},...]

// Get raw data without formatting
$raw = Lookups::getRaw('gender');
// Returns: [{"key":"1","value":"Female"},{"key":"2","value":"Male"},...]

// Get label for a specific key
$label = Lookups::getLabel('gender', '1'); // Returns 'Female'

// Get key/value pairs for select inputs
$options = Lookups::getOptions('gender');
// Returns: [["key":"1","value":"Female"],...]

// Transform database records with lookup text labels
$patients = [
    ['ID' => 1, 'Sex' => '1', 'Priority' => 'S'],
    ['ID' => 2, 'Sex' => '2', 'Priority' => 'R'],
];
$labeled = Lookups::transformLabels($patients, [
    'Sex' => 'gender',
    'Priority' => 'order_priority'
]);
// Result: [['ID'=>1, 'Sex'=>'1', 'SexText'=>'Female', 'Priority'=>'S', 'PriorityText'=>'Stat'],...]

// Clear cache after modifying valueset data
Lookups::clearCache();
```

### Frontend Usage (Alpine.js)

```php
<?php
// In your PHP view file
use App\Libraries\Lookups;

$allLookups = Lookups::getAll();
?>
<script>
const LOOKUPS = <?= json_encode($allLookups) ?>;
console.log(LOOKUPS.gender);
// Output: {"values":[{"key":"1","value":"Female"},{"key":"2","value":"Male"},...]}

// Convenience accessors
const genderValues = LOOKUPS.gender.values;
const genderDropdown = LOOKUPS.gender.values.map(v => ({value: v.key, label: v.value}));
</script>
```

### When to Use

| Approach | Use Case |
|----------|----------|
| **Lookups Library** | Static values that rarely change (gender, status, types) - fast, cached |
| **API `/api/valueset*`** | Dynamic values managed by admins at runtime |

### Adding New Lookups

1. Create `app/Libraries/Data/valuesets/{name}.json`:
```json
{
  "name": "example_lookup",
  "description": "Example lookup description",
  "values": [
    {"key": "1", "value": "Option One"},
    {"key": "2", "value": "Option Two"},
    {"key": "3", "value": "Option Three"}
  ]
}
```

2. Access via `Lookups::get('example_lookup')`

---

## 📋 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.*