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-01
Status: ✅ Implemented
Spec Reference: CL-01-patient-chart-clinical-summary.md
Last Updated: 2026-02-17
Last Verified: 2026-02-19

​
Table of Contents

​
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

ItemValue
Primary tablespf_patient_identities, cl_patient_charts, cl_problems, cl_allergies
Access helperscl_has_org_access, cl_has_chart_access, cl_fn_is_break_glass_authorized, cl_fn_record_break_glass
Integration patternPF direct integration + CL internal integration
Event styleAudit-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

PatternUsage in CL-01
PF identity boundarycl_patient_charts.patient_id references PF-owned pf_patient_identities
Defense-in-depth tenancyApp code includes .eq('organization_id', orgId) in addition to RLS
Break-glass read-only pathEmergency path extends read access only; write paths always require org access
Audit-first PHI accessBreak-glass workflow always writes to pf_audit_logs

​
Integration Points (from Spec)

DependencyPatternPurpose
PF-01 (Organizations & Sites)DirectMulti-tenant isolation, site-level chart assignment
PF-02 (RBAC)DirectClinical role-based access to charts
PF-11 (Documents)Platform / DirectClinical document storage and retrieval
PF-04 (Audit Logging)DirectBreak-glass access logging, PHI access tracking
PM-01 (Patient Registration)Cross-corePatient demographics sourced from PM core
CL-02 through CL-17InternalAll 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

{
  "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.

​
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

MistakeImpactFix
Query without organization_id filterCross-tenant data riskAlways include explicit tenant filtering
Using break-glass for writesPolicy/compliance violationKeep break-glass SELECT-only
Treating CL as PM identity ownerBoundary violationUse 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.