Medication Service — Service Overview

Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · 03 platform-services · 02 DDD · FHIR-first

1. Purpose

The medication-service is the platform's canonical owner of medication knowledge, longitudinal medication lists, prescribing workflows, pharmacy fulfillment, dispensing, inventory, and medication administration (MAR). It provides the clinical meaning for every medication-related FHIR resource except the national interop copies of MedicationRequest / MedicationDispense that are mediated by the ghasi-eprescribing-gateway-service.

The service spans two historically separate modules:

Source module	Contribution
medication-management	Longitudinal med list, prescribe-time safety checks (drug-drug, drug-allergy, drug-condition, duplicate therapy), reconciliation, MAR, signing, dose calculation.
pharmacy	Fulfillment plane: dispensing queues, verification, inventory (lot/expiry/recall), pharmacy portal, external adapter hooks (NCPDP SCRIPT optional), controlled-substance dispense counter-sign.

2. Bounded Context

Medication Domain — classified as Core. Pharmaceutical safety is a differentiating clinical capability; medication-related data is the largest source of preventable adverse events in hospital care.

3. Responsibilities

Area	What medication-service Owns
Medication list	Longitudinal list per patient: active / on-hold / discontinued / completed / proposed; sources: prescribed, patient-reported, history, facility-administered.
Prescribing	Drafting, dose/sig/route/frequency structuring, formulary lookup, signing, renewal, refill, substitution (DAW), discontinue, hold/resume.
Safety checks	Allergy checks (vs allergies in patient-chart-service), drug-drug interactions, drug-condition, duplicate therapy, dose range validation. Uses configurable knowledge-base adapter.
Reconciliation	Admission, transfer, discharge, outpatient reconciliation sessions with side-by-side diff + actions.
Administration (MAR)	MedicationAdministration events: given / held / refused / not-available; timing, route actual, administered-by.
Fulfillment queue	Projection of gateway MedicationRequest into pharmacy work items; verification; print labels; PDF prescription output.
Dispensing	MedicationDispense writes, atomic inventory decrement, partial dispense, returns, emergency override with reason.
Inventory	Stock items per facility node: NDC/local code, lot, expiry, supplier, quantity-on-hand, reorder points, recalls, valuation.
Pharmacy portal	Standalone offline-first portal for pharmacists and technicians; separate from clinical shell.
Controlled substances	Counter-sign at dispense, enhanced audit, disclosure accounting. Prescribe-time CS rules delegated to Access-Policy / tenant-service.
Alerts & overrides	Blocking + non-blocking alerts; override record with reason (≥10 chars), drug-KB snapshot version, actor.

4. Non-Responsibilities

Area	Owner	Why not medication-service
National interop MedicationRequest / MedicationDispense SoT	ghasi-eprescribing-gateway-service	Cross-tenant / cross-org routing and validation is a gateway-level concern; this service authors the clinical intent, gateway persists the interop copy.
CPOE order lifecycle for medication	orders-service	Orders-service owns the general CPOE ServiceRequest / order lifecycle; it produces MedicationRequest on activation and delegates safety checks here.
Allergies storage	patient-chart-service	medication-service reads AllergyIntolerance via FHIR; it does not own the allergy record.
Conditions / problem list	patient-chart-service	Drug-condition checks read Condition; they are not written here.
Terminology (RxNorm, ATC, NDC)	terminology-service	medication-service references codes; terminology-service owns valuesets and expansion.
Billing charge generation	billing-service	medication-service emits a dispense event; billing-service turns it into ChargeItem.
Notifications (SMS/email on ready-for-pickup)	communication-service	medication-service emits events; communication-service delivers.

5. Dependencies

5.1 Upstream

