Patient Chart & Clinical Summary — Integration

​

Table of Contents

• Overview
• Quick Reference
• Decision Tree
• Pattern Library
• Integration Points (from Spec)
• API / Data Contracts
• Labeled Example
• System Boundaries and Data Flow
• Event Contracts
• Security and RLS
• Common Mistakes
• Pre-Flight Checklist
• Related Docs

​

Overview

​

Quick Reference

​

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

​

Integration Points (from Spec)

​

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.

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.

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

​

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
• CL-PM-ENCOUNTER-TO-BILLING.md
• API_CONTRACTS.md
• EVENT_CONTRACTS.md