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

# Patient Registration & Demographics — Integration

> Feature ID: PM-01 Status: 🚧 In Progress Last Verified: 2026-02-18 Spec Reference: PM-01-patient-registration-demographics.md Last Updated: 2026-02-18

**Feature ID:** PM-01\
**Status:** 🚧 In Progress\
**Last Verified:** 2026-02-18\
**Spec Reference:** [PM-01-patient-registration-demographics.md](../../../specs/pm/specs/PM-01-patient-registration-demographics.md)\
**Last Updated:** 2026-02-18

***

## Table of Contents

* [Overview](#overview)
* [Quick Reference](#quick-reference)
* [Decision Trees](#decision-trees)
* [Pattern Library](#pattern-library)
* [Integration Points (from Spec)](#integration-points-from-spec)
* [API / Data Contracts](#api--data-contracts)
* [Labeled Code Examples](#labeled-code-examples)
* [Event Contracts](#event-contracts)
* [Security and RLS](#security-and-rls)
* [Common Mistakes](#common-mistakes)
* [Pre-Flight Checklist](#pre-flight-checklist)
* [Related Docs](#related-docs)

***

## Overview

PM-01 provides patient registration and USCDI v3–aligned demographics, Master Patient Index (MPI) duplicate detection, AHCCCS member/CIS ID capture, and multi-site visibility. It depends on PF for tenancy, RBAC, forms, and custom fields. Downstream consumers (CL-01, PM-02, PM-03) use patient identity via PF or PM-01 data.

***

## Quick Reference

| Item              | Value                                                                               |
| ----------------- | ----------------------------------------------------------------------------------- |
| Core tables       | `pm_patients`, `pm_patient_addresses`, `pm_emergency_contacts`, `pm_guarantors`     |
| Permission keys   | `pm.patients.view`, `pm.patients.create`, `pm.patients.update`, `pm.patients.merge` |
| Primary event     | `patient_registered`                                                                |
| Identity boundary | PF-owned `pf_patient_identities` shared across PM and CL integrations               |

***

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

| Pattern                     | Usage                                                    |
| --------------------------- | -------------------------------------------------------- |
| Direct PF dependency        | PM-01 depends on PF-01/PF-02 for tenancy and permissions |
| Platform forms abstraction  | PF-08 intake forms wrap PM registration payloads         |
| Cross-core contract handoff | PM-01 publishes data for CL-01 and PM-02/PM-03 consumers |

***

## Integration Points (from Spec)

| Dependency                    | Pattern     | Purpose                                                             |
| ----------------------------- | ----------- | ------------------------------------------------------------------- |
| PF-01 (Organizations & Sites) | Direct      | Multi-tenant isolation, organization\_id                            |
| PF-02 (RBAC)                  | Direct      | Permission checks (pm.patients.view, .create, .update, .merge)      |
| PF-08 (Forms)                 | Platform    | Patient intake forms                                                |
| PF-16 (Custom Fields)         | Direct      | Extensible patient metadata (custom\_fields)                        |
| CL-01                         | Cross-core  | Patient chart creation from registration; patient identity boundary |
| PM-02                         | Internal PM | Insurance linked to patient                                         |
| PM-03                         | Internal PM | Appointments linked to patient                                      |

***

## 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](./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

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

### Example: `patient_registered` event payload

```json theme={null}
{
  "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](./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

| Mistake                                 | Impact              | Fix                                              |
| --------------------------------------- | ------------------- | ------------------------------------------------ |
| Omitting `organization_id` in writes    | Tenant leakage risk | Include explicit tenant context in all mutations |
| Treating PM as identity source-of-truth | Boundary drift      | Keep shared identity references in PF layer      |
| Merge workflow without audit events     | Data lineage loss   | Emit merge/audit events with actor metadata      |

***

## 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](./CROSS_CORE_INTEGRATIONS.md)
* [CL-01-patient-chart-clinical-summary-INTEGRATION.md](./patient-chart-clinical-summary-integration.md) (patient identity boundary)
* [API\_CONTRACTS.md](./API_CONTRACTS.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)