158 lines
6.6 KiB
Markdown
158 lines
6.6 KiB
Markdown
---
|
|
title: "Project Pandaria: Next-Gen LIS Architecture"
|
|
description: "An offline-first, event-driven architecture concept for the CLQMS."
|
|
date: 2025-12-19
|
|
order: 6
|
|
tags:
|
|
- posts
|
|
- clqms
|
|
layout: clqms-post.njk
|
|
---
|
|
|
|
## 1. 💀 Pain vs. 🛡️ Solution
|
|
|
|
### 🚩 Problem 1: "The Server is Dead!"
|
|
> **The Pain:** When the internet cuts or the server crashes, the entire lab stops. Patients wait, doctors get angry.
|
|
|
|
**🛡️ The Solution: "Offline-First Mode"**
|
|
The workstation keeps working 100% offline. It has a local brain (database). Patients never know the internet is down.
|
|
|
|
---
|
|
|
|
### 🚩 Problem 2: "Data Vanished?"
|
|
> **The Pain:** We pushed data, the network blinked, and the sample disappeared. We have to re-scan manually.
|
|
|
|
**🛡️ The Solution: "The Outbox Guarantee"**
|
|
Data is treated like Registered Mail. It stays in a safe SQL "Outbox" until the workstation signs a receipt (ACK) confirming it is saved.
|
|
|
|
---
|
|
|
|
### 🚩 Problem 3: "Spaghetti Code"
|
|
> **The Pain:** Adding a new machine (like Mindray) means hacking the core LIS code with endless `if-else` statements.
|
|
|
|
**🛡️ The Solution: "Universal Adapters"**
|
|
Every machine gets a simple plugin (Driver). The Core System stays clean, modular, and untouched.
|
|
|
|
---
|
|
|
|
### 🚩 Problem 4: "Inconsistent Results"
|
|
> **The Pain:** One machine says `WBC`, another says `Leukocytes`. The Database is a mess of different codes.
|
|
|
|
**🛡️ The Solution: "The Translator"**
|
|
A built-in dictionary auto-translates everything to Standard English (e.g., `WBC`) before it ever touches the database.
|
|
|
|
---
|
|
|
|
## 2. 🏗️ System Architecture: The "Edge" Concept
|
|
|
|
We are moving from a **Dependent** model (dumb terminal) to an **Empowered** model (Edge Computing).
|
|
|
|
### The "Core" (Central Server)
|
|
* **Role:** The "Hippocampus" (Long-term Memory).
|
|
* **Stack:** CodeIgniter 4 + MySQL.
|
|
* **Responsibilities:**
|
|
* Billing & Financials (Single Source of Truth).
|
|
* Permanent Patient History.
|
|
* API Gateway for external apps (Mobile, Website).
|
|
* Administrator Dashboard.
|
|
|
|
### The "Edge" (Smart Workstation)
|
|
* **Role:** The "Cortex" (Immediate Processing).
|
|
* **Stack:** Node.js (Electron) + SQLite.
|
|
* **Responsibilities:**
|
|
* **Hardware I/O:** Speaking directly to RS232/TCP ports.
|
|
* **Hot Caching:** Keeping the last 7 days of active orders locally.
|
|
* **Logic Engine:** Validating results against reference ranges *before* syncing.
|
|
|
|
> **Key Difference:** The Workstation no longer asks "Can I work?" It assumes it can work. It treats the server as a "Sync Partner," not a "Master." If the internet dies, the Edge keeps processing samples, printing labels, and validating results without a hiccup.
|
|
|
|
---
|
|
|
|
## 3. 🔌 The "Universal Adapter" (Hardware Layer)
|
|
|
|
We use the **Adapter Design Pattern** to isolate hardware chaos from our clean business logic.
|
|
|
|
### The Problem: "The Tower of Babel"
|
|
Every manufacturer speaks a proprietary dialect.
|
|
* **Sysmex:** Uses ASTM protocols with checksums.
|
|
* **Roche:** Uses custom HL7 variants.
|
|
* **Mindray:** Often uses raw hex streams.
|
|
|
|
### The Fix: "Drivers as Plugins"
|
|
The Workstation loads a specific `.js` file (The Driver) for each connected machine. This driver has one job: **Normalization.**
|
|
|
|
#### Example: ASTM to JSON
|
|
**Raw Input (Alien Language):**
|
|
`P|1||12345||Smith^John||19800101|M|||||`
|
|
`R|1|^^^WBC|10.5|10^3/uL|4.0-11.0|N||F||`
|
|
|
|
**Normalized Output (clean JSON):**
|
|
```json
|
|
{
|
|
"test_code": "WBC",
|
|
"value": 10.5,
|
|
"unit": "10^3/uL",
|
|
"flag": "Normal",
|
|
"timestamp": "2025-12-19T10:00:00Z"
|
|
}
|
|
```
|
|
|
|
### Benefit: "Hot-Swappable Labs"
|
|
Buying a new machine? You don't need to obscurely patch the `LISSender.exe`. You just drop in `driver-sysmex-xn1000.js` into the `plugins/` folder, and the Edge Workstation instantly learns how to speak Sysmex.
|
|
|
|
---
|
|
|
|
## 4. 🗣️ The "Translator" (Data Mapping)
|
|
|
|
Machines are stubborn. They send whatever test codes they want (`WBC`, `Leukocytes`, `W.B.C`, `White_Cells`). If we save these directly, our database becomes a swamp.
|
|
|
|
### The Solution: "Local Dictionary & Rules Engine"
|
|
Before data is saved to SQLite, it passes through the **Translator**.
|
|
|
|
1. **Alias Matching:**
|
|
* The dictionary knows that `W.B.C` coming from *Machine A* actually means `WBC_TOTAL`.
|
|
* It renames the key instantly.
|
|
|
|
2. **Unit Conversion (Math Layer):**
|
|
* *Machine A* sends Hemoglobin in `g/dL` (e.g., 14.5).
|
|
* *Our Standard* is `g/L` (e.g., 145).
|
|
* **The Rule:** `Apply: Value * 10`.
|
|
* The translator automatically mathematical normalized the result.
|
|
|
|
This ensures that our Analytics Dashboard sees **clean, comparable data** regardless of whether it came from a 10-year-old machine or a brand new one.
|
|
|
|
---
|
|
|
|
## 5. 📨 The "Registered Mail" Sync (Redis + Outbox)
|
|
|
|
We are banning the word "Polling" (checking every 5 seconds). It's inefficient and scary. We are switching to **Events** using **Redis**.
|
|
|
|
### 🤔 What is Redis?
|
|
Think of **MySQL** as a filing cabinet (safe, permanent, but slow to open).
|
|
Think of **Redis** as a **loudspeaker system** (instant, in-memory, very fast).
|
|
|
|
We use Redis specifically for its **Pub/Sub (Publish/Subscribe)** feature. It lets us "broadcast" a message to all connected workstations instantly without writing to a disk.
|
|
|
|
### 🔄 How the Flow Works:
|
|
|
|
1. **👨⚕️ Order Created:** The Doctor saves an order on the Server.
|
|
2. **📮 The Outbox:** The server puts a copy of the order in a special SQL table called `outbox_queue`.
|
|
3. **🔔 The Bell (Redis):** The server "shouts" into the Redis loudspeaker: *"New mail for Lab 1!"*.
|
|
4. **📥 Delivery:** The Workstation (listening to Redis) hears the shout instantly. It then goes to the SQL Outbox to download the actual heavy data.
|
|
5. **✍️ The Signature (ACK):** The Workstation sends a digital signature back: *"I have received and saved Order #123."*
|
|
6. **✅ Done:** Only *then* does the server delete the message from the Outbox.
|
|
|
|
**Safety Net & Self-Healing:**
|
|
* **Redis is just the doorbell:** If the workstation is offline and misses the shout, it doesn't matter.
|
|
* **SQL is the mailbox:** The message sits safely in the `outbox_queue` table indefinitely.
|
|
* **Recovery:** When the Workstation turns back on, it automatically asks: *"Did I miss anything?"* and downloads all pending items from the SQL Outbox. **Zero data loss, even if the notification is lost.**
|
|
|
|
---
|
|
|
|
## 6. 🏆 Summary: Why We Win
|
|
|
|
* **Reliability:** 🛡️ 100% Uptime for the Lab.
|
|
* **Speed:** ⚡ Instant response times (Local Database is faster than Cloud).
|
|
* **Sanity:** 🧘 No more panic attacks when the internet provider fails.
|
|
* **Future Proof:** 🚀 Ready for any new machine connection in the future.
|