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

Key documents:

• Database Schema Redesign Proposal
• API Contract: Patient Registration
• Database Design Review (Reference)

---

🔧 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.