> ## 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 — Administrator Guide

> Module: Practice Management (PM) Feature: PM-01 Patient Registration & Demographics Version: 1.0 Updated: 2026-02-18

**Module:** Practice Management (PM)\
**Feature:** PM-01 Patient Registration & Demographics\
**Version:** 1.0\
**Updated:** 2026-02-18

***

## Overview

This guide covers permission configuration, role assignments, audit considerations, and data management for the Patient Registration feature (PM-01).

***

## Permission Key Reference

| Permission Key       | Constant                         | Description                                                |
| -------------------- | -------------------------------- | ---------------------------------------------------------- |
| `pm.patients.view`   | `PM_PERMISSIONS.PATIENTS_VIEW`   | View patient list and detail pages                         |
| `pm.patients.create` | `PM_PERMISSIONS.PATIENTS_CREATE` | Register new patients (shows Register button)              |
| `pm.patients.update` | `PM_PERMISSIONS.PATIENTS_UPDATE` | Edit demographics and manage child records                 |
| `pm.patients.merge`  | `PM_PERMISSIONS.PATIENTS_MERGE`  | Merge duplicate patient records (Phase 2 — not yet active) |

***

## Default Role Assignments

These assignments are seeded by the PM-01 database migration (`pf_role_permissions`):

| System Role  | View | Create | Edit | Merge |
| ------------ | ---- | ------ | ---- | ----- |
| `org_admin`  | ✅    | ✅      | ✅    | ✅     |
| `site_admin` | ✅    | ✅      | ✅    | —     |
| `staff`      | ✅    | ✅      | —    | —     |
| `readonly`   | ✅    | —      | —    | —     |

> **Note:** The `org_admin` role automatically receives all active permissions via the platform trigger. Custom roles can be configured in **Settings > Permissions**.

***

## Managing PM Permissions

1. Navigate to **Settings > Permissions** (requires `org_admin` role).
2. Select the **Practice Management** module from the module list.
3. Assign or revoke permissions per role using the toggle interface.
4. Changes take effect immediately for newly issued tokens; existing sessions refresh on next page load.

***

## MPI Duplicate Override Audit

When a staff member overrides a duplicate warning during patient registration:

* The override reason is stored in the patient's `custom_fields` JSONB column under the key `mpi_override_reason`.
* The `created_by` column records which user performed the registration.
* The `created_at` timestamp provides the exact time of registration.

To audit overrides, run the following query in the Supabase SQL editor:

```sql theme={null}
SELECT 
  id,
  mrn,
  first_name,
  last_name,
  created_by,
  created_at,
  custom_fields->>'mpi_override_reason' AS override_reason
FROM pm_patients
WHERE 
  organization_id = '<your_org_id>'
  AND custom_fields->>'mpi_override_reason' IS NOT NULL
ORDER BY created_at DESC;
```

***

## Soft Delete vs. Permanent Delete

Patient records and child records (addresses, contacts, guarantors) use **soft deletion** — the `deleted_at` column is set to the current timestamp, and records are hidden from standard views.

**Soft delete behavior:**

* Records remain in the database for audit and recovery.
* Application queries filter `deleted_at IS NULL`.
* RLS policies enforce this at the database level.

**To restore a soft-deleted record** (administrators only):

```sql theme={null}
UPDATE pm_patients
SET deleted_at = NULL, updated_at = NOW()
WHERE id = '<patient_id>'
  AND organization_id = '<your_org_id>';
```

**Permanent deletion** is not available through the UI and should only be performed by a database administrator in compliance with your organization's data retention policy.

***

## Module Settings

The `pm_module_settings` table contains organization-specific configuration for the PM module. Currently, the settings UI is not exposed (Phase 3). Direct database edits can be made for:

| Setting                       | Default  | Description                                |
| ----------------------------- | -------- | ------------------------------------------ |
| `patient_number_prefix`       | `'MRN-'` | Prefix for manually entered MRNs           |
| `duplicate_detection_enabled` | `true`   | Enable MPI duplicate check on registration |

To view current settings:

```sql theme={null}
SELECT * FROM pm_module_settings WHERE organization_id = '<your_org_id>';
```

***

## Database Tables

| Table                   | Description                               |
| ----------------------- | ----------------------------------------- |
| `pm_patients`           | Core patient demographics (USCDI v3)      |
| `pm_patient_addresses`  | Patient address records (soft-delete)     |
| `pm_emergency_contacts` | Emergency contact records (soft-delete)   |
| `pm_guarantors`         | Financial guarantor records (soft-delete) |
| `pm_module_settings`    | Organization-level PM configuration       |

All tables have RLS enabled with `FORCE ROW LEVEL SECURITY`. SECURITY DEFINER helpers (`pm_has_org_access`, `pm_can_access_patient`, `pm_can_modify_patient`) prevent RLS recursion.

***

## Related Resources

* [User Guide](./patient-registration-user-guide.md)
* [PM-01 Specification](../../specs/pm/specs/PM-01-patient-registration-demographics.md)
* [Implementation Log](../../specs/pm/IMPLEMENTATION_LOG.md)
* Platform Permissions: `src/platform/permissions/constants.ts`