Shifa One — Detailed Use Cases

Shifa One · Medical Platform

# Detailed Use Cases

Twelve end-to-end scenarios, told step by step from each actor's chair — with the exact system behavior at every step. Everything on the LIVE badge is running on the demo today.

docs/Shifa-one · use cases · 2026-07
UC-1 · LIVE

## Owner / Admin onboards a new facility

Actors: Owner, platformModules: MedRegistry · MedOrganizationGoal: from empty tenant to configured medical facility
Open the setup wizard (Medical Modules → Setup wizard).wizard reads the 10 business-type presets + Custom from the registry
Pick the facility type — e.g. Polyclinic.default modules pre-checked and locked; optional ones (radiology, specialties) toggleable
Confirm & install.module instances enabled per tenant; dependencies auto-added (e.g. pharmacy ⇒ inventory); missing hosts reported honestly
Medical roles appear for staffing: doctor, nurse, pharmacist, lab technician, radiologist, receptionist, billing clerk…12 roles seeded additively per business — existing users untouched
Shape the organization (Organization menu): type each branch, nest facilities, add departments & rooms, assign staff to departments.facility profiles satellite business_locations; department scope feeds data-access rules
Track credentials: add each clinician's license with expiry.daily job alerts admins 30 days before expiry; verification workflow (pending → verified)
BioClinic variant: repeat per branch — dental modules on the Maadi branch only, derma in New Cairo.module instances scope per business_location
UC-1
UC-2 · LIVE

## Outpatient visit — Receptionist → Doctor → Cashier

Trigger: patient walks inModules: ClinicCore · MedBillingDemo: patient “Ahmed Saleh”, appointment E2E-0001
Receptionist registers the patient: identity (national ID, nationality, language), demographics, photo.ERP contact + clinical patient created 1:1; duplicate detection flags similar name+DOB+phone
Books an appointment from real availability (doctor, date, slot), source = walk-in.availability engine applies working hours, breaks, exceptions, per-slot capacity
Checks the patient in.check-in time stamped; patient appears on Today's Queue in the “in queue” column
Nurse records vitals: BP, pulse, temp, SpO₂, glucose, weight/height.BMI auto-computed; out-of-range values flag critical and raise a patient alert
Doctor opens the consult — safety banner first (allergies/alerts), then encounter card (type, priority).ABAC: a nurse could edit vitals here but not the assessment
Documents SOAP + ICD-10 diagnoses, adds a diagnosis to the problem list, signs & locks the note.post-sign edits only via the amendment flow — full audit trail
Prescribes — the safety screen runs (allergy / duplicate therapy); orders a CBC from the Orders card.lab item routes automatically into the analyzer worklist
Completes the encounter; billing captures charges (consultation 450 + CBC 200 from the lab catalog).one real ERP invoice per patient; stock-tracked items decrement exactly once
Cashier takes payment at POS or against the invoice; patient leaves with the printed Rx.
UC-2
UC-3 · LIVE

## The patient-safety net — Nurse / Doctor

Goal: the system blocks harm before it happensDemo: Penicillin scenario on Ahmed Saleh
Nurse records a structured allergy: Penicillin, drug, life-threatening, anaphylaxis.severe/life-threatening allergies auto-raise a critical alert
Red safety banner appears on every clinical screen for this patient — profile, consult, pharmacy.alerts carry acknowledge/resolve actions, permission-gated
Doctor tries to prescribe Penicillin V 250mg → blocking warning: “matches a recorded life-threatening drug allergy”.server-side block requires explicit confirmed override; a drug_interaction alert is raised, idempotently
Critical alerts notify — in-app to the care team via the notifications hub.MedNotify routes per user preferences, quiet hours, digests
Same net elsewhere: critical vitals (BP 195/118), critical lab analytes on verify, IOP > 30 in eye exams, critical imaging findings — all land in the same alert registry and banner.
UC-3
UC-4 · LIVE

## Lab order → verified result — Doctor → Lab tech → Verifier

