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.

​
Clinical Intake Documentation & SDOH Assessment — Integration Documentation

Spec: CL-40 Created: 2026-03-29 Status: 📝 Planned

​
Integration Overview

CL-40 is a cross-core orchestration feature that consumes upstream intake/screening events and produces downstream clinical/billing events. It bridges CE (screening), PM (appointments/billing), CL (clinical documentation), and PF (signatures, code library).

​
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

LayerImportUsage
@/platform/clinicalPatient context, consent checkingusePatientSudConsent() for Part 2 gating
@/platform/schedulingEncounter/appointment contextPre-populate from appointment data
@/platform/typesEncounterContext, DiagnosisReferenceShared types for CL/PM data exchange
@/platform/formsForm renderingIntake assessment multi-section form

​
Cross-Core Foreign Keys

FK ColumnSource TableTarget TableJustification
appointment_idcl_intake_assessmentspm_appointmentsPer ADR-002 (CL→PM FK allowed)
patient_idcl_intake_assessments, cl_peer_encounterspm_patientsPer ADR-002
encounter_idcl_peer_encounterspm_encountersPer ADR-002
peer_supporter_idcl_peer_encounters(none — logical hr_employees.id)Decision (B): No CL→HR database FK. Default cross-core pattern (UUID + validation) applies; ADR-002 does not extend to HR. Credential/billing checks use the platform layer and SQL helper below (same spirit as CL-HR-PROVIDER-PRODUCTIVITY-INTEGRATION.md: read-only / validated access without a core-to-core FK). Option (A) — add a direct FK — would require a new ADR that explicitly exceptions ADR-002 and documents billing/credential justification.

​
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