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-21
Status: 🏗️ Scaffolded (event contracts are placeholders)
Spec Reference: CL-21-medication-assisted-treatment-moud-tracking.md
Last Updated: 2026-02-23

​
Overview

CL-21 defines MAT/MOUD enrollment, medication events (ordered, prescribed, administered, dispensed, held, missed), and monitoring events (UDS, hepatic panel, etc.) for opioid treatment and behavioral health programs. It integrates with CL-05 (medications), CL-06 (e-prescribing), CL-10 (outcomes/CBE #3400), CL-11 (consent/42 CFR Part 2), PM-07 (charge triggers), PF-10 (alerts), and PF-70 (terminology).

​
Quick Reference

I need to…PatternLocation
Enforce consent before MAT accessSUD MAT: require linked consent_id (42 CFR Part 2); deny if absent. Non-SUD MAT: may use chart-level SUD flag.RLS on cl_moud_enrollments, cl_moud_medication_events, cl_moud_monitoring_events
Trigger charge capture for MATPM-07 charge inputs from enrollment/medication/monitoring contextAPI_CONTRACTS / CL-PM Encounter-to-Billing
Send overdue monitoring alertsPF-10 Platform NotificationsEVENT_CONTRACTS when defined
Use permission keyscl.moud.view, cl.moud.enroll, cl.moud.medication-event.create, cl.moud.monitoring.manage, cl.moud.report.viewPF-30 seed

​
Pattern Library

  • Consent-gated MAT access: Always resolve consent via consent_id on enrollment or chart-level SUD consent; enforce in RLS with SECURITY DEFINER helpers (no direct query to RLS-protected tables).
  • Charge context: Pass enrollment/medication/monitoring context to PM-07 for encounter-to-charge mapping.
  • Alerts: Publish overdue monitoring / missed-dose events via PF-10 when event contracts are defined.

​
Common Mistakes

PitfallFix
Reading MAT data without CL-11 consent checkEnforce consent in RLS; use SECURITY DEFINER helper that checks consent_id or chart SUD flag.
Missing WITH CHECK on UPDATE policiesAdd WITH CHECK (organization_id) per constitution §5.2.4.
Exposing raw MAT/SUD data in logsLog only non-PHI identifiers; see constitution.md §4.2 (PHI / PII Handling).

​
Pre-Flight Checklist

  • CL-11 consent enforcement in place for all MAT tables.
  • Permission keys seeded (PF-30); UI gated by cl.moud.*.
  • UPDATE policies include WITH CHECK on organization_id.
  • No direct queries to RLS-protected tables inside policies.

​
Decision Tree (major choices)

​
Integration Points (from Spec)

DependencyPatternPurpose
PF-01 (Organizations & Sites)DirectMulti-tenant isolation
PF-02 (RBAC)DirectPermission keys
PF-10 (Notifications)PlatformOverdue monitoring and missed-dose alerts
PF-70 (Terminology)PlatformCoding support where required
CL-01 (Patient Chart)InternalChart-scoped enrollment and events (chart_id)
CL-05 (Medication Management)InternalMedication reconciliation context
CL-06 (E-Prescribing)InternalPrescription and pharmacy workflows
CL-10 (Outcomes)InternalMAT outcome metrics and CBE #3400 derivations
CL-11 (Consent / 42 CFR Part 2)InternalConsent checks before MAT access; see Consent (CL-11) subsection below
PM-07API / DataCharge trigger inputs for MAT encounters and services; see CL-PM Encounter-to-Billing
  • consent_id on cl_moud_enrollments is optional only for non-SUD MAT cases. For SUD MAT, a linked 42 CFR Part 2 consent must be used.
  • When consent_id is null, the system falls back to chart-level SUD consent flags (CL-11) via RLS policies before any read/write access to MAT enrollment or related events.
  • When consent_id is present, it ties to a specific consent record for that MAT episode.
  • All access to cl_moud_enrollments and related events (cl_moud_medication_events, cl_moud_monitoring_events) must pass the CL-11 consent check—either the linked consent_id or the chart-level SUD consent flag—enforced in RLS via SECURITY DEFINER helpers. See CL-11 Consent Integration.

​
Integration Type Mapping (for CROSS_CORE_INTEGRATIONS matrix)

DependencyIntegration TypeContract / Behavior
CL-10DataOutcome metrics and CBE #3400 derivations from enrollments and medication/monitoring events; consumed via shared tables and reporting. See CL-10 Outcomes Integration.
PF-10Event (Platform)Overdue monitoring and missed-dose alerts delivered via Platform Notifications; event contracts in EVENT_CONTRACTS.md when defined.
PM-07API / DataCharge trigger inputs for MAT encounters and services; API or data contract for encounter-to-charge context. See CL-PM Encounter-to-Billing and API_CONTRACTS.md when defined.
CL-05, CL-06DataMedication reconciliation and prescription context; shared chart/medication data.
CL-11Data (consent)Consent checks before MAT access; see Consent (CL-11) subsection below.
PF-70PlatformTerminology and coding support; platform code library.

​
API Contracts

  • PM-07 charge triggers: Inputs for MAT encounters and services (enrollment/medication/monitoring context) for charge capture. Document in API_CONTRACTS.md or CL-PM Encounter-to-Billing when implemented.
  • Enrollments: cl_moud_enrollments — enrollment, phase, status; consumed by CL-10 and reporting.
  • Medication events: cl_moud_medication_events — dosing and adherence; feeds CL-10 numerator/denominator logic.
  • Monitoring events: cl_moud_monitoring_events — UDS/lab due and completion; drives PF-10 alerts.
(Add request/response or event schemas here when APIs or events are defined.)

​
Event Contracts

  • PF-10 (Platform): Overdue monitoring and adherence-risk alerts published via Platform Notifications (Platform Integration Layer).
  • Event contracts are defined in EVENT_CONTRACTS.md as:
    • cl_moud_monitoring_overdue
    • cl_moud_adherence_risk
  • See EVENT_CONTRACTS.md for payload definitions.

​
Security and RLS

  • PHI/SUD: strict RLS and CL-11 consent enforcement before access.
  • RLS on cl_moud_enrollments, cl_moud_medication_events, cl_moud_monitoring_events via SECURITY DEFINER helpers; no direct queries to RLS-protected tables in policies (constitution §5.7).
  • UPDATE policies must include WITH CHECK on organization_id (constitution §5.2.4).
  • Permission keys: cl.moud.view, cl.moud.enroll, cl.moud.medication-event.create, cl.moud.monitoring.manage, cl.moud.report.view (seed in migration per PF-30).