A bilingual knowledge layer for a complex HIS

The problem every hospital IT team knows too well

There's a peculiar kind of frustration that comes with administering a complex Hospital Information System when the vendor is 2,000 kilometers away, speaks a different language, and operates on a different holiday calendar. Every question — no matter how small — requires a support ticket. Every workflow clarification needs a scheduled call. Every new hire's onboarding is blocked on the same tribal knowledge that lives in the heads of a few veteran operators.

This isn't hypothetical. It's the daily reality of running Sarus HIS, a large-scale Hospital Information System built by Teknoritma and deployed across hospitals in Turkey, Iraq, and the UAE — patient registration, outpatient and inpatient management, lab (LIS), radiology (RIS), pharmacy, billing, stock, and more modules, wrapped in SOAP services with 457 to 707 operations each.

HL7-compliant, battle-tested, mission-critical. And, from an information-access standpoint, a black box.

When you ask "How do I cancel an invoice?" or "What does a red screen at login mean?", the answer isn't in a manual you can easily grep. It could be buried in a training video recorded in a foreign language three years ago — or in the memory of a sysadmin who's answered that question forty times this month.

I decided to change that.

What Sarus HIS actually is

An 18-module (and growing) system covering the full hospital workflow: patient registration & master index, outpatient follow-up (vitals, ICD-10, prescriptions, SOAP notes, referrals), inpatient (admission, transfer, discharge, bed boards, wristbands), operating rooms & anesthesia, lab and radiology as separate ASP.NET apps with barcode and DICOM/PACS flows, pharmacy with narcotics control, an emergency room on a customized Manchester 5-color triage, cashier & billing, stock with 1,300+ SKUs, appointment scheduling, info desk, diet, statistics (652 reports across 66 pages), system administration with 24 sub-menus, counseling, financial management, and a mobile app.

The contractual spec alone is a 102-page PDF; the original deployment target ran to thousands of beds and users with tens of thousands of daily patients. This is not a small system.

The black-box problem

Three barriers, all painfully specific:

1. Language. The vendor is Turkish. Deployments surface Arabic and English, but the reference materials, the knowledge base, and the expert consultants mostly operate in Turkish.

2. Timezone & timing. Even where clocks align, support hours don't align with hospital hours. A question raised at 8 AM handover may not be answered until the next day — past the window when it was needed. Add mismatched holidays and human contingencies.

3. Tribal knowledge. The real workflows — "a red screen at login means the account is inactive", "you can't delete an encounter once a practitioner has started it" — live in videos, scattered PDFs, and senior staff memories. No searchable, structured base.

ed. Result: clerks, nurses, and cashiers ask the same questions forever; IT answers them forever; every new hire replays the same slow ramp-up. Job security, but make it miserable.

Who this is for

This is a knowledge and support layer built for hospital IT teams, application support, super-users, and HIS implementation partners. The goal is simple: deflect routine questions, cut time spent hunting through training videos and documents, and standardize answers across sites running the same HIS.

The insight: a custom-tuned model changes everything

The mechanics of an IT system that directly serves customers must be transparent.

General-purpose chatbots fail here three ways: they hallucinate features ("change appointment timing on the patient website" — the site has no such function), they can't navigate an 18-module HL7 system's UI, and they don't speak the staff's language — our people switch between English and Arabic mid-conversation.

What's needed: a model that knows exactly what the system does and doesn't do, answers in the user's language, grounds every answer in documented facts, and can distinguish "here's how" from "that needs front-desk authorization." That's a Retrieval-Augmented Generation (RAG) pipeline with curated knowledge — not a generic LLM with a system prompt.

The architecture

User Browser → Chat UI → Node.js Server (local) → LLM Proxy (local) → LLM Provider (local/remote) → LLM (local/remote)

A featherweight HTML/JS chat UI, a zero-dependency vanilla Node server (no Express, no npm install, no dependency rot), an OpenAI-compatible proxy so no external API key ever touches the code, and a capable open model that handles English and Arabic with strong reasoning. The production deployment has access to live hospital data (with strict, read-only scopes) to surface up-to-date information such as bed census, appointment availability, lab status, and other operational data.

The retrieval layer is a hybrid pipeline. BM25 (k1=1.4, b=0.72) and multilingual embeddings (e.g. bge-m3 or multilingual-e5) run in parallel, with results merged and passed to a cross-encoder reranker. This handles paraphrase, code-switching, and Arabic dialects far better than lexical search alone. Every answer has enforced citations to retrieved source chunks, with an abstain threshold applied when retrieval confidence is low.

Morphological bridging — standard stemming fails on domain language, so a bidirectional map links register↔registration, print↔printout, cancel↔cancellation.

Arabic normalization + synonyms — alef variants collapse, ى→ي, ة→ه, ال-prefixes strip, so المواعيد matches موعد with no translation layer; a synonym map bridges Arabic queries to English terms cross-lingually.

Credential redaction — training docs contain real usernames, passwords, IPs; a redact() pass strips them before any text reaches LLM context. The model never sees credentials. Ever.

Smart chunking — split at headings first, then sliding 800-char windows with 100-char overlap snapped to word boundaries, so procedures survive intact.

Hybrid retrieval scoring — BM25 with a coverage bonus for chunks matching all query terms and phrase bonuses for bigrams and verbatim phrases is combined with embedding similarity, then reranked. English stopword removal, Q/A banks chunked question-first, and enforced citations with an abstain threshold ensure high precision. Top results are selected from the reranked set.

