> ## 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.

# MAT/MOUD Tracking — Admin Guide

> This guide covers administrative configuration for the MAT/MOUD Tracking module.

## Overview

This guide covers administrative configuration for the MAT/MOUD Tracking module (CL-21).

## Quick Reference

| I need to...                              | Pattern                           | Location                                    |
| ----------------------------------------- | --------------------------------- | ------------------------------------------- |
| Configure MAT access                      | Permission keys + role assignment | [Permission Keys](#permission-keys)         |
| Validate consent-based access behavior    | CL-11 consent + RLS enforcement   | [Consent Enforcement](#consent-enforcement) |
| Check planned operational tuning controls | `cl_module_settings` roadmap      | [Future Settings](#future-settings)         |
| Verify integration readiness              | CL/PM/PF integration status       | [Integration Points](#integration-points)   |

***

## Permission Keys

Assign these permissions via **Settings > Roles & Permissions**:

| Permission Key                    | Category | Description                              |
| --------------------------------- | -------- | ---------------------------------------- |
| `cl.moud.view`                    | view     | View MAT enrollments and related events  |
| `cl.moud.enroll`                  | create   | Create and edit MAT enrollments          |
| `cl.moud.medication-event.create` | create   | Record medication dose events            |
| `cl.moud.monitoring.manage`       | edit     | Manage monitoring schedules and results  |
| `cl.moud.report.view`             | view     | Access MAT outcome and adherence reports |

**Note:** The `org_admin` role is automatically granted all permissions via the `pf_auto_grant_org_admin` trigger.

***

## Default Role Assignments

| Role        | Permissions Granted                                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
| `org_admin` | All 5 permissions (auto-granted)                                                                                        |
| `manager`   | `cl.moud.view`, `cl.moud.enroll`, `cl.moud.medication-event.create`, `cl.moud.monitoring.manage`, `cl.moud.report.view` |
| `staff`     | `cl.moud.view`, `cl.moud.medication-event.create`, `cl.moud.monitoring.manage`                                          |

***

## Data Retention

MAT/MOUD records do **not** support soft delete (`deleted_at`). This is intentional:

* **42 CFR Part 2** requires retention of SUD treatment records
* DELETE operations are restricted to `org_admin` role only (via RLS)
* Enrollments can be set to "Discontinued" or "Completed" status instead of deletion

***

## Consent Enforcement

The system enforces 42 CFR Part 2 consent at the RLS (database) level:

* If a `consent_id` is linked to an enrollment, that specific consent must be active
* If no `consent_id` is set, chart-level SUD consent flags are checked
* Without valid consent, MAT records are inaccessible (queries return empty)

***

## Future Settings

The following settings are planned for future releases and will be configurable in `cl_module_settings`:

* **Monitoring cadence defaults** — default intervals for UDS, hepatic panels
* **Adherence risk thresholds** — missed-dose count triggering alerts
* **Overdue monitoring alert rules** — notification timing for overdue items

***

## Database Tables

| Table                       | Purpose                                  |
| --------------------------- | ---------------------------------------- |
| `cl_moud_enrollments`       | MAT enrollment records per patient chart |
| `cl_moud_medication_events` | Individual medication dose/event records |
| `cl_moud_monitoring_events` | Lab and screening monitoring schedules   |

All tables enforce RLS with `FORCE ROW LEVEL SECURITY` and multi-tenant isolation via `organization_id`.

***

## Integration Points

| Integration      | Status     | Description                        |
| ---------------- | ---------- | ---------------------------------- |
| CL-11 (Consent)  | ✅ Active   | 42 CFR Part 2 consent enforcement  |
| CL-10 (Outcomes) | 📋 Planned | CBE #3400 pharmacotherapy metrics  |
| PM-07 (Billing)  | 📋 Planned | Charge triggers for MAT encounters |
| PF-10 (Alerts)   | 📋 Planned | Overdue monitoring notifications   |

***

## Troubleshooting

| Issue                                           | Likely Cause                                                                                  | Resolution                                                                                     |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| MAT enrollment inaccessible despite valid login | Consent requirements not satisfied (`consent_id` inactive or chart-level SUD consent missing) | Verify consent status in CL-11 and re-check linked enrollment/chart consent context            |
| Monitoring alerts not firing                    | PF-10 integration is still planned/not active                                                 | Confirm current integration status and verify planned cadence settings in `cl_module_settings` |
| Unable to enroll patient                        | Missing `cl.moud.enroll` permission                                                           | Update role mapping in Settings → Roles & Permissions and retry                                |