← Back to projects
Case study · Nexus suite · Clinical core

HMS
Hospital Management System

The clinical and operational core of the Nexus suite, covering every department of an inpatient hospital from the front desk to discharge. It is also the hub that joins the lab, radiology, finance and HR systems into one HMIS.

Role: Solution architect & lead engineer
Client: Private hospital, Kurdistan Region of Iraq
Product: Nexus Clinical & Hospital Enterprise Suite, SpaceCraft Ltd (Erbil)
Status: Going live at the reference hospital
Stack: Go · PostgreSQL · Lit · FHIR R5 · CDS Hooks

01 the problem

Private hospitals in the region usually run four or five separate systems: a hospital system, a lab system, a radiology system, an accounting package and spreadsheets for HR. Each has its own patient list and its own prices, and none of them agree on the money.

HMS is the core that replaces them. A patient registered once moves through reception, clinics, the emergency department, wards, theatre, the lab and radiology, and every chargeable event reaches the same bill and the same ledger.

02 at a glance

~200k: lines of Go across the suite
~125k: lines of JavaScript (Lit)
400+: PostgreSQL tables
1,500+: permission-checked API routes
12: hospital staff roles
11: admission types, each with its own policy
36,683: coded diagnoses (28,157 with ICD-10)
8,443: drug concepts (8,298 RxNorm-coded)

03 what it covers

Patient access & flow

reception · clinics · ED · wards

Reception: registry search across name, MRN, phone and national ID; Arabic four-part names; duplicate guard and patient merge; a 3-step admit wizard.
11 admission types, each with its own policy on deposits, prior authorisation, rooms and specialties. 27 registration fields can each be set to required, optional or hidden per type.
Outpatient clinics: a live queue model (patients hold a place in line, not a time slot) with 10 queue states, a two-step call-in and return-after-results ordering.
Emergency department: triage board, re-triage history kept as a record of deterioration, full dispositions, and door-to-triage and length-of-stay reported as median and 90th percentile.
Wards: atomic bed claims so two nurses cannot book the last bed twice; a raise → accept → complete transfer handshake with an escalation service that survives restarts.

Clinical record & critical care

EMR · scores · ICU · maternity

EMR: ICD-10 conditions, allergies, LOINC-coded vitals with automatic interpretation, consents, code status, isolation signage, care plans, SBAR handoff and a patient-journey timeline.
Risk scores: NEWS2, Morse, Braden, SOFA, qSOFA and APACHE II. They are computed on the server so they can be reproduced, and missing values are never silently scored as zero.
ICU: ventilator episodes, with ventilator-days computed rather than stored.
Maternity: labour partogram with WHO alert and action lines, postpartum haemorrhage monitoring, newborns as separate patients with automatic NICU routing below 37 weeks, WHO 2006 and INTERGROWTH-21st growth curves, and a human milk bank.

Theatre, pharmacy & blood

safety gates in the workflow

Theatre: the WHO Surgical Safety Checklist acts as a gate: surgery cannot start until sign-in and time-out are complete. Also implant recall tracking, and a team roster that drives the fee split.
Pharmacy: pharmacist verification, a formulary gate with audited override, drug–drug and drug–allergy checks at prescribing, controlled drugs with a second signature, and FEFO dispensing.
MAR: a dose engine that creates one record per due dose, so a missed dose leaves a record; atomic administration so a dose is never charted twice.
Blood bank: donor deferral, quarantine until screening clears, lookback investigation, and crossmatch as a gate before transfusion.

Care pathways

orchestration · decision support

FHIR-based workflow orchestrator that turns a care pathway into dependent tasks and escalates them when they are overdue. It ships with the Surviving Sepsis one-hour bundle.
CDS Hooks engine, order sets and questionnaires.
Shared department kiosk: ED, ICU, maternity, theatre and wards share the same trailing tabs (stock locker, lab reports, front desk, shifts), and the server works out the user's department from their login.

04 architecture

Clients

Nexus web appLit web components · EN / AR (RTL)

Lab analysersHL7 v2 ORU^R01

ScannersDICOM modality worklist

External systemsFHIR R5 · CDS Hooks

Nexus server: single Go binary, embedded UI

REST APIJWT auth · RBAC · full audit trail

HMSclinical

LISlab

RISradiology

FinanceGL · pricing

HRpayroll

