CL–RH: Residential Medication Administration Record (MAR) Integration

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.

​

Purpose

​

Integration Type

• Event-based: CL publishes when medication list changes; RH subscribes to refresh MAR.
• Platform layer: Read API for RH to fetch resident medications (e.g. getResidentMedications()) so RH can display MAR without querying CL tables directly.

​

Event Contract

​

Event: cl_medication_list_updated

​

Purpose

​

Trigger Conditions

• Trigger 1: INSERT or UPDATE on CL medication list table (e.g. cl_medications or equivalent) that affects “active” medications for a patient who has a current residence in RH (or broadcast; RH filters by resident).
• Trigger 2: Optional: on encounter or reconciliation completion that updates active meds.

​

Payload Schema

interface ClMedicationListUpdatedPayload {
  event_type: 'cl_medication_list_updated';
  organization_id: uuid;
  timestamp: timestamptz;
  chart_id: uuid;
  site_id?: uuid;
  user_id?: uuid;
  correlation_id?: uuid;
  // Optional: list of medication ids or summary so RH can refetch
  medication_ids?: uuid[];
}

​

Consumer Actions

​

Operational Requirements

• Idempotency: RH can refetch full list by chart_id; duplicate events result in same MAR state.
• Retry: Event consumer may retry; idempotent refetch is safe.
• Versioning: Add event_version: '1.0' if payload evolves.

​

Security and Compliance (event cl_medication_list_updated, payload ClMedicationListUpdatedPayload, chart_id)

• 42 CFR Part 2: Require explicit patient consent or documented integrated-care consent before RH may subscribe to or receive medication data for SUD-related medications. Enforce subscriber authorization checks scoped to chart_id prior to publishing. Log all publications and recipients for audit. Apply multi-tenancy/RLS controls where applicable. Publisher-side filtering: only emit events for residents for whom RH is authorized to receive medication data.

​

Platform Integration Layer

​

API: getResidentMedications (or equivalent)

​

Purpose

​

Contract

• Location: @/platform/clinical — medication-related APIs remain colocated with clinical data; no separate @/platform/residential-mar layer. See PLATFORM_INTEGRATION_LAYERS.md.
• Function/hook: e.g. getResidentMedications(organizationId, chartId): Promise<ResidentMedicationSummary[]> returning medication name, dose, route, frequency, prescriber, start/end date, and any MAR-relevant flags (e.g. self-admin vs witnessed).
• Security: Organization and chart scoped; caller must have access to the resident’s chart (via RH resident–chart link). Use SECURITY DEFINER or RPC that enforces org/chart access. 42 CFR Part 2 (MOUD): Callers must present and verify documented consent or a qualifying exception before MOUD-related fields are returned; SECURITY DEFINER/RPC must filter or redact MOUD entries when authorization is missing. Store/validate consent at chart level (e.g. CL-11). Audit log every access to 42 CFR Part 2–protected medication records (who, when, chart_id).

​

Data Flow

1. CL-05 maintains active medication list per chart.
2. When med list changes, CL publishes cl_medication_list_updated (optional).
3. RH (or platform layer) subscribes and/or calls getResidentMedications(chart_id) to refresh MAR.
4. RH displays MAR to residential staff; no direct CL table access from RH code.

​

Implementation Notes

• CL side: Emit event on medication list change; expose read-only API or RPC that returns active medications for a chart (with org_id check).
• RH side: Map resident to chart_id (existing or new); on event or on MAR view load, call platform API to get medications; render MAR view. Platform layer lives in @/platform/clinical; see PLATFORM_INTEGRATION_LAYERS.md.

​

Testing Requirements

• Event payload structure validation
• Event fires when CL medication list updated for a chart
• RH (or test consumer) receives event and refetches; MAR data matches CL list
• getResidentMedications returns only org/chart-authorized data; RLS or RPC enforces tenant isolation
• 42 CFR Part 2 — getResidentMedications redaction: Verify getResidentMedications redacts MOUD/Part 2 entries when consent is missing (no MOUD medication details in response for that chart when CL-11 consent not present or revoked).
• 42 CFR Part 2 — medication-change event gating: Verify the integration does not publish the medication-change event (or equivalent) when the subscriber lacks Part 2 authorization for the chart; test with unauthorized RH context.
• 42 CFR Part 2 — audit logging: Validate audit logging captures all medication access attempts, including denied reads (failed consent check or unauthorized caller); reference PF-40 and CL-11 audit requirements.
• 42 CFR Part 2 — consent revocation: Confirm consent revocation prevents subsequent access and events; after revocation, getResidentMedications must not return Part 2–protected meds and no new events for that chart to that consumer.

​

References

• CL-05-medication-management-INTEGRATION.md
• CROSS_CORE_INTEGRATIONS.md
• EVENT_CONTRACTS.md — add cl_medication_list_updated entry
• PLATFORM_INTEGRATION_LAYERS.md
• specs/cl/CL-STRATEGIC-ROADMAP-20260302.md