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

# Enhancements Admin Guide

> This guide helps administrators configure, manage, and troubleshoot EN-27 (Server-Side CDS Evaluation), EN-28 (Clinical Pathways), and EN-29 (CDS Alert Analyti…

> **Purpose:** This guide helps administrators configure, manage, and troubleshoot EN-27 (Server-Side CDS Evaluation), EN-28 (Clinical Pathways), and EN-29 (CDS Alert Analytics).

***

## Overview

These three enhancements extend the CL-08 Clinical Decision Support module:

| Enhancement | Description                                       | Admin Involvement                        |
| ----------- | ------------------------------------------------- | ---------------------------------------- |
| **EN-27**   | Server-side drug interaction checks via RxNav API | Monitoring only; auto-deploys            |
| **EN-28**   | Clinical pathway definitions and patient progress | Permission assignment; pathway oversight |
| **EN-29**   | Alert fatigue analytics dashboard                 | Permission assignment; metric review     |

### Admin Responsibilities

| Responsibility        | Description                                                                  |
| --------------------- | ---------------------------------------------------------------------------- |
| Permission Management | Assign `cl.pathways.*` and `cl.cds_rules.*` permissions to appropriate roles |
| Pathway Governance    | Review and approve clinical pathway definitions                              |
| Alert Monitoring      | Monitor override rates and alert fatigue trends                              |
| Rule Tuning           | Adjust CDS rules based on analytics data                                     |
| Edge Function Health  | Monitor the `evaluate-cds` function for errors or degraded mode              |

***

## Prerequisites

### Required Permissions

| Permission            | Purpose                                  |
| --------------------- | ---------------------------------------- |
| `cl.pathways.manage`  | Create, edit, delete pathway definitions |
| `cl.cds_rules.manage` | Full CDS rule and analytics access       |
| `pf.roles.manage`     | Assign permissions to user roles         |

### System Requirements

* CDS rules must be configured (`cl_cds_rules` table) before EN-27/EN-29 produce data
* The `evaluate-cds` Edge Function is auto-deployed — no manual deployment needed

***

## Initial Setup

### Step 1: Assign Permissions

Assign permissions based on clinical roles:

| Role                 | Recommended Permissions                                                              |
| -------------------- | ------------------------------------------------------------------------------------ |
| Clinical Supervisor  | `cl.pathways.view`, `cl.pathways.manage`, `cl.cds_rules.view`, `cl.cds_rules.manage` |
| Licensed Clinician   | `cl.pathways.view`, `cl.cds_rules.view`                                              |
| Quality/Compliance   | `cl.cds_rules.view`, `cl.cds_rules.manage`                                           |
| Staff (non-clinical) | No CDS/pathway permissions                                                           |

**To assign permissions:**

1. Go to **Settings** → **Roles & Permissions**
2. Select the role to modify
3. Under the **Clinical** module, enable the required permissions
4. Save changes

### Step 2: Configure CDS Rules

CDS rules drive both EN-27 (evaluation) and EN-29 (analytics). Without active rules, the system generates no alerts.

1. Navigate to **Clinical** → **CDS Rules**
2. Create rules with appropriate types:
   * `drug_interaction` — Checks for interactions between drug classes
   * `drug_allergy` — Cross-references medications with allergies
   * `quality_measure` — Flags missing assessments
3. Set each rule's `trigger_event`, `severity`, and `condition.parameters`
4. Mark rules as **Active**

### Step 3: Review Pathway Definitions

If clinical pathways have been created:

1. Navigate to **Clinical** → **Clinical Pathways** → **Pathway Management**
2. Review each pathway for clinical accuracy
3. Deactivate any pathways that are not yet approved for use

***

## Configuration Reference

### EN-27: Edge Function Configuration

The `evaluate-cds` Edge Function requires no secrets or environment variables — it uses the public RxNav API (no authentication needed).

| Parameter         | Value                                                  | Notes                                |
| ----------------- | ------------------------------------------------------ | ------------------------------------ |
| RxNav API URL     | `https://rxnav.nlm.nih.gov/REST/interaction/list.json` | Public, rate-limited                 |
| Timeout           | 5 seconds                                              | AbortController-enforced             |
| Fallback behavior | Fail-open (degraded mode)                              | Returns `pass: true, degraded: true` |

### EN-28: Database Tables

| Table                    | Purpose                  | Key Fields                                                         |
| ------------------------ | ------------------------ | ------------------------------------------------------------------ |
| `cl_pathway_definitions` | Pathway templates        | `pathway_name`, `condition_type`, `steps` (JSONB), `is_active`     |
| `cl_pathway_progress`    | Patient pathway tracking | `chart_id`, `pathway_id`, `current_step`, `status`, `step_history` |

**RLS Policies:**

* SELECT/INSERT/UPDATE: `cl_has_org_access(organization_id, auth.uid())`
* DELETE: `cl_is_org_admin(organization_id, auth.uid())` — admin only
* UPDATE includes `WITH CHECK` to prevent cross-tenant data movement

### EN-29: Analytics Data Source

Analytics aggregate from `cl_cds_alerts` with joins to `cl_cds_rules` (rule names) and `pf_profiles` (provider names).

| Setting                  | Value                   | Notes                         |
| ------------------------ | ----------------------- | ----------------------------- |
| Default time window      | 30 days                 | User-selectable: 7d, 30d, 90d |
| staleTime                | 5 minutes               | Data refreshes automatically  |
| Provider name resolution | `pf_profiles.full_name` | Falls back to truncated UUID  |

***

## Routine Administration

### Weekly Tasks

* [ ] Review CDS Alert Fatigue Dashboard for override rates > 50%
* [ ] Check `evaluate-cds` Edge Function logs for errors or sustained degraded mode

### Monthly Tasks

* [ ] Audit pathway definitions for clinical accuracy and relevance
* [ ] Review per-provider alert metrics for training opportunities
* [ ] Tune or deactivate CDS rules with consistently high override rates

### Quarterly Tasks

* [ ] Comprehensive review of all active CDS rules against current clinical guidelines
* [ ] Evaluate pathway step content for evidence-based updates
* [ ] Generate alert fatigue report using 90-day time window

***

## Monitoring and Reports

### Edge Function Health (EN-27)

Monitor the `evaluate-cds` function:

| Metric                  | Target               | Where to Check                                                                                                |
| ----------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- |
| Error rate              | \< 1%                | [Edge Function Logs](https://supabase.com/dashboard/project/zkgxozahyczcnzpwhbbf/functions/evaluate-cds/logs) |
| Degraded mode frequency | \< 5% of evaluations | Edge Function logs (search for `degraded`)                                                                    |
| Latency                 | \< 3 seconds (p95)   | `latency_ms` in response payloads                                                                             |

### Alert Fatigue Metrics (EN-29)

| Metric                     | Target       | Where to Check                                  |
| -------------------------- | ------------ | ----------------------------------------------- |
| Overall override rate      | \< 30%       | CDS Alert Analytics Dashboard                   |
| Avg. acknowledgement time  | \< 5 minutes | CDS Alert Analytics Dashboard                   |
| Per-provider override rate | \< 50%       | Provider table (requires `cl.cds_rules.manage`) |

### Pathway Usage (EN-28)

| Metric                  | Target                 | Where to Check                               |
| ----------------------- | ---------------------- | -------------------------------------------- |
| Active pathways         | ≥ 1 per condition type | Pathway Management page                      |
| Pathway completion rate | > 70%                  | `cl_pathway_progress` (status = 'completed') |

***

## Troubleshooting

### Issue: Users Can't Access Pathways

**Symptoms:** Users see "Access Denied" shield on `/cl/pathways`

**Diagnostic Steps:**

1. Check user's role assignments in **Settings** → **Roles & Permissions**
2. Verify role includes `cl.pathways.manage` permission

**Resolution:** Assign `cl.pathways.manage` to the user's role.

***

### Issue: No Alerts Generated by EN-27

**Symptoms:** `evaluate-cds` returns `{ alerts: [], pass: true }` even with known interactions.

**Diagnostic Steps:**

1. Verify CDS rules exist and are active (`cl_cds_rules.is_active = true`)
2. Check that medications have `status = 'active'`
3. Check if medications include `rxcui` values (required for RxNav checks)
4. Review Edge Function logs for errors

**Resolution:**

* Ensure active CDS rules with correct `condition.parameters` (`drug_class_a`, `drug_class_b`)
* For RxNav interaction checks, medications must have valid `rxcui` codes
* For allergy checks, verify patient allergy records exist

***

### Issue: CDS Analytics Shows Stale Data

**Symptoms:** Dashboard data doesn't reflect recent alerts.

**Cause:** Query cache (5-minute staleTime).

**Resolution:** Refresh the page. Data updates automatically after 5 minutes.

***

### Issue: Edge Function in Sustained Degraded Mode

**Symptoms:** Logs show repeated `RxNav API unavailable` warnings.

**Diagnostic Steps:**

1. Check [RxNav API status](https://rxnav.nlm.nih.gov/)
2. Review Edge Function logs for timeout or network errors
3. Verify Edge Function can reach external URLs

**Resolution:**

* If RxNav is down, no action needed — the system operates safely in degraded mode
* Text-based rule matching continues to function as a fallback
* Monitor for when RxNav returns to normal operation

***

### Escalation Path

1. Check Edge Function logs at [Supabase Dashboard](https://supabase.com/dashboard/project/zkgxozahyczcnzpwhbbf/functions/evaluate-cds/logs)
2. Review `cl_cds_alerts` table for recent entries
3. Contact technical support with:
   * `request_id` from the CDS evaluation response
   * Time range of the issue
   * Screenshot of the analytics dashboard

***

## Security Considerations

### Data Access

* All CDS data is tenant-isolated via RLS policies with `organization_id` filtering
* Provider metrics in analytics resolve names from `pf_profiles` — no PHI exposed
* The `evaluate-cds` Edge Function validates JWT auth and org access before processing

### Audit Trail

* Every CDS evaluation includes `request_id`, `request_timestamp`, and `latency_ms`
* Alert persistence creates records in `cl_cds_alerts` with full provenance
* Break-glass access to CDS data follows standard clinical audit patterns

### External API Security

* RxNav API is public (no API key) — no secrets to manage
* 5-second timeout prevents Edge Function hangs
* No PHI is sent to RxNav — only RxCUI codes (standardized drug identifiers)

***

## Best Practices

### Configuration Best Practices

* ✅ Start with a small set of high-value CDS rules and expand based on analytics
* ✅ Set appropriate severity levels — reserve `critical` for true hard-stop scenarios
* ✅ Review override rates monthly and deactivate rules with > 70% override rates
* ✅ Define pathways with clear, measurable completion criteria at each step

### Security Best Practices

* ✅ Restrict `cl.cds_rules.manage` to supervisors and quality staff
* ✅ Review provider-level alert metrics to identify potential compliance gaps
* ✅ Ensure all pathway definitions are reviewed by a licensed clinician before activation

### Performance Best Practices

* ✅ Keep active CDS rule count reasonable (\< 50 rules per organization)
* ✅ Use RxCUI codes on medications for more accurate interaction checks
* ✅ Archive completed pathway progress records periodically

***

## Data Management

### Data Retention

| Data Type           | Retention Period         | Notes                               |
| ------------------- | ------------------------ | ----------------------------------- |
| CDS Alerts          | Indefinite               | Required for compliance audit trail |
| Pathway Definitions | Indefinite (soft delete) | Soft-deleted definitions preserved  |
| Pathway Progress    | Indefinite               | Patient clinical record             |

### Soft Delete

Pathway definitions use soft delete (`deleted_at` timestamp):

* Deleted pathways are hidden from the UI but preserved in the database
* Only org admins can delete pathways (RLS policy)
* Existing progress records linked to deleted pathways remain accessible

***

## Integration Points

| Feature                        | Integration                                            | Documentation                                       |
| ------------------------------ | ------------------------------------------------------ | --------------------------------------------------- |
| CDS Rule Management (CL-08)    | Rules drive EN-27 evaluation and EN-29 analytics       | Navigate to Clinical → CDS Rules                    |
| Medication Management (CL-05)  | Medications are the input for drug interaction checks  | `specs/cl/specs/CL-05-*.md`                         |
| Patient Charts (CL-01)         | Pathway progress is tracked per patient chart          | `specs/cl/specs/CL-01-*.md`                         |
| Platform Notifications (PF-10) | CDS alerts can trigger notifications via domain events | `docs/architecture/integrations/EVENT_CONTRACTS.md` |

***

## Change Log

| Version | Date       | Changes                                      |
| ------- | ---------- | -------------------------------------------- |
| 1.0.0   | 2026-02-26 | Initial release covering EN-27, EN-28, EN-29 |

***

## Related Documentation

* **User Guide:** `docs/guides/cl/cl-08-cds-enhancements-user-guide.md`
* **Specification:** `specs/cl/specs/CL-08-ENHANCEMENTS.md`
* **Edge Function Logs:** [Supabase Dashboard](https://supabase.com/dashboard/project/zkgxozahyczcnzpwhbbf/functions/evaluate-cds/logs)

***

**Last Updated:** 2026-02-26\
**Technical Support:** Contact your organization's system administrator.