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.

---

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