Orders Service — Domain Model

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template

1. Aggregate Roots

1.1 Order

The central aggregate. Represents a single clinical order of any type.

ID prefix: ord_

Order types:

• medication → FHIR MedicationRequest
• laboratory → FHIR ServiceRequest (category: laboratory)
• radiology → FHIR ServiceRequest (category: imaging)
• procedure → FHIR ServiceRequest (category: procedure)
• referral → FHIR ServiceRequest (category: referral)
• nursing → FHIR ServiceRequest (category: nursing)
• diet → FHIR NutritionOrder
• activity → FHIR ServiceRequest (category: activity)

Invariants:

1. patientId must reference an active, non-deceased registered patient.
2. encounterId is required for all order types (orders must be encounter-bound).
3. orderedBy must hold a role with order entry permission for the order type.
4. CDS checks must complete before an order transitions from draft to active. A CDS hard-stop blocks activation; warning allows activation with acknowledgement.
5. A cancelled or completed order cannot be reactivated.
6. Optimistic locking: version field required on all mutations.
7. Tenant isolation enforced at DB level via RLS.
8. Idempotency-Key / clientMutationId prevents duplicate order creation.

State machine:

FHIR status mapping: draft→draft, active→active, on-hold→on-hold, completed→completed, cancelled→revoked, entered-in-error→entered-in-error.

---

1.2 OrderSet

A named template containing a pre-defined collection of order parameters that can be instantiated as a batch.

ID prefix: ords_

Invariants:

1. An OrderSet must contain at least one order template.
2. OrderSet templates are tenant-scoped but may be flagged as global (read-only system-wide templates).
3. Instantiation creates one Order aggregate per template entry.

---

2. Entities

Entity	Description	ID prefix
Order	Aggregate root; single clinical order	ord_
OrderSet	Template collection for batch order creation	ords_
CdsAlert	CDS check result attached to an order	cds_
OrderNote	Clinical note appended to an order	on_

3. Value Objects

Value Object	Fields	Notes
OrderCode	system, code, display	SNOMED CT for procedures; RxNorm/ATC for medications
MedicationDetail	medicationCode, dose, doseUnit, route, frequency, durationDays, prn	Medication-specific fields
LabDetail	specimenType, priority (routine/urgent/stat), fastingRequired	Laboratory-specific fields
RadiologyDetail	modality, region, laterality, contrastRequired	Radiology-specific fields
ReferralDetail	referralType (internal/external), referToFacilityId, referToSpecialty, urgency, clinicalSummary	Referral-specific fields
CdsSeverity	level (info/warning/hard-stop), message, ruleId	CDS alert severity
OrderPriority	routine/urgent/stat/asap	Order priority

4. Domain Events

Event	Trigger	Key payload fields
clinical.orders.order.created	Order created in draft	orderId, patientId, orderType, encounterId, orderedBy
clinical.orders.order.activated	Order transitions to active	orderId, patientId, orderType, cdsAlerts[]
clinical.orders.order.completed	Order fulfilled by downstream	orderId, patientId, orderType, completedAt
clinical.orders.order.cancelled	Order cancelled	orderId, patientId, cancelReason, cancelledBy
clinical.orders.order.on-hold	Order placed on hold	orderId, patientId, holdReason
clinical.orders.referral.created	Referral order activated	orderId, patientId, referralDetail, referToFacilityId
clinical.orders.order.corrected	Order entered-in-error	orderId, patientId, correctionReason

5. Consumed Events

Event	Source service	Purpose
REGISTRATION.patient.vital-status-changed.v1	registration-service	Block new orders for deceased patients
REGISTRATION.allergy.recorded.v1	registration-service	Refresh allergy cache for CDS checks
SCHEDULING.appointment.fulfilled.v1	scheduling-service	Trigger completion of associated referral orders

6. Ubiquitous Language

Term	Definition
CPOE	Computerised Physician Order Entry — electronic entry of clinician orders
Order	A clinical instruction to perform a service, administer a medication, or refer a patient
Order type	The classification of an order: medication, laboratory, radiology, procedure, referral, nursing, diet, activity
CDS	Clinical Decision Support — automated checks applied at order entry
Hard-stop	A CDS alert that prevents order activation until clinically resolved
Warning	A CDS alert that can be acknowledged and overridden by an authorized clinician
Order set	A named template of grouped orders that can be instantiated together
Referral	An order type directing a patient to another provider or facility
Requisition	Legacy term for laboratory or radiology order; replaced by laboratory and radiology order types per ADR-0046
Encounter-bound	Every order must be associated with an active encounter