Modules: ClinicCore orders · ClinicLab · LabCore analyzers
Doctor orders “CBC” from the consult Orders card (priority routine/urgent/STAT).order item auto-routes into the lab worklist with patient + encounter linkage
Lab tech generates a specimen — barcode SPX-8-000001 printed on the tube.specimen lifecycle: awaiting collection → collected → received → processing
Rejection path: hemolyzed sample → reject with reason; the note writes back onto the doctor's order.reason enum: hemolyzed, clotted, insufficient volume, wrong container, mislabeled…
The analyzer reports (NX600/Abaxis/IDEXX) into result sessions with reference ranges.device-agnostic LabCore pipeline; abnormal flags normalized
Tech reviews → verifier verifies.verify applies catalog critical bounds; critical values raise a patient alert + notify; the order flips to “resulted” with a summary — the loop closes back to the doctor
Patient is notified results are ready (WhatsApp/in-app per template).lab.result.ready event through the notifications hub, fail-soft per channel
Outreach: a standalone lab logs an external provider's sample through the same specimen flow and marks delivery back to the referrer.
UC-4
UC-5 · LIVE

## Pharmacy dispensing — Pharmacist

Screen: Clinic → Pharmacy (dispense queue)Safety: allergy re-check + witnessed controlled drugs
Open the dispense queue — active prescriptions with undispensed items, filter by doctor/date.controlled items carry a schedule badge
Open an item — FEFO batch guidance shows lots by earliest expiry with remaining quantity.guidance reads real ERP purchase-line lots at the pharmacist's location
Safety re-check at dispense — the same allergy screen runs again; life-threatening hits require explicit confirmation.
Controlled medicine? A witness must be selected; the witnessed OUT movement writes to the controlled-drug register.insert-only register with running balance per medicine+batch — audit-proof
Dispense — quantities and dispenser stamped on the Rx item; when the whole Rx is dispensed the patient gets a “prescription ready” notification and the Rx completes.dispensing is clinical only; stock deducts once, at billing
Refills: later visits use the refill action until refills_allowed is exhausted.
Retail walk-in (OTC): straight through the ERP POS — batch/expiry stock already native.
UC-5
UC-6 · LIVE

## Insurance billing & claims — Billing clerk

Module: MedBilling on the ERP invoice engineDemo: claim CLM-8-0000002, split 352/98
Set up payers once (insurance/corporate) and attach patient policies (coverage %, copay, expiry).policies link the patient's insurance cards; payer price lists via ERP selling-price groups
Open the billing worklist — completed encounters with uncaptured charges.capture drafts consultation fee + orders (lab-catalog priced) + dispensed medicines
Review and bill, choosing the patient's policy — the split preview shows payer vs patient share.ONE real ERP invoice (scheme numbering, taxes, accounts); with 80% coverage after 10 copay: 450 → payer 352 / patient 98
A claim drafts automatically per invoice+policy with line items.
Submit → acknowledge → adjudicate per item → paid.markPaid records the payer's ERP payment; the invoice correctly shows partial until the patient settles their share
Denied? Record the reason, appeal with notes — the full lifecycle is tracked; adjudication changes notify billing users.
Reports: billed vs collected, claims by status, payer aging.
UC-6
UC-7 · LIVE

## Imaging with a critical finding — Radiologist

Screens: modality worklist · report editorModalities: XR/US/CT/MRI/Endo + ECG/Echo/PFT/Audio/Vision
Doctor orders a chest X-ray (urgent) from the consult.order routes to an imaging request; STAT/urgent float to the top of the worklist
Technologist runs the study, uploads images with radiation dose (DAP/DLP/CTDIvol).per-patient cumulative dose tracked
Radiologist writes the report: findings, impression, recommendation — draft → preliminary → final (impression required).final locks the report; corrections only via the amend flow with a reason
Critical finding? The report cannot finalize without naming who was told.critical_communicated_to mandatory → critical alert raised + “report ready” notification; the ordering item flips to resulted with the impression
Diagnostic center: ECG, echo, endoscopy, PFT, audiometry and vision tests ride exactly this pipeline as modalities.
UC-7
UC-8 · LIVE

## Specialty deep-dives — Dentist · Dermatologist · Ophthalmologist

