Integration Contract

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.

​

Purpose

​

Integration Points

1. Internal CL-12 referral workflow
   • Source of truth for referral entity lifecycle.
   • Supports inbound status updates and closeout tracking fields/history.
2. CL-18 relationship (boundary only)
   • Shares conceptual status/closeout pattern where useful.
   • No duplication of SDOH domain ownership.
3. External directory lookup
   • Optional FindTreatment.gov (or Arizona directory) read-only lookup.
   • Backend-only API calls via adapter/edge function.
   • Secret reference resolved from Supabase Vault at runtime.

​

Security and Tenancy

• All mutation paths must enforce organization_id isolation.
• RLS policies required for new referral status history structures.
• FindTreatment.gov requires pre-approval (access request form) but no runtime API key. Adapter pattern supports future credential-based directories via Supabase Vault. No API keys in client code, logs, or front-end bundles.
• No PHI in integration logs; use identifiers only as required for operational tracing.

​

Data Model

• cl_referral_status_history — Append-only table; columns: id, organization_id, referral_id (bare UUID → pm_referrals.id), status (enum: sent, accepted, declined, patient_connected, patient_did_not_connect, closed), patient_connected, patient_connected_at, external_status_source, notes, custom_fields JSONB, created_at, created_by.
• cl_referral_current_status — View (security_invoker = true): latest status per referral via DISTINCT ON (referral_id).

​

API/Event Contract Notes

​

Inbound referral status update contract

• Fields: referral_id (UUID, required), status (enum, required), patient_connected (boolean, optional), patient_connected_at (timestamptz, optional), external_status_source (enum: partner_api | manual | file_import, optional), notes (text, optional).
• Validation: Allowed status enum values; tenant ownership check (referral_id exists in cl_transitions for caller’s organization_id); append-only (no UPDATE).

​

Directory lookup contract (edge function: cl-referral-directory-search)

• Upstream API: FindTreatment.gov v1.10 — GET /locator/exportsAsJson/v2?{querystring}.
• Request (internal): { sType?: 'sa' | 'mh', limitType: 0 | 1 | 2, limitValue: string, lat?: number, lng?: number, page?: number, pageSize?: number }.
• Response (normalized): { results: [{ name, address, phone, services: string[], accepting_new_patients: boolean }], total: number, page: number }.
• Auth: FindTreatment.gov requires pre-approval via SAMHSA access request form; no runtime API key. Adapter pattern supports future credential-based directories (Vault-stored). CORS via getCorsHeaders(req.headers.get('origin')).

​

Events Published

​

Permission Keys

​

Testing Expectations

• Unit: Status enum validation, closeout derivation, directory response normalization, referral_id ownership check. Files: tests/unit/cl/referral-status-history.test.ts, tests/unit/cl/referral-directory-search.test.ts.
• RLS: Tenant isolation on cl_referral_status_history; INSERT org-scoped; UPDATE blocked; DELETE org_admin only. File: tests/rls/cl-referral_status_history.rls.test.ts.
• Integration: Chart display of status history; directory search edge function (mocked). File: tests/integration/cl/cl-referral-status-history.test.ts.
• E2E: Create referral → status update → closeout → outcome report → CSV export. File: tests/e2e/cl/referral-closed-loop.spec.ts.