CL-40: Clinical Intake Documentation & SDOH Assessment — Integration Documentation

​

Integration Overview

​

Events Consumed

​

pm_appointment_created (from PM-38)

• Publisher: PM core (PM-38 Appointment Creation)
• Payload: { organization_id, appointment_id, patient_id, provider_id, appointment_date, appointment_type }
• CL-40 Action: Auto-create cl_intake_assessments record with status = 'draft'; pre-populate from CE-28 screening data.

​

ce_screening_completed (from CE-28)

• Publisher: CE core (CE-28 Intake Screening)
• Payload: { organization_id, screening_id, patient_id, chief_complaint, risk_factors, substance_use_flags }
• CL-40 Action: Pre-populate cl_intake_assessments fields (chief complaint, MH history, SUD history, risk flags).

​

Events Published

​

cl_intake_finalized

• Publisher: CL-40
• Subscribers: PM-07/PM-08 (billing), CL-02 (longitudinal assessment)
• Payload: { event_id, organization_id, assessment_id, patient_id, appointment_id, diagnosis_ids[] } (IDs only — no PHI in payload per HIPAA/Part 2)
• Trigger: cl_intake_assessments.status transitions to 'finalized'
• Status: 📝 Planned

​

cl_sdoh_referral_created

• Publisher: CL-40
• Subscribers: CL-18 (social work assignment), notification service
• Payload: { event_id, organization_id, referral_id, patient_id, sdoh_category, referral_status }
• Trigger: Positive SDOH screen detected during intake assessment finalization
• Status: 📝 Planned

​

cl_peer_encounter_documented

• Publisher: CL-40
• Subscribers: PM-07 (billing — CPT 96153/96154)
• Payload: { event_id, organization_id, peer_encounter_id, patient_id, encounter_id, duration_minutes, cpt_code }
• Trigger: Peer encounter signed by supervising clinician
• Status: 📝 Planned

​

API Contracts

​

PF-70 Code Library (Consumed)

• Endpoint: PF-70 type-ahead API for ICD-10 code lookup
• Usage: Diagnosis selection during intake assessment finalization
• Contract: Uses existing PF-70 platform integration layer (@/platform/clinical or @/platform/types)

​

PF-29 E-Signature (Consumed)

• Endpoint: PF-29 e-signature API
• Usage: Clinician signature on intake assessments and clinical notes; peer encounter co-signature
• Contract: Uses existing PF-29 signature workflow

​

Platform Integration Layer Usage

​

Cross-Core Foreign Keys

​

CL→HR peer supporter identity (CL-40 / CL-19)

• Storage: cl_peer_encounters.peer_supporter_id stores the workforce identifier that maps to hr_employees.id in PM/HR; no REFERENCES hr_employees in CL migrations.
• Application: Intake and peer-encounter UIs resolve and assign peers via @/platform/workforce (e.g. EmployeeSelector, useCredentialCheck) so CL code never imports @/cores/hr.
• Database: Implement cl_peer_supporter_valid_for_org(p_organization_id UUID, p_peer_supporter_id UUID) RETURNS BOOLEAN as SECURITY DEFINER SET search_path = public, verifying p_peer_supporter_id exists in hr_employees for p_organization_id (and optional employment/credential predicates). Use in both USING (for UPDATE reads) and WITH CHECK (for INSERT/UPDATE writes) on cl_peer_encounters alongside cl_has_org_access, and anywhere migrations or triggers must assert the peer belongs to the tenant.
• Contract: Documented in PLATFORM_INTEGRATION_LAYERS.md under Platform Workforce Integration (CL-40 peer validation).

​

Data Flow Diagram

CE-28 Screening ──(ce_screening_completed)──▶ CL-40 Intake Assessment (pre-populate)
PM-38 Appointment ──(pm_appointment_created)──▶ CL-40 Intake Assessment (auto-create)

CL-40 Intake (finalized) ──(cl_intake_finalized)──▶ PM-07 Charges (auto-create)
CL-40 SDOH Screen (+) ──(cl_sdoh_referral_created)──▶ CL-18 Social Referrals
CL-40 Peer Encounter (signed) ──(cl_peer_encounter_documented)──▶ PM-07 Charges (CPT)
CL-40 Clinical Note ──(PF-29 API)──▶ E-Signature Workflow

​

Security & Compliance

• All event payloads contain IDs only — no PHI/SUD data per 42 CFR Part 2 and HIPAA.
• SUD fields gated by cl_has_sud_consent(chart_id) SECURITY DEFINER (CL-11 cl_consents schema) + application-layer consent hook from @/platform/clinical / CL-11.
• RLS enforces organization isolation on all CL-40 tables.
• Peer encounter billing requires supervising clinician signature (credential verification).

​

References

• CL-40 Spec
• ADR-002
• CL-11 (consent schema / cl_has_sud_consent alignment)
• CL-HR-PROVIDER-PRODUCTIVITY-INTEGRATION.md (platform workforce pattern for CL↔HR without DB FK)
• CROSS_CORE_INTEGRATIONS.md
• EVENT_CONTRACTS.md