Modern pathology laboratories operate in an environment where time and clinical precision dictate patient outcomes. While developing Spandan Cloud PLMS, I asked an important question: How can we empower lab managers, technicians, and visiting doctors to instantly find precise answers about analyzer protocols, NABL compliance rules, and reporting workflows without digging through lengthy manual pages?
The answer was Spandan Lab AI—a specialized clinical pathology assistant embedded directly into the software website. In this article, I share the technical goals, security architecture, hosting realities, and lessons learned while integrating this intelligent assistant.
1. Why Traditional FAQ Accordions Fall Short
Most software websites rely on static FAQ accordions. If a pathologist needs to know whether their specific 5-part hematology analyzer (such as the Mindray BC-5000 or Sysmex XN-350) supports bi-directional ASTM queries, or what critical panic threshold triggers an automated doctor alert for serum potassium, a static list of 10 generic questions rarely answers their query.
Spandan Lab AI bridges this gap by functioning as a conversational guide. It understands nuanced diagnostic terminology, clarifies how barcode accessioning prevents pre-analytical tube mix-ups, and guides prospective users to live demo booking links or WhatsApp support.
2. The Architecture: Decoupled Proxy & Zero-Secret Security
A fundamental rule of modern software engineering—especially in healthcare technology—is that API keys must never be exposed to the client-side browser.
If you call Google Gemini directly from browser JavaScript, any visitor can open Chrome DevTools, inspect the network payload, and extract your private API key. To prevent this vulnerability, I implemented a strict two-tier architecture:
- Client-Side Frontend (
app.js): Collects user input and multi-turn conversation history. It sends requests solely to a configured backend endpoint (such as/api/chat) without holding any secrets or keys. - Server-Side Secure Proxy (
server/server.js&server.ps1): A lightweight Node.js/PowerShell proxy server. It securely loads theGEMINI_API_KEYfrom a protected.envfile (which is strictly ignored by Git), applies a clinically grounded pathology system prompt, injects conversation context, and communicates over encrypted HTTPS with Google's Gemini REST API. - Automated Secret Redaction: Even if Gemini returns an upstream error or rate-limit notice, the server sanitizes all error strings before returning them to the client, scrubbing any API key patterns or internal server paths.
3. The Deployment Dilemma: Why Chatbots Go "Offline" on GitHub Pages
A frequent point of confusion when deploying web applications to GitHub Pages is understanding what GitHub repository hosting actually does.
/api/chat return a 404 Not Found error because no server is listening behind GitHub's static CDN.
To solve this for production without compromising security:
- Decoupled Backend Deployment: The backend server (
server/server.js) is packaged with a cleanpackage.jsonfile. This allows it to be hosted independently on a cloud platform like Render, Railway, or Koyeb where Node.js processes run continuously. - Configurable Endpoint Resolution: The frontend is engineered with an intelligent resolution hierarchy:
- It checks for a configured production backend URL (via
window.SPANDAN_BACKEND_URLorlocalStorage). - When running locally on
localhost:8085, it seamlessly calls the local proxy. - If hosted on a static domain (such as GitHub Pages) without an active backend URL configured, it avoids crashing or displaying intimidating network errors. Instead, it activates Client-Side Pathology Knowledgebase Mode.
- It checks for a configured production backend URL (via
4. Resilience: The Built-In Pathology Knowledgebase
In clinical environments, software cannot afford a blank error screen when an internet hiccup or upstream API downtime occurs.
Inside app.js, I engineered a comprehensive client-side Pathology Knowledgebase. Even when completely offline or running purely as a static demo on GitHub Pages, Spandan Lab AI can accurately answer core questions:
- Analyzer Models Supported: Details for Mindray (BC-5000, BS-200), Sysmex (XN-350, XP-300), Erba (Chem 5X), and Roche Cobas.
- NABL ISO 15189 Standards: Immutable audit trails, digital doctor signatures, and Levey-Jennings QC charts.
- WhatsApp Dispatch Mechanics: Instant PDF delivery through the Meta WhatsApp Business Cloud API.
- Critical Panic Values: Severe thrombocytopenia alerts (<20,000 /cu.mm), critical hyperkalemia (>6.2 mmol/L), and severe anemia flags.
5. Current Reality vs. Future Possibilities
In healthcare AI, it is vital to be transparent about what is implemented today versus what is slated for future research:
| Feature Status | Capabilities |
|---|---|
| ✅ Currently Implemented | Real-time Gemini chat proxy, multi-turn conversation memory, instant pathology knowledgebase fallback, interactive action buttons (WhatsApp, Demo, Sample Report), and zero-secret credential protection. |
| 🔬 Future Exploration | Automated preliminary narrative drafting for histopathology reports, AI OCR scanning of paper referral slips, and intelligent reagent re-ordering forecasts based on seasonal disease patterns. |
Key Lessons Learned
- Never Compromise on Security: Keep API secrets on the server side at all times. A fast launch is never an excuse to commit credentials.
- Design for Offline Fallbacks: In clinical environments, systems must degrade gracefully. Providing a client-side knowledgebase ensures users always find the information they need.
- Acknowledge Hosting Realities Early: Static hosts and dynamic Node backends require distinct deployment strategies. Designing for this from day one prevents unexpected offline surprises.