Feature ID: CL-26Documentation Index
Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
Use this file to discover all available pages before exploring further.
Module: CL (Clinical & EHR)
Version: 1.0
Last Updated: 2026-02-25
Overview
This guide covers administrative configuration for the Patient-Reported Outcomes & Self-Service Portal feature. Organization administrators can manage permissions, review workflows, and understand the data model.Permission Configuration
CL-26 introduces three permission keys. These are automatically seeded fororg_admin and staff roles.
| Permission Key | Description | Recommended Roles |
|---|---|---|
cl.patient-submissions.view | View submissions list and detail pages | All clinical staff |
cl.patient-submissions.review | Change submission status (reviewed/incorporated) | Licensed clinicians, supervisors |
cl.between-session-checkins.view | View between-session check-in data | All clinical staff |
- Go to Settings → Permissions (org_admin only).
- Find the CL module permissions.
- Assign or remove permissions per role as needed.
Supported Screening Instruments
| Instrument | Questions | Scoring | Crisis Detection |
|---|---|---|---|
| PHQ-9 | 9 (Likert 0–3) | 0–27, severity bands | Q9 (suicidal ideation) ≥ 1 |
| GAD-7 | 7 (Likert 0–3) | 0–21, severity bands | None |
| AUDIT-C | 3 (Likert 0–4) | 0–12, positive ≥ 3 | None |
| DAST-10 | 10 (Yes/No) | 0–10, severity bands (Q3 reverse-scored) | None |
| C-SSRS Screener | 6 (Yes/No) | 0–6 positive items | Any positive = crisis |
Data Model
cl_patient_submissions
Stores all patient-submitted screening results.| Column | Type | Description |
|---|---|---|
| id | UUID | Primary key |
| organization_id | UUID | Tenant isolation |
| chart_id | UUID | Patient chart (composite FK) |
| submission_type | TEXT | Instrument type (CHECK constraint) |
| submitted_at | TIMESTAMPTZ | When patient submitted |
| responses | JSONB | Raw question responses |
| score_result | JSONB | Auto-calculated score, severity, crisis flag |
| status | TEXT | pending_review → reviewed → incorporated |
| reviewed_by | UUID | Clinician who reviewed |
| reviewed_at | TIMESTAMPTZ | When reviewed |
| custom_fields | JSONB | Organization-specific metadata |
cl_between_session_checkins
Append-only check-in records.| Column | Type | Description |
|---|---|---|
| id | UUID | Primary key |
| organization_id | UUID | Tenant isolation |
| chart_id | UUID | Patient chart (composite FK) |
| checkin_at | TIMESTAMPTZ | When patient checked in |
| mood_rating | INTEGER | 1–10 scale (CHECK constraint) |
| medication_adherence | TEXT | Adherence level |
| crisis_flag | BOOLEAN | Patient-reported crisis indicator |
| crisis_warning_signs | TEXT | Free-text warning signs |
| custom_fields | JSONB | Organization-specific metadata |
RLS & Security
- Row Level Security is enabled and forced on both tables.
- Portal patients can only see/insert data for their own charts (via
cl_portal_chart_ids_for_userSECURITY DEFINER helper). - Clinicians access data scoped to their organization via
cl_has_org_access. - UPDATE policies include
WITH CHECKto prevent cross-tenant data movement. - Check-ins are append-only — no UPDATE or DELETE policies exist.
Crisis Escalation Flow
When a submission triggers crisis detection:- Patient sees: Crisis resources banner (988, Crisis Text Line, SAMHSA) immediately after submission.
- In-Basket: An urgent priority in-basket item is created in CL-23 for the care team.
- Clinician action: Clinician reviews the submission and takes appropriate clinical action.
- PHQ-9: Question 9 (suicidal ideation) score ≥ 1
- C-SSRS: Any positive item
- Check-in: Crisis flag toggled by patient
Integration Points
| System | Integration | Direction |
|---|---|---|
| CL-23 In-Basket | In-basket items created on submission | CL-26 → CL-23 |
| PM-12 Portal | Patient identity and chart scoping | PM-12 → CL-26 |
| CL-03 Treatment Plans | Read-only portal view | CL-03 → CL-26 |
| PF-10 Notifications | Crisis escalation alerts | CL-26 → PF-10 |
Troubleshooting
Q: Portal patients can’t see the screening page.A: Ensure the patient has an active
pm_portal_users record with a linked portal_patient_id in pf_profiles. The RLS helper cl_portal_chart_ids_for_user must return chart IDs for the patient.
Q: Submissions aren’t appearing in the clinician list.A: Check that the clinician has
cl.patient-submissions.view permission and belongs to the same organization as the submission.
Q: Crisis in-basket items aren’t being created.A: Verify CL-23 tables exist and the
usePatientSubmissionInbasket hook is invoked after submission creation.