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

# Patient Chart & Clinical Summary — Integration

> Feature ID: CL-01 Status: ✅ Implemented Spec Reference: CL-01-patient-chart-clinical-summary.md Last Updated: 2026-02-17 Last Verified: 2026-02-19

**Feature ID:** CL-01\
**Status:** ✅ Implemented\
**Spec Reference:** [CL-01-patient-chart-clinical-summary.md](../../../specs/cl/specs/CL-01-patient-chart-clinical-summary.md)\
**Last Updated:** 2026-02-17\
**Last Verified:** 2026-02-19

***

## Table of Contents

* [Overview](#overview)
* [Quick Reference](#quick-reference)
* [Decision Tree](#decision-tree)
* [Pattern Library](#pattern-library)
* [Integration Points (from Spec)](#integration-points-from-spec)
* [API / Data Contracts](#api--data-contracts)
* [Labeled Example](#labeled-example)
* [System Boundaries and Data Flow](#system-boundaries-and-data-flow)
* [Event Contracts](#event-contracts)
* [Security and RLS](#security-and-rls)
* [Common Mistakes](#common-mistakes)
* [Pre-Flight Checklist](#pre-flight-checklist)
* [Related Docs](#related-docs)

***

## Overview

CL-01 defines the patient chart shell and clinical summary: unified clinical dashboard, problem list, allergies, timeline, clinical alerts, and break-glass emergency access. It depends on PF (organizations, RBAC, documents, audit, and `pf_patient_identities` for patient identity) and PM-01 (patient demographics via PF identity). **Errata E-1 resolution (adopted):** patient identity is provided by `pf_patient_identities` (PF); `cl_patient_charts.patient_id` references that table. No direct CL→PM FK.

***

## Quick Reference

| Item                | Value                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| Primary tables      | `pf_patient_identities`, `cl_patient_charts`, `cl_problems`, `cl_allergies`                               |
| Access helpers      | `cl_has_org_access`, `cl_has_chart_access`, `cl_fn_is_break_glass_authorized`, `cl_fn_record_break_glass` |
| Integration pattern | PF direct integration + CL internal integration                                                           |
| Event style         | Audit-centric (break-glass logged to `pf_audit_logs`)                                                     |

***

## Decision Tree

1. **User requests chart access**
2. If user has org access (`cl_has_org_access`) → allow normal read/write by role.
3. Else if user has active break-glass (`cl_fn_is_break_glass_authorized`) → allow SELECT-only read path.
4. Else deny.
5. When break-glass is requested, justification is required and `cl_fn_record_break_glass` writes immutable audit metadata.

***

## Pattern Library

| Pattern                    | Usage in CL-01                                                                 |
| -------------------------- | ------------------------------------------------------------------------------ |
| PF identity boundary       | `cl_patient_charts.patient_id` references PF-owned `pf_patient_identities`     |
| Defense-in-depth tenancy   | App code includes `.eq('organization_id', orgId)` in addition to RLS           |
| Break-glass read-only path | Emergency path extends read access only; write paths always require org access |
| Audit-first PHI access     | Break-glass workflow always writes to `pf_audit_logs`                          |

***

## Integration Points (from Spec)

| Dependency                    | Pattern           | Purpose                                               |
| ----------------------------- | ----------------- | ----------------------------------------------------- |
| PF-01 (Organizations & Sites) | Direct            | Multi-tenant isolation, site-level chart assignment   |
| PF-02 (RBAC)                  | Direct            | Clinical role-based access to charts                  |
| PF-11 (Documents)             | Platform / Direct | Clinical document storage and retrieval               |
| PF-04 (Audit Logging)         | Direct            | Break-glass access logging, PHI access tracking       |
| PM-01 (Patient Registration)  | Cross-core        | Patient demographics sourced from PM core             |
| CL-02 through CL-17           | Internal          | All CL specs render within chart navigation framework |

***

## API / Data Contracts

* **Chart data:** `cl_patient_charts`, `cl_problems`, `cl_allergies`; all scoped by `organization_id`; RLS via SECURITY DEFINER helpers.
* **Break-glass:** Justification required; time-limited; audit row created via `cl_fn_record_break_glass` (PF-04); privacy officer notification.
* **Patient identity:** `pf_patient_identities` (PF) is the source of truth; `cl_patient_charts.patient_id` references it.

***

## Labeled Example

### Example: Break-Glass RPC payload

```json theme={null}
{
  "organization_id": "org-uuid",
  "chart_id": "chart-uuid",
  "patient_id": "patient-uuid",
  "reason": "Emergency access for urgent stabilization"
}
```

***

## System Boundaries and Data Flow

* **PF owns:** tenant membership + patient identity (`pf_patient_identities`).
* **CL owns:** chart shell + clinical summary records (`cl_patient_charts`, `cl_problems`, `cl_allergies`).
* **PM consumes shared identity:** via PF and integration contracts, not direct CL DB dependency.

Read flow:

1. UI requests chart by ID.
2. Query includes tenant filter (`organization_id`).
3. RLS checks `cl_has_chart_access`.
4. Only non-deleted rows are returned.

Break-glass flow:

1. User submits reason.
2. `cl_fn_record_break_glass` validates org and chart/org match.
3. Audit row written.
4. Time-limited read access is granted.

***

## Event Contracts

* No CL-01-specific domain events are currently defined. Break-glass events are audit records (PF-04), not event-bus messages. Document future events in [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md).

***

## Security and RLS

* RLS on `cl_patient_charts`, `cl_problems`, `cl_allergies`; USING and WITH CHECK policies rely on SECURITY DEFINER helpers.
* UPDATE policies include WITH CHECK.
* 42 CFR Part 2 SUD records require additional consent-based access checks (CL-11).
* PHI access is audit-logged with minimum retention requirements.

***

## Common Mistakes

| Mistake                                | Impact                      | Fix                                      |
| -------------------------------------- | --------------------------- | ---------------------------------------- |
| Query without `organization_id` filter | Cross-tenant data risk      | Always include explicit tenant filtering |
| Using break-glass for writes           | Policy/compliance violation | Keep break-glass SELECT-only             |
| Treating CL as PM identity owner       | Boundary violation          | Use PF-owned `pf_patient_identities`     |

***

## Pre-Flight Checklist

* [ ] Confirm CL-01 tables have RLS + FORCE RLS enabled.
* [ ] Confirm UPDATE policies include WITH CHECK.
* [ ] Confirm break-glass RPC enforces org and chart consistency checks.
* [ ] Confirm all user-facing errors are sanitized.
* [ ] Confirm query keys/invalidation include tenant context.

***

## Related Docs

* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)
* [CL-PM-ENCOUNTER-TO-BILLING.md](./CL-PM-ENCOUNTER-TO-BILLING.md)
* [API\_CONTRACTS.md](./API_CONTRACTS.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)