Skip to main content

medOS Clinical

Internal scope: ever-api-clinical — encounters, clinical notes, episode of care, and core clinical records.

medOS Clinical owns the of-record clinical entities at the centre of a patient's visit: encounters, clinical documentation, episode-of-care linkage, and the specialised clinical records that hang off them (referrals, medical certificates, adverse drug reactions, bed-status transitions, and post-anaesthesia care). It inherits most of its schema from the shared platform-api-schema package and communicates with the rest of the mesh over NATS as a Moleculer service. Many status-changing actions publish to the read-model layer so dashboards, queues, and the encounter journey stay in sync.

NATS
Service mesh transport
Mongo
Primary write store
7+
Clinical modules
FHIR
Mapped to R4

Responsibilities​

  • Encounters & episode of care — the encounter is the unit clinical records attach to; episode-of-care linkage groups encounters into a longitudinal course of treatment.
  • Clinical documentation — notes and structured clinical records inherited from shared schemas and exposed through composed services.
  • Specialised clinical records — referrals, medical certificates, adverse drug reactions, and perioperative (PACU) handoff and discharge decisions.
  • Bed status transitions — a state machine driving admit / transfer / discharge bed movements that feed the bed board read model.
  • Scope-of-practice enforcement (AHP) — a server-side trust anchor for the AHP-led care pathway, the authoritative gate between an unlicensed operator and an of-record clinical write.
  • Event emission — status changes are published to hospital_events for the read-model orchestrator to project.

Major modules​

ModulePurpose
referralPatient referral lifecycle (create, route, accept) with read-model event emission
medicalCertificateIssuance and management of medical certificates, with document numbering
adverseDrugReactionADR recording linked to the encounter, surfaced to the patient record
bedStatusMachineBed-status state machine — admit / transfer / discharge transitions feeding the bed board
pacuHandoffPost-anaesthesia care unit (PACU) handoff records and SBAR-style transfer of care
pacuDischargeDecisionPACU discharge readiness decisions tied to the encounter
ahpAHP-led care pathway enforcement (entitlement, red-flag detector, lane-decision gate)
_sequenceClinical document / record numbering
_settingPer-deployment clinical service configuration

Most core clinical entities (the encounter and its notes) are exposed through composed services that pull from the shared platform-api-schema package rather than from a dedicated module folder in this service.

Workflow

Read-model events

Status-changing actions across referral, bed-status, ADR, medical certificate, and PACU modules emit to hospital_events so the encounter orchestrator can project department queues and the encounter journey cache.

Safety

AHP trust anchor

The ahp module re-makes the lane decision server-side (Lane A capped / Lane B cosign / refer / blocked) — advisory frontend UX is never the gate.

AHP-led care pathway (scope-of-practice gate)​

The ahp module is the server-side trust anchor for the AHP-led care pathway (physician-absent / doctorless clinics). It is a regulated, default-OFF module — enforcement is enabled only when AHP_CARE_PATHWAY_ENABLED is exactly true.

HelperRole
ahpEntitlement.helper.tsBackend entitlement check; default-OFF for regulated safety
redFlagDetector.shared.tsDeterministic, presentation-based red-flag detector — missing input or evaluation error both escalate
ahpEnforcement.helper.tsenforceAhpGate() — re-derives the lane decision (Lane A capped / Lane B cosign / refer / blocked)

The helpers ship as scaffolding (the hard gate is wired at a later phase before any AHP-led encounter touches a real patient). See the Architecture overview for the broader pattern.

Events & integration​

Status-changing actions publish to the hospital_events stream consumed by the read-model orchestrator. A simplified flow:

  Clinical action (referral / bed transition / ADR / PACU / certificate)
        │
        ▼
  ever-api-clinical  ──emit──►  hospital_events
        │                            │
   Mongo write                  orchestrator
   (of record)                       │
                                     ▼
                       read models (queues, journey cache)
                                     │
                                     ▼
                         frontend realtime subscription

Clinical entities are also mapped to FHIR R4 resources (for example Encounter, Condition, and Appointment) for external read/write through the FHIR layer — see FHIR Integration.

NATS meshhospital_events emissionFHIR R4 mappingAHP enforcement (default-OFF)

Configuration flags​

AHP_CARE_PATHWAY_ENABLEDfhir.write.enabled

Behaviour is additive and fail-open by default; regulated features such as AHP enforcement must be explicitly turned on per deployment.

  • CL-8 — Doctor Order Entry (CPOE)
  • CL-11 … CL-15 — Clinical documentation
  • CL-18 … CL-20 — Diagnosis
  • CL-25, CL-26 — Clinical Dashboard & Summary View

See also​