Suicide Risk Screening & Safety Planning — Integration

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.

​

Overview

​

Quick Reference

​

Integration Points (from Spec)

​

Event / Notification Contracts

​

cl_risk_screening_high_risk (Errata E-5)

{
  organization_id: string;   // required — tenant isolation
  chart_id: string;          // required — patient chart reference (no PHI)
  screening_id: string;      // required — cl_risk_screenings.id
  risk_level: 'high' | 'imminent';
  screened_at: string;       // ISO 8601 timestamp
  next_screening_due: string; // ISO 8601 — always set on save (not optional; see below)
}
// ⚠ next_screening_due is ALWAYS set when screening is saved — never optional in actual
// insert. Integration doc previously listed it as optional; corrected here (Errata E-5).

// Insert into pf_notifications after screening save
await supabase.from('pf_notifications').insert({
  organization_id: orgId,
  user_id: careTeamMemberId,     // repeat for each care team member
  type: 'alert',                  // pf_notifications.type enum value
  channel: 'in_app',             // primary; add 'email' row for email channel if needed
  title: `${riskLevel.toUpperCase()} Suicide Risk Alert`,
  message: `Patient chart ${chartId} screened at ${riskLevel} risk. Next screening due ${nextScreeningDue}.`,
  priority: 'high',
  metadata: { chart_id: chartId, screening_id: screeningId, risk_level: riskLevel },
});

​

cl_safety_plan_signed (Errata E-5)

{
  organization_id: string;
  chart_id: string;
  safety_plan_id: string;    // cl_safety_plans.id
  signer_type: 'patient' | 'clinician';
  signed_at: string;         // ISO 8601
}

​

PF-33 / SignatureCanvas — Pattern Decision & Implementation (Errata E-6)

​

Decision

​

Rationale

​

Pattern B Upgrade Path (v2)

1. Add patient_signature_request_id UUID REFERENCES pf_signature_requests(id) and clinician_signature_request_id UUID REFERENCES pf_signature_requests(id) to cl_safety_plans.
2. Retain patient_signature_data / clinician_signature_data JSONB columns for backward compatibility with v1 records.
3. On completion, pf_signature_requests.signature_id links to the pf_signatures row; read back to display signed state.

​

Pattern A Implementation

1. Render <SignatureCanvas> from @/platform/signatures within the safety plan form.
2. On completion, capture base64 image output (dataUrl).
3. Update cl_safety_plans row via useSignSafetyPlan:
   • Patient: patient_signature_data = { image: dataUrl, captured_at: ISO8601 }, patient_signed_at = now()
   • Clinician: clinician_signature_data = { image: dataUrl, captured_at: ISO8601 }, clinician_signed_at = now()
4. Publish cl_safety_plan_signed domain event (payload: IDs only — no image data).

​

Storage Schema (on cl_safety_plans)

​

CL-01 Risk Flag (Errata E-7)

ALTER TABLE cl_patient_charts
  ADD COLUMN IF NOT EXISTS current_risk_level TEXT
    CHECK (current_risk_level IN ('low', 'moderate', 'high', 'imminent')),
  ADD COLUMN IF NOT EXISTS risk_last_screened_at TIMESTAMPTZ;

UPDATE cl_patient_charts
SET current_risk_level = NEW.risk_level,
    risk_last_screened_at = NEW.screened_at
WHERE id = NEW.chart_id;

​

CL-13 Bidirectional Relationship

• CL-07 → CL-13: Risk screenings may trigger crisis intervention documentation (CL-13). Crisis episodes reference the triggering screening.
• CL-13 → CL-07: cl_crisis_episodes.safety_plan_updated BOOLEAN references the existence of a CL-07 safety plan record for the same chart (soft relationship, no FK). CL-13’s scope explicitly includes “Safety plan creation/update during crisis (CL-07).”

​

Security and RLS

• Tables: cl_risk_screenings, cl_safety_plans, cl_environmental_assessments (per Errata E-1).
• RLS: All three tables use cl_has_org_access(organization_id, auth.uid()) (two-argument form, Errata E-4) for SELECT/INSERT/UPDATE/DELETE. WITH CHECK required on UPDATE. No direct queries to RLS-protected tables in policies.
• Permissions: cl.risk_screening.view/create, cl.safety_plan.view/create/sign (sign = approve category), cl.environmental_assessment.view/create. Enforce at application layer via useHasPermission.
• PHI: Signature image data (*_signature_data) is PHI — never log or expose in event payloads. Event payloads contain IDs only.

​

Common Mistakes

​

Related Docs

• CL-01 Patient Chart & Clinical Summary — Risk flag columns on chart
• CL-02 Comprehensive Assessments — CL-02 references CL-07 for risk workflows
• CL-13 Crisis Intervention spec — Bidirectional coupling with CL-07 (no separate integration stub; see spec and CL-07 errata)
• CROSS_CORE_INTEGRATIONS.md — Matrix entry for CL-07