Training the model: the knowledge base

Three tiers: patient-facing how-tos, staff-facing UI steps ("cancel an invoice → Accounts Manager authorization + mandatory reason"), and developer/admin internals (SOAP ops, WSDL paths, user/bed/service provisioning) that the model must translate into plain steps — or withhold behind the right desk.

Access control: role-based indexes

Content is split into separate indexes for Patient, Staff, and Admin. SSO determines the user's role and decides which index(es) are searched. This enforces least privilege — patient-facing sessions never touch staff or admin content, and sensitive documentation stays scoped to authorized roles.

The chat pipeline: question → answer

1. Role resolution via SSO — determine role and select authorized index(es) to search.

2. Quick-answer lookup over 124 bilingual FAQs when matched.

3. Live data routing — for statistic-based queries (e.g. bed counts), attempt to fetch from live, read-only hospital APIs first, falling back to cached snapshots if unreachable.

4. Personal-question guard ("Whats your gender?" → friendly deflection)

5. Hybrid retrieval — run BM25 and multilingual embeddings in parallel against authorized indexes, merge, and rerank with a cross-encoder.

6. Prompt assembly with strict grounding rules and enforced citation with grounding enforcement — if top reranked results fall below the abstain threshold, the system abstains and routes to the appropriate desk. Otherwise, answers include citations to the source chunks used.

7. LLM call with 3-retry exponential backoff.

The system prompt stays deliberately lean: what the system is, what it cannot do (book, modify, cancel, or access personal patient records), and how to say "I don't have that information." Hallucinations are kept near zero through grounding, citations, and abstention. Honesty is a feature.

Results: what the assistant actually does

FAQ resolution (instant): red screen at login → account inactive, contact admin · password reset → step-by-step flow · invoice cancellation → authorization + audit trail — in Arabic too (كيف أسجل الدخول؟ → same answer, in Arabic).

Procedural guidance: register an encounter (Facility → Specialty → Physician → Type → Special Case → Save) · finish an examination (diagnosis + prescription + notes → Finish with outcome) · book a surgery (pre-op → surgeon/anesthesiologist → services → team).

Boundary awareness: "book me an appointment" → "I can't book — here's how it works, contact the clinic" · "show me patient records" → "I can't view patient data — front desk, please" · "what's your gender?" → "I'm the Sarus HIS Virtual Assistant…"

Statistics: "how many beds?" → routed to live read-only hospital APIs (or presented as "last recorded" from cached census when offline) — whole-hospital and department-level (ICU 20, ED 92, CICU 12…) without a canned answer hijacking specific questions.

Building the knowledge base

Feeding the base meant distilling approved training material, user guides, and observed workflows into structured, retrievable chunks. The full technical story of how key workflows were reconstructed from captured traffic is covered in a separate companion note (The HAR Journey: Mapping an Undocumented HIS).

Key design decisions

1. Zero-dependency Node. Deployable on any machine with Node.js.

2. LLM proxy, not direct API — flaky keys and 403s live at the proxy, not in the product.

3. systemd persistence — both services Restart=always, surviving crashes and reboots.

4. Multi-source indexing — new knowledge is a dropped .md file + restart.

5. Security boundaries — public chat touches zero live patient data; admin stats sit behind JWT; credentials never reach the model.

Production capabilities

This is a production-grade system. What you see below is a demo of it. In production, the deployment has:

Retrieval & grounding: Hybrid retrieval (BM25 + multilingual embeddings such as bge-m3 or multilingual-e5) with a cross-encoder reranker, enforced citations, and an abstain threshold on low retrieval confidence.

Access control: SSO-integrated RBAC with separate indexes for Patient, Staff, and Admin content, with full audit logging of retrieval scope per request.

Live data: Read-only integrations to live hospital data (census, queues, statuses) with timeouts, caching, and safe fallbacks to cached snapshots.

Channels & accessibility: WhatsApp and Microsoft Teams access, voice input, an in-app widget, and a persistent feedback button, all routed through the same policy layer.

Feedback loop & observability: Thumbs up/down on every answer, logging of unanswered and missed questions, user and admin dashboards showing satisfaction, coverage by topic/module, and knowledge gaps, with a weekly review that turns misses into new Q&A entries.

Ongoing expansion: Arabic training docs, continued module automation (RIS posting, LIS sample tracking, pharmacy dispense), and continuous knowledge gap closure driven by the feedback loop.

The bigger picture

When a complex system creates information asymmetry between vendor and operator, a tuned RAG pipeline breaks that asymmetry.

The model doesn't need to be the largest or most expensive. It needs to be grounded, multilingual, bounded, and transparent about its limits — turning tribal knowledge into shared knowledge, vendor support bottlenecks into self-serve answers, and "wait for the next support call" into "ask the assistant."

This is the Shoreline principle in practice: the assistant knows when to answer, when to cite sources, and when to abstain and route to authorized staff. Rather than overreaching, it treats its limits as a feature — the shoreline where machine guidance ends and human judgment begins. Read more about the Shoreline Framework →

Crucially, the hardest problem isn't retrieval quality — it's adoption. Meeting staff on the tools they already use (WhatsApp, Teams), lowering the barrier to entry (voice, in-app widget), and closing the loop on their feedback is what turns a production-grade assistant into a relied-upon one.

Now the real challenge: MAKE THE USERS USE IT.