Progress Notes & Session Documentation — Integration

​

Table of Contents

• Overview
• Quick Reference
• Decision Trees
• Pattern Library
• Integration Points (from Spec)
• API / Data Contracts
• Code Examples
• Event Contracts
• Security and RLS
• Common Mistakes
• Pre-Flight Checklist
• Related Docs

​

Overview

​

Quick Reference

​

Decision Trees

​

Note finalization flow

1. Draft note is authored in chart context.
2. Clinician signs (or supervisor co-signs) note.
3. If final status is signed/cosigned, publish clinical_note_finalized.
4. PM-07 consumes event for charge capture workflow.

​

Co-signature flow

1. Determine whether author role requires supervisory co-sign (HR-19).
2. If required, enforce co-sign due window and PF-10 alerts.
3. Block billing event publication until required co-sign state is satisfied.

​

Pattern Library

​

Integration Points (from Spec)

​

API / Data Contracts

• Progress notes: Tables cl_progress_notes, cl_note_treatment_goals, cl_note_templates; all scoped by organization_id; RLS via SECURITY DEFINER helpers (e.g. cl_fn_check_org_membership). No direct FK to pm_encounters; encounter_id validated at application layer (core independence).
• Event: clinical_note_finalized — published when note status transitions to signed or cosigned; payload must include organization_id, clinical_note_id, encounter_id, patient_id, finalized_at. See CL-PM-ENCOUNTER-TO-BILLING.md.

​

Code Examples

​

Example: clinical_note_finalized payload

{
  "event_type": "clinical_note_finalized",
  "organization_id": "org-uuid",
  "clinical_note_id": "note-uuid",
  "encounter_id": "encounter-uuid",
  "patient_id": "patient-uuid",
  "status": "signed",
  "finalized_at": "2026-02-17T18:30:00Z",
  "actor_id": "clinician-uuid"
}

​

Example: org access guard pattern

USING (cl_fn_check_org_membership(organization_id, auth.uid()))

​

Event Contracts

• clinical_note_finalized: CL publishes when a progress note is signed or cosigned; PM-07 (charge capture) subscribes. Payload schema and subscription details in CL-PM-ENCOUNTER-TO-BILLING.md.

​

Security and RLS

• RLS on cl_progress_notes, cl_note_treatment_goals, cl_note_templates; USING and WITH CHECK use SECURITY DEFINER helpers; no direct queries to RLS-protected tables (constitution §5.7).
• UPDATE policies include WITH CHECK for organization_id (constitution §5.2.4).
• Part 2 SUD: restrict via consent check (e.g. cl_has_sud_consent() SECURITY DEFINER) per CL-11; access logged per HIPAA.

​

Common Mistakes

​

Pre-Flight Checklist

• RLS + FORCE RLS enabled on all CL-04 tables.
• clinical_note_finalized payload contract documented and validated.
• Co-signature requirements mapped to HR-19 role rules.
• Error messages sanitized for all UI-facing failures.
• Integration tests cover note finalization → PM-07 handoff.

​

Related Docs

• CROSS_CORE_INTEGRATIONS.md
• CL-PM-ENCOUNTER-TO-BILLING.md
• CL-PM-TELEHEALTH.md
• CL-03-treatment-planning-INTEGRATION.md (if present)
• PLATFORM_INTEGRATION_LAYERS.md