mahdahar/clqms-be
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
clqms-be/docs/clqms-wst-concept.md

6.6 KiB
Raw Blame History

title, description, date, order, tags, layout
title description date order tags layout
Project Pandaria: Next-Gen LIS Architecture An offline-first, event-driven architecture concept for the CLQMS. 2025-12-19 6
posts
clqms
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):

{
  "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.