Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Feature ID: CL-05
Status: ✅ Implemented
Spec Reference: CL-05-medication-management-reconciliation.md
Last Updated: 2026-02-17
Last Verified: 2026-02-18

​
Table of Contents

​
Overview

CL-05 provides medication list management, medication reconciliation at transitions of care, and safety alerts (drug-drug, drug-allergy, duplicate therapy). It depends on CL-01 (patient chart); integrates with CL-06 (e-prescribing), CL-08 (clinical decision support), CL-09 (lab orders), and CL-12 (care transitions).

​
Quick Reference

ItemValue
Core tablescl_medications, cl_medication_reconciliations
Safety dependenciesCL-08 (drug interactions), CL-09 (monitoring labs)
Transition triggersAdmission, transfer, discharge, LOC change
Controlled-substance requirementTamper-evident audit logging

​
Decision Trees

​
Reconciliation trigger path

  1. Detect transition event (admission/transfer/discharge/LOC change).
  2. Create reconciliation record with reconciliation_type.
  3. Compare prior list vs current orders and record discrepancies.
  4. Resolve/acknowledge discrepancies and finalize reconciliation.

​
Alert handling path

  1. Submit active med list + allergies to CL-08 CDS service.
  2. Receive interaction severity result.
  3. If severity is critical/major, require clinician acknowledgement before save.

​
Pattern Library

PatternUsage
Event-triggered reconciliationTransition events create reconciliation tasks
Platform CDS adapterCL-08 handles interaction logic while CL-05 owns medication state
Monitoring protocol automationmonitoring_protocol drives CL-09 lab workflow hooks

​
Integration Points (from Spec)

DependencyPatternPurpose
CL-01 (Patient Chart)DataMedication list displays on patient chart; cl_medications.chart_id → cl_patient_charts.id
CL-06 (E-prescribing)API / DataE-prescribing creates medication records in cl_medications
CL-08 (Clinical decision support)APIInteraction/monitoring alerts; drug interaction source: RxNav/NLM APIs (MVP); interface documented for future FDB swap
CL-09 (Lab orders)API / EventLab orders triggered by monitoring protocols (monitoring_protocol JSONB)
CL-12 (Care coordination / transitions)Event / APIReconciliation triggered at admission, transfer, discharge; transition_event can reference transition

​
API / Data Contracts

  • Medication list: cl_medications (organization_id, chart_id); status includes active, discontinued, on_hold, completed, entered_in_error; soft-delete via deleted_at. RxNorm/NDC for interoperability.
  • Reconciliation: cl_medication_reconciliations; reconciliation_type in (‘admission’, ‘transfer’, ‘discharge’, ‘loc_change’); discrepancies JSONB schema per spec Errata E-4; transition_event optional (event ID or free text for audit).
  • CL-08 drug interaction: Request (medication list + allergy list); response (interactions with severity: critical, major, moderate, minor; duplicate therapy; allergy cross-reference). Data source: RxNav/NLM APIs (MVP); interface abstracted for future FDB (First Databank) swap.
  • CL-09 monitoring: cl_medications.monitoring_protocol drives lab order triggers (lithium, clozapine, metabolic panel); schema per spec Errata E-2.

​
Labeled Code Examples

​
Example: medication reconciliation payload

{
  "organization_id": "org-uuid",
  "chart_id": "chart-uuid",
  "reconciliation_type": "discharge",
  "transition_event": "ADT-A03",
  "discrepancies": [
    { "medication": "Lithium", "issue": "dose_mismatch", "action": "review_required" }
  ]
}

​
Example: monitoring protocol shape

{
  "labs": ["CMP", "A1C"],
  "frequency_days": 90,
  "alert_thresholds": { "lithium_level": "1.2" }
}

​
Event Contracts

  • Inbound: Care transition events (from CL-12 or workflow) trigger reconciliation workflow; payload should include chart_id, transition type, and optional transition_event reference.
  • Outbound: medication_reconciliation_completed — published when a reconciliation record is finalized (status → ‘completed’). Publisher: CL-05. Subscriber: PF-10 (notifications). Payload: { organization_id, chart_id, reconciliation_id, reconciliation_type, reconciled_by }. Seeded in fw_workflow_events (category: operational). Registered in KnownEventName in src/platform/events/types.ts.

​
Security and RLS

  • RLS on cl_medications and cl_medication_reconciliations via cl_has_org_access(organization_id, auth.uid()) (SECURITY DEFINER — matches CL-01 through CL-04 pattern). FORCE ROW LEVEL SECURITY enforced on both tables. No separate cl_check_medication_access function (removed — violated platform RLS pattern by querying RLS-protected tables and hardcoding roles).
  • All UPDATE policies include WITH CHECK (constitution §5.2.4).
  • Controlled substances (schedule II–V, is_controlled): tamper-evident audit logging required (user_id, timestamp, action, reason).
  • Drug interaction and allergy data are PHI; audit logging required.

​
Common Mistakes

MistakeImpactFix
Missing request_trace_id in eligibility-style external checksPoor auditabilityPersist trace IDs for external calls
Not filtering soft-deleted rowsStale/incorrect med displayAlways enforce deleted_at IS NULL in active views
Skipping controlled-substance audit fieldsCompliance exposureRequire actor, timestamp, reason for controlled-substance updates

​
Pre-Flight Checklist

  • Validate RLS helper usage on medication and reconciliation tables.
  • Confirm reconciliation flow covers all transition types.
  • Validate CDS integration fallback behavior for upstream outages.
  • Confirm controlled-substance audit logging for creates/updates/discontinues.
  • Validate monitoring protocol → lab order trigger mapping.