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.

​
ADR-005: Cross-Core Foreign Keys to pm_patients

Status: Accepted
Date: 2026-04-10
Decision Makers: Platform Architecture Team

​
Context

Several cores reference the PM patient record (pm_patients.id) for demographics, portal linkage, and clinical–PM alignment. Constitution §5.2.7 defaults to UUID-only cross-core references unless an ADR authorizes a database FK. Existing patterns include:
  • CL — e.g. cl_intake_assessments, cl_diagnoses, cl_peer_encounters (patient linkage).
  • CE — e.g. ce_lead_conversions → pm_patients.
  • PF — e.g. pf_profiles.portal_patient_id → pm_patients.
These differ from ADR-002 (CL → pm_encounters only).

​
Decision

  1. Database FKs to pm_patients.id are permitted where a spec explicitly requires tight referential integrity for the patient master record, with ON DELETE RESTRICT so PM cannot delete a patient row that is still referenced by downstream clinical or engagement data without an explicit remediation path. (NO ACTION is acceptable only where it provides identical semantics—i.e., the FK constraint prevents deletion when references exist—but RESTRICT is preferred for clarity.)
  2. New references should prefer UUID columns + application validation unless a spec documents the need for an FK; when an FK is added, it must be listed in migration notes and this ADR.
  3. Tenant isolation remains enforced by RLS on all participating tables; the FK does not bypass RLS.

​
Rationale

  • The patient identity is a shared anchor across CL, PM, CE, and portal (PF) surfaces; orphan UUIDs create higher operational risk than for generic cross-core links.
  • RESTRICT preserves auditability and prevents silent cascades inconsistent with HIPAA-aligned chart retention.

​
Consequences

​
Positive

  • Stronger integrity for patient-scoped data shared across cores.
  • Clear precedent distinct from encounter-only ADR-002.

​
Negative

  • Deployment ordering: PM patient migrations must be coherent before dependent FKs.
  • Additional review burden for any new pm_patients FK.