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.

Status: Accepted
Date: 2026-02-25
Decision Makers: Platform Architecture Team

​
Context

CL (Clinical) tables such as cl_progress_notes, cl_group_sessions, and cl_peer_encounters reference the encounter entity via an encounter_id (or equivalent) column pointing to pm_encounters.id. The encounter is owned by PM and is the canonical entity linking scheduling, clinical documentation, and billing. Current practice uses UUID columns with no database foreign key constraint; validation is done at the application layer. This creates data integrity risk: if an encounter is deleted (or the reference is mistyped), clinical records can be left with orphaned or invalid references. There is no database-level guarantee that encounter_id points to an existing row in pm_encounters.

​
Decision

Allow a scoped exception: CL tables MAY add a database foreign key from their encounter reference column to pm_encounters.id with ON DELETE RESTRICT.
  • Scope: Only the encounter entity. Only CL tables that reference pm_encounters may use this FK. No other cross-core foreign key is permitted without a separate ADR.
  • Constraint: ON DELETE RESTRICT so that an encounter with linked clinical documentation cannot be deleted until those links are removed or the documentation is reassigned.
  • Indexes: The FK column MUST be indexed (per constitution §5.2).
  • RLS: Tenant isolation remains enforced by RLS on both CL and PM tables; the FK does not bypass RLS.

​
Rationale

  1. Encounter is the fundamental joint between clinical documentation and revenue cycle. Every major EHR/PM system treats this as a tight coupling point; allowing a single, well-defined FK reflects that reality without relaxing the broader no-cross-core-import rule.
  2. Referential integrity prevents orphaned clinical notes and avoids silent data corruption. Application-layer checks can be missed; a database constraint cannot.
  3. RESTRICT over CASCADE ensures we never automatically delete or null out clinical documentation when an encounter is removed. Deletion of encounters with documentation must be an explicit, controlled workflow.
  4. Narrow scope keeps the exception from becoming a precedent for other cross-core FKs. Other cross-core references (e.g., referrals, schedules) remain UUID-only unless a future ADR approves them.

​
Consequences

​
Positive

  • Referential integrity between CL documentation and PM encounters
  • Impossible to delete an encounter that still has linked progress notes, group sessions, or peer encounters without explicit handling
  • Clear, single exception documented for implementers and reviewers

​
Negative

  • Deployment ordering: PM migrations that define or alter pm_encounters must run before CL migrations that add the FK
  • Cross-core dependency at the database level (mitigated by keeping it to one entity and one direction: CL → PM)

​
Mitigations

  • Document migration order in PM/CL deployment runbooks
  • Constitution §5.2.7 and this ADR make the rule and its scope explicit
  • No other cross-core FK is permitted without a new ADR