Shared platformterminology · i18n · report designer · orchestrator · notifications · FHIR R5

PostgreSQL400+ tables · idempotent bootstrap & seeding

Companion services

HL7 v2 / MLLP gatewaywrites via authenticated REST

Lab analyser simulatorHL7 v2.5.1

Orthanc PACS + OHIFDocker · study webhook

DICOM modality simulatorstdlib-only Go

On-premises deployment. One Go executable serves the API and the embedded web app, so the hospital runs it on its own network with no internet needed. Windows build, run, migration and backup scripts are included.
Data. The PostgreSQL schema bootstrap and seeding are safe to re-run at every start. Clinical catalogues are compiled into the binary and upserted by their source concept id.
Frontend. Lit 3 web components built with Vite. One design system and CSS logical properties let a single stylesheet serve both reading directions.

05 joining five systems into one

Much of the effort went into the integration itself: making five sub-systems behave as one product rather than five products sharing a login.

One patient identity across reception, clinics, ED, wards, theatre, lab, radiology, pharmacy and billing, with a unified history and a FHIR $everything export.
One money path: a lab test, an imaging study, a theatre consumable and a room-day all reach the same bill and the same ledger. A single stock-movement path means the stock report, the consumption report and the patient's statement always agree.
One security model: JWT sessions, 26 roles and about 690 role-to-resource grants checked on every API call, department scoping, account lockout, forced password rotation, instant session revocation, and an audit trail that records before and after values.
One setup console that replaces about 18 settings screens, plus a specialty configuration engine: 12 kinds of clinical content in mandatory, common and quick sets, inherited down the specialty tree. A child specialty can never weaken what its parent requires.
Shared business rules: an atomic claim on disposal of a case (the losing request gets a 409 instead of creating a duplicate), one close-out routine for every admission, and immutable report versions in both lab and radiology.

06 shared platform

Arabic / English

A full right-to-left layout served from one stylesheet using CSS logical properties. Translations are stored as locale-keyed JSONB with fallback. Screen text is translated; stored enum values and clinical free text never are.

Clinical terminology

I converted the 58,829-concept CIEL dictionary from MySQL to PostgreSQL and fed it through a Python ETL pipeline into the binary. SNOMED CT, ICD-10/11, RxNorm and LOINC codes come in through CIEL's crosswalks. Search runs on pg_trgm indexes.

Reporting & comms

An on-screen report designer with 9 block types, JsonLogic rules and versioned publishing to HTML and PDF. Notifications can target a department, role or user.

07 engineering approach

Values that change are computed on read, not stored. Overdue doses, ventilator-days, ward rounds and OR occupancy can never drift out of date, and no clean-up job is needed.
Atomic claims for concurrent actions. When two staff members race for the same bed, dose or disposition, the second is told cleanly that someone else got there first.
Clinical records are immutable. Reports, prices and results get new versions; old rows are never edited.
Settings allow everything until configured, and side effects never block care: ledger posting, notifications and audit logging fail safely.
Large-scale restructuring. The backend began as one flat handlers package, with 1,572 route registrations in a single main.go block. Over 30 planned batches I split it into 49 domain packages, measured the package graph and removed the shims, with no change to any endpoint's behaviour or security.
Quality engineering. 750+ Go tests (81 against real PostgreSQL) and 43 Playwright suites. Over 140 defects were tracked in a numbered DEF/CAV register and closed only after verification.
Knowledge graph of the repository (17,000+ nodes, 31,000+ edges) to trace dependencies before changes that cross modules, and a fact sheet checked against the code that marks every external claim as shipping, partial or roadmap.
Documentation: 300+ engineering documents, plus bilingual sales material (23-slide deck, brochure and leaflet) generated from a single content source.

08 results

One system replaces five: one database and one patient record, with one bill per patient and one ledger for the group.
Safety barriers built into the workflow rather than added as reports: surgical checklist, crossmatch, formulary and interaction checks, controlled-drug signatures.
Fitted to the regional market: Arabic RTL and fully on-premises.
Going live with a 4-wave implementation plan, starting with the revenue areas.

Roadmap

Two-factor login
Live push updates
Bedside barcode scanning
Offline & mobile
Multi-hospital groups
Analytics warehouse
Kurdish interface

— the nexus suite

← All projects Next: LIS →

HMSHospital Management System