Dependency	Pattern	Purpose
orders-service	Event consumer + FHIR read	Consumes orders.medication_request.activated.v1 to create medication-list entries and fulfillment rows.
patient-chart-service	FHIR read	Allergy, problem-list, vitals for safety checks.
terminology-service	REST	Code lookup, valueset expansion for sig/route/frequency.
ghasi-eprescribing-gateway-service	Event consumer + FHIR read	Ingests eprescribing.medication_request.created.v1 for cross-tenant Rx arriving from external prescribers.
identity-service	JWT	AuthN; prescriber / pharmacist roles via tenant-service role claims.
tenant-service	REST	Access-Policy for controlled substances, formulary configuration per tenant.

5.2 Downstream

Consumer	Pattern	Purpose
ghasi-eprescribing-gateway-service	HTTP POST	Posts MedicationDispense to gateway for national interop; posts MedicationRequest when prescribing for external pharmacies.
billing-service	Event consumer	Charges on medication.dispensing.completed.v1.
communication-service	Event consumer	Ready-for-pickup, refill reminder notifications.
patient-chart-service	Event consumer	Medication-list projection for chart summary.
audit-service	Event consumer	Immutable audit of every prescribe/sign/dispense/override.
population-health-service	Event consumer	Medication adherence metrics, controlled-substance surveillance.

6. Slice Involvement

Slice	Scope	Milestone
S1 — Core Clinical	Med list, prescribe + sign, allergy + interaction checks, MAR basic	M1
S2 — Fulfillment	Pharmacy queue ingestion, dispensing, inventory lot/expiry, reconciliation sessions	M2
S3 — Advanced	Controlled substances counter-sign, offline pharmacy portal, recalls, NCPDP optional adapter	M3
S4 — Enterprise	Full IG profile validation, analyzer-grade KB, dose-calc for pediatrics/renal, MoPH controlled-substance reporting	M4

7. Architectural Decisions

1. Single service merges prescribe + fulfill to keep the longitudinal medication graph intact (prescriber intent, dispense events, administrations) and to preserve referential integrity at the DB layer. Both sub-domains share a common Medication reference table.
2. Gateway is authoritative for interop copies. Local prescriptions is a fulfillment projection keyed by gateway_medication_request_fhir_id. Clinical chart writes happen locally; interop writes post to the gateway.
3. Pharmacy portal is a separate Next.js surface under the same service, not a separate service. Rationale: shared domain model + RLS + same deployment cadence; different shell app only.
4. Drug knowledge base behind a port. DrugKnowledgeBase port has adapters for: local formulary + terminology-service, external licensed DB (e.g. First Databank), WHO EML baseline. Alerts include KB-snapshot-version in the override record.
5. Inventory decrement is transactional with dispense. Single SQL transaction updates dispensing_events, decrements stock_items.quantity_on_hand, writes outbox entry. No saga; rollback on any failure.
6. Controlled-substance dispense requires counter-sign — a different actor than the dispenser. Schedule II always; Schedule III–V by tenant policy.

8. Architecture Diagram

9. Source Reconciliation

medication-management and pharmacy source modules merged using these decisions:

Question	Decision
Single or split aggregate for prescription vs dispense?	Single domain, two aggregates (Prescription, DispensingEvent) with shared Medication VO.
Where does MedicationAdministration live?	Here (MAR), consumed by patient-chart-service for chart display.
Prescribe-time alert overrides	Recorded here with KB snapshot; delegated to medication-management aggregate.
Dispense-time controls	Own aggregate DispensingEvent with inventory transaction + counter-sign invariant.
FR-ID prefix harmonization	Both FR-MEDS-* and FR-PHARM-* legacy refs preserved with new prefix FR-MED-*.
Events	Unified under medication.* subject; legacy MEDICATION.* and PHARMACY.* documented as deprecated with dual-publish in M2.

10. Readiness Levels

Level	Description	Target
L2	Med list, prescribe, sign, alerts, MAR; basic dispensing queue	M1
L3	Inventory, reconciliation, recalls, controlled-substance dispense	M2
L4	Offline pharmacy portal, NCPDP/HL7 adapters, full IG validation, chaos-tested	M3+