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-23
Status: 📋 Spec approved; implementation pending
Spec Reference: CL-23-clinical-in-basket-provider-messaging.md
Last Updated: 2026-02-24

​
Overview

CL-23 provides a unified clinical in-basket for provider action items (co-sign, lab review, refill, chart message, referral response, CDS alert). It consumes events from CL and PM/PF and integrates with PF-10 notifications and PM-14 secure messaging.

​
Integration Points (from Spec)

DependencyPatternPurpose
PF-01 (Organizations & Sites)DirectMulti-tenant isolation
PF-02 (RBAC)DirectPermission checks
PF-10 (Notifications)Platform / EventNotification fan-out and urgency channels
PF-29 (Tasks)PlatformOptional task linkage for deferred items
CL-01 (Patient Chart)InternalChart context for items
CL-04 (Progress Notes)InternalCo-sign and documentation follow-up tasks
CL-08 (CDS)InternalCDS action-required alerts
CL-09 (Labs/Results)InternalLab/result review queue entries
CL-11 (Consent)InternalPart 2-sensitive item access consent checks
PM-14 (Secure Messaging)Platform / APISecure message deep-linking into clinical workflow

​
Quick Reference

  • Purpose: Unified in-basket for provider action items (co-sign, lab review, refill, chart message, referral response, CDS alert).
  • Audience: Implementers integrating CL-23 with CL/PM/PF events and PF-10/PM-14.
  • Inputs: Events from CL (progress_note_signed, cds_alert_triggered, cl_lab_result_*), PM (referral_response, chart_message when defined).
  • Outputs: PF-10 notifications; PM-14 deep-links; cl_inbasket_items and cl_inbasket_item_activity records.
  • SLAs: Per spec NFRs; event-to-item creation latency TBD in implementation.

​
Decision Tree

  1. Event received → Route by event type (cosign_request, lab_review, refill_request, chart_message, referral_response, cds_alert).
  2. Co-sign: progress_note_signed → create/update item type cosign_request; optional PF-10 notify.
  3. Lab review: cl_lab_result_received / cl_lab_result_reviewed → lab_review item; abnormal results may trigger CDS.
  4. Refill: Refill request event (when defined) → refill_request item.
  5. Chart message: chart_message event (when defined) → chart_message item; link to PM-14 thread.
  6. Referral response: referral_response event (when defined) → referral_response item.
  7. CDS alert: cds_alert_triggered → cds_alert item; PF-10 for urgency.
  8. Item completed → PF-10 notification; optional PM-14 reply.

​
Pattern Library

  • Consuming CL/PM events: Subscribe to channel per EVENT_CONTRACTS.md; map event payload to cl_inbasket_items (item_type, payload, assigned_to, due_at); insert activity log row.
  • Producing PF-10 output: On item create/update/complete, call PF-10 notification API with actor, urgency, deep-link.
  • Producing PM-14 output: When item references a secure message, use PM-14 deep-link (route + thread id); do not duplicate message content in in-basket payload.
  • RLS: All access via SECURITY DEFINER helper; WITH CHECK on UPDATE; no direct query to RLS-protected tables in policies.

​
Common Mistakes

MistakeMitigation
Direct core-to-core import (e.g. CL → PM)Use platform integration layer or events only
Missing WITH CHECK on in-basket UPDATEAdd WITH CHECK (e.g. org access) per constitution §5.2.4
Querying RLS-protected tables inside policyUse SECURITY DEFINER helper only
Forgetting to seed permission keysMigration must insert cl.inbasket.* into pf_module_permissions / pf_role_permissions
Emitting PHI in event payloadsPayloads: IDs only; resolve display via authorized APIs

​
Pre-Flight Checklist

  • Migration: tables, indexes, updated_at trigger, RLS with FORCE RLS applied.
  • Permission keys seeded; roles assigned.
  • Event consumers (or stubs) mapped per EVENT_CONTRACTS.md; referral_response and chart_message stubs acknowledged.
  • PF-10 and PM-14 integration points verified (or stubbed).
  • RLS tests pass; cross-tenant isolation verified.
  • Observability: audit trail for item create/update/complete where required.

​
API / Data Contracts

  • In-basket items: cl_inbasket_items — item type, priority, classification, status, assigned_to, due_at, payload; event-driven creation from CL/PM/PF.
  • Activity log: cl_inbasket_item_activity — created, read, assigned, status_changed, escalated, completed, commented; append-only audit trail.
(Add request/response or event schemas here when APIs or events are defined.)

​
Event Contracts

  • Consumed (planned): Event names and payload schemas are in EVENT_CONTRACTS.md – Planned Events (CL/PM). CL-23 maps: progress_note_signed → cosign_request; cds_alert_triggered → cds_alert; cl_lab_result_received / cl_lab_result_reviewed → lab_review. Referral and chart_message events to be added when PM/CL specs define them. Each creates or updates cl_inbasket_items with item_type and payload.
  • Published (planned): Item created/updated → PF-10 notification; deep-link to PM-14 message when item references a secure message.

​
Security and RLS

  • RLS on cl_inbasket_items and cl_inbasket_item_activity via SECURITY DEFINER helpers (constitution §5.7); no direct queries to RLS-protected tables in policies.
  • UPDATE policies on cl_inbasket_items MUST include WITH CHECK (constitution §5.2.4).
  • Permission keys: cl.inbasket.view, cl.inbasket.manage, cl.inbasket.escalate, cl.inbasket.assign; seed in migration.
  • Part 2-sensitive item access must honor CL-11 consent checks where applicable.