Dentist: charts tooth 26 (FDI 42 display) — caries, probing depth, mobility; logs the CDT procedure with materials & anesthesia.
Builds a treatment plan (rows, urgency, cost estimate, printable for the patient) and converts it into a real ClinicCore multi-session plan.
Recalls: 6-month cleaning recall lands on the due list; the daily job fires patient reminders.
Dermatologist: clicks the body map (back, 40/55) to register a nodule; ABCDE checklist — 3+ flags show the suggest-biopsy badge; photos compare over time.
Scores PASI/EASI/DLQI trends for chronic disease follow-up.
Ophthalmologist: OD/OS exam — VA, refraction, IOP; IOP 34 → automatic critical alert; DR grade R2+ hints referral; prints a standard glasses Rx.
All 45 specialties run on one engine: structural ones add their own tables & panels; the rest are data-driven profiles with structured exam templates.
UC-8
UC-9 · LIVE

## Running the clinic day — Receptionist

Screens: Today's Queue · Waitlist · Schedules
Morning: the queue board shows waiting / in queue / with doctor / done, auto-refreshing; check-in moves patients along.
Dr. Omar calls in sick → add an unavailable schedule exception for today.his slots vanish instantly from staff booking AND the public portal — one availability engine
A full day? Add the patient to the waitlist with preferred date/time.
A cancellation lands → the system lists matching waitlisted patients and notifies them a slot opened.appointment.slot_available via the notifications hub
Capacity tuning: per-slot capacity and overbooking limits per doctor pattern; breaks subtracted automatically.
Follow-ups & referrals book pre-filled (patient, doctor, source) from the encounter or a completed referral.
UC-9
UC-10 · BUILT — in verification

## Emergency → admission — ER team → Ward

Modules: MedEmergency · MedWard
Arrival quick-reg (name + phone is enough to start), mode: ambulance.
Triage: vitals captured — RR 34, SpO₂ 88 → the system suggests emergent; GCS < 9 would suggest resuscitation; critical levels raise alerts.
ER board tracks the visit: awaiting triage → to be seen → in progress → pending results → disposition, with ticking time-in-department and today's door-to-doctor medians.
Disposition: admit → hand-off creates a pending ward admission; the visit boards as “admitted awaiting bed”.
Ward: bed board shows the free bed → admit (ADM number), bed occupied with history.
MAR generates scheduled doses from inpatient prescriptions (OD/BD/TID/QID parsed); controlled doses need a witness; fluid balance per shift.
ICU flowsheets (if ICU): hourly vitals, auto-MAP; MAP < 60 or SpO₂ < 90 raises critical alerts on the ICU dashboard strips.
Discharge workflow: summary required → bed released (marked dirty for cleaning) → “bed available” notification → waitlisted admissions proceed.
UC-10
UC-11 · BUILT — in verification

## Surgery under WHO safety — OR team

Module: MedSurgery + org OR rooms · ClinicCore consents
Book the case: procedures (CPT, laterality), team, ASA class, anesthesia plan, OR room & slot.the OR board warns on overlapping room bookings
No signed consent → the case cannot enter the OR.a consent-missing alert raises and auto-resolves once the signed consent links
WHO checklist phases — Sign-In, Time-Out (mandatory before incision), Sign-Out — each item ticked and signed.
Counts: sponge/instrument/needle pre vs close vs final — a discrepancy blocks completion until acknowledged with a note.
Post-op: findings, complications, specimens to pathology, implants (serial/lot) — searchable later in the implant registry for recalls.
Blood needed? Blood bank issues only crossmatch-compatible bags (FIFO by expiry); a transfusion reaction records type/severity and raises a critical alert. (MedBloodBank)
UC-11
UC-12 · LIVE (booking) + PLANNED (portal+)

## The patient's own journey — Patient

Books online from the clinic website or PWA — picks doctor, sees only truly free slots, confirms with OTP (no password needed).the same availability engine as the front desk; appointment lands as source=online
Gets reminded — appointment reminders and vaccination boosters via WhatsApp; “results ready” when the lab verifies.
PWA: views appointments and vaccination card; staff run their day on the staff PWA.
Phase 8 adds: family/dependents, medical-record release & download, invoices with online payment, secure messaging, telemedicine (video + virtual waiting room), symptom checker, PHQ-9/GAD-7 questionnaires, medication reminders, wellness tracking.
Cross-cutting in every use case: business/branch scoping on every row · role + attribute permissions (nurse ≠ doctor ≠ billing) · every send/view/print audited · all integrations fail-soft (a missing optional module never breaks a screen).
UC-12 · demo: https://localhost/shifa-one/public · shifa / 123456