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.

---

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