Clinical knowledge as software that never guesses.
A private preventive-medicine practice needed its clinical protocol to run as software — without a single threshold, dose or reference range ever being retyped by an engineer. We built a monitoring and decision-support platform where every recommendation traces back to the physician's own verified knowledge, and the software refuses rather than improvises.
In clinical software, a confident wrong answer is the only unforgivable bug.
Preventive medicine runs on hundreds of biomarkers, interventions, contraindications and safety thresholds. Most health apps hard-code a handful of them and hope. The brief here was the opposite: the physician owns the medicine, the software owns the delivery, and the boundary between them has to be provable.
Knowledge engineers must not touch
Every threshold, dose, reference range and evidence tier belongs to the physician. None of it could live in application code, where a refactor or a typo would silently change a clinical recommendation.
Gates that pass silently are worse than none
The inherited rule engine returned the same "no objection" answer whether a safety gate had genuinely cleared or had simply found no threshold to test against. Hundreds of gates were reporting clear without ever being evaluated.
Three roles, one database
Physician, patient and laboratory share a single database. A laboratory sees an order, never a name. A patient sees their own record and nothing else. That guarantee had to hold in the database, not in an interface condition.
Arabic-first, and inside the border
Patient-facing screens are Arabic-first RTL, and Saudi PDPL requires patient data to stay in-country — which rules out most managed platforms and shapes the entire deployment.
One engine, one source of truth, and a boundary CI can enforce.
We split the system into a knowledge layer the physician owns, an application layer we own, and a deterministic decision engine that is the only component allowed to reason clinically. A CI check fails the build if a clinical number ever appears in application code.
Bilingual, Server-Rendered, Role-Aware
- Next.js 16 App Router with React 19 server components and server actions — no separate API tier to keep in sync
- Arabic-first RTL throughout, with a CI check that fails on any untranslated interface string
- Tailwind CSS v4 and a restrained clinical design system — hairlines over boxes, tabular figures, one accent colour
- Server-rendered SVG charts with no charting library — trend lines and glucose profiles that stay legible under RTL
Deterministic, and Honest About Refusing
- Python FastAPI service exposing exactly one clinical endpoint — the single path to any recommendation
- Twenty-one named refusals — the engine declines with a stated reason rather than guessing when inputs are insufficient
- Gate-coverage reporting — every recommendation states how many safety gates were evaluated and why each remaining one was not
- Version stamping — every stored decision carries the exact knowledge version that produced it
Isolation Proven at Boot, Not Assumed
- PostgreSQL 17 with three isolated schemas — universal clinical knowledge, patient data, and authentication behind a hard wall
- Row-level security on every patient table, with a startup assertion that refuses to boot if the connecting role could bypass it
- Argon2 hashing and mandatory TOTP for clinicians, with stateful sessions that revoke instantly — deliberately not JWTs
- AES-256-GCM at rest for device tokens and secrets, on infrastructure that keeps patient data inside the country
Measurement in, safety-gated recommendations out.
The loop runs from enrolment through laboratory panels and wearable data to a physician-approved plan the patient actually follows — with explicit release gates, so nothing reaches a patient before the physician releases it.
Two-Stage Release
A confirmed laboratory value and an approved plan item both stay invisible to the patient until the physician releases them. Enforced in the database, not the interface.
Wearable & Lab Ingest
Whoop over OAuth2 with HMAC-signed webhooks, continuous glucose data from Dexcom, and OCR extraction of laboratory reports in English and Arabic.
Hash-Chained Audit
An append-only audit log where any edit or deletion invalidates every entry after it. It records who acted on what — never the clinical value itself.
A clinical interface that never scolds.
Warm paper rather than clinical white, ink rather than pure black, and a single restrained green used sparingly. Marker states read optimal, off-optimal or not-measured — never a red-versus-green verdict — because a full baseline takes weeks, and waiting should feel calm rather than like failure.
One idea per screen.
Every recommendation arrives as a decision card that shows its own reasoning: where a marker sits against its optimal band, which safety gates were evaluated, and — just as importantly — which were not. The console itself is confidential, so what follows is its shape rather than a capture of it.
Stamped with the knowledge version that produced it. Nothing reaches the patient until the physician releases it.
A platform where every clinical claim is traceable to its source.
Zero clinical values in application code
A CI check scans the codebase on every commit and fails the build if a threshold, dose or reference range appears anywhere outside the physician-owned knowledge layer.
63 of 202 marker gates made able to block
Gates that previously returned clear without being evaluated now either block or state plainly why they could not run — reported on every recommendation instead of hidden inside it.
Code and clinical knowledge roll back together
The container image tag is the knowledge version, so reverting a release reverts both at once. Weekly backups are verified by restoring them and diffing against live — a file on disk is not a backup.
~34,000 lines · 54 tables · 591 tests
Three applications and twelve packages in a fully typed monorepo, with every interface string maintained in both English and Arabic and a build that fails on any missing translation.
Building something where being wrong isn't an option?
If your product carries real-world consequences — clinical, financial or regulatory — let's talk about the boundaries it needs.