Patient Registration & Demographics — Integration

​

Table of Contents

• Overview
• Quick Reference
• Decision Trees
• Pattern Library
• Integration Points (from Spec)
• API / Data Contracts
• Labeled Code Examples
• Event Contracts
• Security and RLS
• Common Mistakes
• Pre-Flight Checklist
• Related Docs

​

Overview

​

Quick Reference

​

Decision Trees

​

Create vs merge flow

1. Search for existing patient candidates (MPI checks).
2. If high-confidence duplicate exists, route to merge workflow.
3. Else create new patient registration record and emit patient_registered.

​

Identity boundary flow

1. Capture PM demographics in PM-owned tables.
2. Resolve shared patient identity through PF integration boundary.
3. CL consumers use PF identity link, not PM-owned FK coupling.

​

Pattern Library

​

Integration Points (from Spec)

​

API / Data Contracts

• Patient demographics: Tables pm_patients, pm_patient_addresses, pm_emergency_contacts, pm_guarantors; all scoped by organization_id; RLS via SECURITY DEFINER helpers (pm_can_access_patient, pm_can_modify_patient).
• Patient identity: Per CL-01 integration, patient identity may be resolved via pf_patient_identities (PF); PM-01 is the source of demographic data. See API_CONTRACTS.md for GET /api/v1/pm/patients/:id (or platform equivalent).
• Permissions: pm.patients.view, pm.patients.create, pm.patients.update, pm.patients.merge (PF-30).

​

Labeled Code Examples

​

Example: patient registration API shape

{
  "organization_id": "org-uuid",
  "first_name": "Alex",
  "last_name": "Rivera",
  "date_of_birth": "1990-07-10",
  "mrn": "MRN-12345"
}

​

Example: patient_registered event payload

{
  "event_type": "patient_registered",
  "organization_id": "org-uuid",
  "entity_id": "patient-uuid",
  "timestamp": "2026-02-17T19:00:00Z",
  "actor_id": "staff-uuid"
}

​

Event Contracts

• patient_registered: PM publishes when a new patient is registered; subscribers CL, RH (optional), PF-10. See EVENT_CONTRACTS.md for payload and timeline.

​

Security and RLS

• RLS on pm_patients, pm_patient_addresses, pm_emergency_contacts, pm_guarantors; USING and WITH CHECK use SECURITY DEFINER helpers; no direct queries to RLS-protected tables (constitution §5.7).
• UPDATE policies include WITH CHECK for organization_id (constitution §5.2.4).
• PHI handling: no SSN in schema; DOB + legal name + MRN for matching; encryption at rest, RBAC, audit per HIPAA and constitution §4.

​

Common Mistakes

​

Pre-Flight Checklist

• Validate permission keys are seeded and enforced in UI/API.
• Validate RLS helper use (pm_can_access_patient, pm_can_modify_patient).
• Validate duplicate detection and merge path behavior.
• Validate patient_registered event contract and subscribers.
• Validate PHI-safe logging and sanitized errors.

​

Related Docs

• CROSS_CORE_INTEGRATIONS.md
• CL-01-patient-chart-clinical-summary-INTEGRATION.md (patient identity boundary)
• API_CONTRACTS.md
• EVENT_CONTRACTS.md