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

# PM System Configuration & Admin Settings — Integration

> Version: 1.0.0 Status: \U0001F4DD Planned Last Updated: 2026-03-02 PM System Configuration & Admin Settings Constitution Reference: Section 1.2 (Core Indep…

**Version:** 1.0.0\
**Status:** 📝 Planned\
**Last Updated:** 2026-03-02\
**Spec:** [PM-28 PM System Configuration & Admin Settings](../../../specs/pm/specs/PM-28-pm-system-configuration-admin-settings.md)\
**Constitution Reference:** Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

***

## Overview

PM-28 provides the single admin surface ("Practice Management Settings") for all org-level `pm_module_settings` keys consumed by PM billing, payments, registration, and eligibility workflows. It does not introduce new tables or data flows; it is a UI aggregator over the existing `pm_module_settings` row (one per org).

**Key tables:** `pm_module_settings` (existing; columns owned by consumer spec migrations)

***

## Integration Points (from spec)

| Dependency | Pattern                      | Purpose                                                                                                         | Status      |
| ---------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------- |
| **PF-01**  | Platform Layer (org context) | Organization context; `organization_id` scoping for settings row                                                | ✅ Available |
| **PF-30**  | Platform Layer (permissions) | Permission keys `pm.settings.view` / `pm.settings.manage`; role assignments (Billing Manager, Org Admin)        | ✅ Available |
| **PM-01**  | Data (read config)           | Registration/eligibility settings (MRN format, auto-eligibility, patient merge window)                          | 📝 Planned  |
| **PM-08**  | Data (read config)           | Claim generation reads claim defaults (prefix, NPI, POS, claim type, filing deadline) from `pm_module_settings` | 📝 Planned  |
| **PM-09**  | Data (read config)           | Payment posting reads payment number prefix/sequence from `pm_module_settings`                                  | 📝 Planned  |
| **PM-20**  | Data (read config) — Phase 2 | GFE business-day config (`gfe_business_days_config`); section hidden until PM-20 Phase 2 ships                  | 📝 Deferred |
| **PM-22**  | Data (read config) — Phase 2 | Superbill template reference; section hidden until PM-22 ships; column name deferred to PM-22 spec              | 📝 Deferred |
| **PM-23**  | Data (read config) — Phase 2 | Underpayment tolerance and contract expiration alert days; section hidden until PM-23 ships                     | 📝 Deferred |

***

## Platform Integration Layer Usage

* **PF-01:** Organization context via `pf_organizations`; `organization_id` is the partition key for the `pm_module_settings` upsert.
* **PF-30:** Permissions platform layer; `useHasPermission('pm.settings.view')` / `useHasPermission('pm.settings.manage')` gate page access and save action.

***

## Event Contracts

*No new events defined in PM-28.* Settings changes do not publish domain events (settings are read by consumer hooks on demand). Future enhancement: `pm_settings_updated` event if consumers require reactive cache invalidation.

***

## API Contracts

*Internal PM only.* `usePmModuleSettings` (read) and `usePmModuleSettingsUpsert` (write) in `src/cores/pm/hooks/`; no external API exposed. Consumer specs (PM-01, PM-08, PM-09) read `pm_module_settings` directly via their own hooks.

***

## Integration Matrix

| From       | To    | Pattern                                      | Status      | Doc                                                                     |
| ---------- | ----- | -------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| PM (PM-28) | PF-01 | Platform Layer (org context)                 | ✅ Available | [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md)    |
| PM (PM-28) | PF-30 | Platform Layer (permissions)                 | ✅ Available | [PLATFORM\_INTEGRATION\_LAYERS.md](./PLATFORM_INTEGRATION_LAYERS.md)    |
| PM (PM-28) | PM-01 | Data (settings read by PM-01)                | 📝 Planned  | [PM-01 Integration](./patient-registration-demographics-integration.md) |
| PM (PM-28) | PM-08 | Data (claim defaults read by PM-08)          | 📝 Planned  | [PM-08 Integration](./claims-management-submission-integration.md)      |
| PM (PM-28) | PM-09 | Data (payment numbering read by PM-09)       | 📝 Planned  | [PM-09 Integration](./payment-posting-era-processing-integration.md)    |
| PM (PM-28) | PM-20 | Data (GFE config — Phase 2 deferred)         | 📝 Deferred | —                                                                       |
| PM (PM-28) | PM-22 | Data (superbill template — Phase 2 deferred) | 📝 Deferred | —                                                                       |
| PM (PM-28) | PM-23 | Data (contract settings — Phase 2 deferred)  | 📝 Deferred | —                                                                       |

***

## Security Notes

* `pm_module_settings` RLS restricts all reads and writes to the user's `organization_id`; no cross-org access is possible.
* `updated_by` populated on every upsert by `usePmModuleSettingsUpsert`; provides audit trail per compliance requirement.
* Permission keys added via migration to `pf_module_permissions` and `pf_role_permissions`; PF-30 enforces at hook level.