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

# Clinical In-Basket / Provider Messaging — Integration

> Feature ID: CL-23 Status: 📋 Spec approved; implementation pending Spec Reference: CL-23-clinical-in-basket-provider-messaging.md Last Updated: 2026-02-24

**Feature ID:** CL-23\
**Status:** 📋 Spec approved; implementation pending\
**Spec Reference:** [CL-23-clinical-in-basket-provider-messaging.md](../../../specs/cl/specs/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)

| Dependency                    | Pattern          | Purpose                                            |
| ----------------------------- | ---------------- | -------------------------------------------------- |
| PF-01 (Organizations & Sites) | Direct           | Multi-tenant isolation                             |
| PF-02 (RBAC)                  | Direct           | Permission checks                                  |
| PF-10 (Notifications)         | Platform / Event | Notification fan-out and urgency channels          |
| PF-29 (Tasks)                 | Platform         | Optional task linkage for deferred items           |
| CL-01 (Patient Chart)         | Internal         | Chart context for items                            |
| CL-04 (Progress Notes)        | Internal         | Co-sign and documentation follow-up tasks          |
| CL-08 (CDS)                   | Internal         | CDS action-required alerts                         |
| CL-09 (Labs/Results)          | Internal         | Lab/result review queue entries                    |
| CL-11 (Consent)               | Internal         | Part 2-sensitive item access consent checks        |
| PM-14 (Secure Messaging)      | Platform / API   | Secure 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

| Mistake                                     | Mitigation                                                                                |
| ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Direct core-to-core import (e.g. CL → PM)   | Use platform integration layer or events only                                             |
| Missing WITH CHECK on in-basket UPDATE      | Add WITH CHECK (e.g. org access) per constitution §5.2.4                                  |
| Querying RLS-protected tables inside policy | Use SECURITY DEFINER helper only                                                          |
| Forgetting to seed permission keys          | Migration must insert cl.inbasket.\* into pf\_module\_permissions / pf\_role\_permissions |
| Emitting PHI in event payloads              | Payloads: 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)](./EVENT_CONTRACTS.md#planned-events-clpm-ehr--practice-management). 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.

***

## Related Docs

* [Spec](../../../specs/cl/specs/CL-23-clinical-in-basket-provider-messaging.md)
* [PM-14 Secure Messaging](secure-messaging-integration.md)
* [CL-04 Progress Notes](progress-notes-session-documentation-integration.md)
* [CL-08 Clinical Decision Support](../../../specs/cl/specs/CL-08-clinical-decision-support.md)
* [CROSS\_CORE\_INTEGRATIONS.md](CROSS_CORE_INTEGRATIONS.md)