> ## 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

# 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.

## Related Documents

* [ADR-002: CL-PM Cross-Core Foreign Keys](./ADR-002-cl-pm-cross-core-foreign-keys.md) — encounter entity only
* [Constitution §5.2.7](../../../constitution.md) — Cross-core database references
* [PLATFORM\_INTEGRATION\_LAYERS.md](../integrations/PLATFORM_INTEGRATION_LAYERS.md)