Comprehensive Assessments — Integration

​

Table of Contents

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

​

Overview

​

Quick Reference

​

Decision Tree

• Assessment flow: Initiate per CL-02 spec → 18-element template (AHCCCS AMPM 320-O) → age-specific instruments (CALOCUS, ASAM, developmental, SU) as applicable → complete sections → 48-hour documentation window → electronic signatures (PF-33) → annual expiration tracking; findings may drive CL-03 goals; risk screening links to CL-07.
• Data source: CL-01 chart embedding; PF-08 form rendering; PF-02 RBAC for view/create/sign/cosign/manage.

​

Pattern Library

​

Common Mistakes

​

Pre-Flight Checklist

• Data: cl_assessments, cl_assessment_sections, cl_assessment_instruments created with RLS; deleted_at, site_id per Errata.
• RBAC: Permission keys seeded (cl.assessment.view, create, sign, cosign, manage); RLS uses existing CL-01 helpers (cl_has_org_access, cl_has_chart_access, pf_is_org_admin). Role checks enforced at application layer via useHasPermission.
• Digital signatures: PF-33 integration for clinician and patient/HCDM; signed rows immutable.
• Notifications: PF-10 assessment_expiring event payload includes organization_id, timestamp, event_type; scheduler (pg_cron or dashboard) documented for 30-day-before expiry.
• Annual expiration tracking: Dashboard/list filter on expires_at; event published per EVENT_CONTRACTS.

​

Integration Points (from Spec)

​

API / Data Contracts

• Assessment data: cl_assessments, cl_assessment_sections, cl_assessment_instruments; all scoped by organization_id; RLS via existing CL-01 SECURITY DEFINER helpers: cl_has_chart_access (SELECT), cl_has_org_access (INSERT/UPDATE), pf_is_org_admin (DELETE). Role-based access enforced at application layer via useHasPermission.
• PF-08: Request { formId, patientId, locale? }; response { html?, schema }. CL owns 18-element structure and section content; PF-08 used for form rendering/validation only.
• PF-33: Request { signerId, documentId, payloadHash }; response { signedAt, signatureBlob }. Used for clinician and patient/HCDM signature capture.
• Amendment/version: New assessment row with supersedes_id FK; status amended/superseded; signed rows immutable.

​

Event Contracts

• PF-10 (assessment_expiring): Published when assessment is expiring (e.g. 30 days before due). Consumer: notification to assigned clinician. Example:
  {
    "event_type": "assessment_expiring",
    "organization_id": "org-uuid",
    "timestamp": "2026-02-19T00:00:00Z",
    "assessment_id": "assessment-uuid",
    "due_date": "2026-03-20T00:00:00Z",
    "clinician_id": "user-uuid"
  }
  
• CL-03 (findings): Assessment findings event for treatment plan linkage. Example:
  {
    "event_type": "assessment_findings_available",
    "organization_id": "org-uuid",
    "timestamp": "2026-02-19T14:00:00Z",
    "assessment_id": "assessment-uuid",
    "chart_id": "chart-uuid",
    "findings": [{ "code": "F32.1", "severity": "moderate", "linked_goal_ids": [] }]
  }
  
• CL-07 (risk): Suicide risk screening event when linked to assessment. Example:
  {
    "event_type": "risk_screening_linked",
    "organization_id": "org-uuid",
    "timestamp": "2026-02-19T15:00:00Z",
    "assessment_id": "assessment-uuid",
    "screening_id": "screening-uuid",
    "risk_level": "high",
    "recommended_actions": ["safety_plan_review", "supervisor_notification"]
  }
  

​

Labeled Example

​

Example: CL-02 Assessment JSON

{
  "assessment_id": "assessment-uuid",
  "organization_id": "org-uuid",
  "assessment_type": "comprehensive",
  "status": "completed",
  "expires_at": "2027-02-17T00:00:00Z",
  "signed_at": "2026-02-17T14:00:00Z"
}

​

AI-Optimized Notes

• Always treat signed/amended/superseded assessments as immutable.
• expires_at drives all expiration dashboards and notifications.
• Use organization_id in payloads, query keys, and mutation filters.
• For expiresInDays, 0 is valid and must not be treated as falsy.

​

Security and RLS

• RLS on cl_assessments, cl_assessment_sections, cl_assessment_instruments; ENABLE + FORCE ROW LEVEL SECURITY. Per-operation policies use existing CL-01 helpers: cl_has_chart_access (SELECT), cl_has_org_access (INSERT/UPDATE with WITH CHECK), pf_is_org_admin (DELETE). Signed assessment immutability enforced via BEFORE UPDATE trigger.
• UPDATE policies include WITH CHECK; signed assessments not updatable except via amendment path (new row with supersedes_id).
• Part 2 SUD assessment sections require explicit tagging (section_code or instrument metadata) and consent checks (CL-11).
• PHI; full HIPAA audit logging; 6-year retention per errata (deleted_at soft-delete).

​

Related Docs

• CROSS_CORE_INTEGRATIONS.md
• CL-01-patient-chart-clinical-summary-INTEGRATION.md
• API_CONTRACTS.md
• EVENT_CONTRACTS.md