Encore OS — Documentation

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:

Go to Settings → Roles & Permissions
Select the role to modify
Under the Clinical module, enable the required permissions
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.

Navigate to Clinical → CDS Rules
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
Set each rule’s trigger_event, severity, and condition.parameters
Mark rules as Active

Step 3: Review Pathway Definitions

If clinical pathways have been created:

Navigate to Clinical → Clinical Pathways → Pathway Management
Review each pathway for clinical accuracy
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
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:

Check user’s role assignments in Settings → Roles & Permissions
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:

Verify CDS rules exist and are active (cl_cds_rules.is_active = true)
Check that medications have status = 'active'
Check if medications include rxcui values (required for RxNav checks)
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:

Check RxNav API status
Review Edge Function logs for timeout or network errors
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

Check Edge Function logs at Supabase Dashboard
Review cl_cds_alerts table for recent entries
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

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

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

​Overview

​Admin Responsibilities

​Prerequisites

​Required Permissions

​System Requirements

​Initial Setup

​Step 1: Assign Permissions

​Step 2: Configure CDS Rules

​Step 3: Review Pathway Definitions

​Configuration Reference

​EN-27: Edge Function Configuration

​EN-28: Database Tables

​EN-29: Analytics Data Source

​Routine Administration

​Weekly Tasks

​Monthly Tasks

​Quarterly Tasks

​Monitoring and Reports

​Edge Function Health (EN-27)

​Alert Fatigue Metrics (EN-29)

​Pathway Usage (EN-28)

​Troubleshooting

​Issue: Users Can’t Access Pathways

​Issue: No Alerts Generated by EN-27

​Issue: CDS Analytics Shows Stale Data

​Issue: Edge Function in Sustained Degraded Mode

​Escalation Path

​Security Considerations

​Data Access

​Audit Trail

​External API Security

​Best Practices

​Configuration Best Practices

​Security Best Practices

​Performance Best Practices

​Data Management

​Data Retention

​Soft Delete

​Integration Points

​Change Log

​Related Documentation