Encore OS — Documentation

Spec: PM-32
Status: ✅ Complete
Last Updated: 2026-04-03
Owner: PM (Practice Management)

Overview

PM-32 adds a structured financial counseling workflow: income collection, FPL calculation, assistance program referral tracking, and charity care determination. It reads patient data from PM-01, writes insurance policies to PM-02, feeds charity indicator data to PM-16, informs sliding fee decisions to PM-21, and optionally integrates with PM-20 GFE and PF-08 forms. All integrations are same-core data reads (PM-01, PM-02, PM-16, PM-20, PM-21) or platform layer (PF-08 form snapshot). No direct cross-core imports. No event contracts are required for MVP; PM-02 eligibility trigger is a same-core function call.

Integration Points

1. PM-01 (Patient Registration)

Attribute	Detail
Pattern	Same-core data reference (FK)
Direction	PM-32 → PM-01 (reads patient)
Data	`pm_financial_counseling_sessions.patient_id → pm_patients.id`
Notes	Sessions and applications are patient-scoped; patient must exist before counseling session

2. PM-02 (Insurance Policy Management & Eligibility)

Attribute	Detail
Pattern	Same-core function call
Direction	PM-32 → PM-02
Trigger	When `pm_assistance_program_referrals.application_status` transitions to `approved`
Action	Populate `policy_id` FK on referral; call PM-02 eligibility check for the new policy
Notes	Policy must already exist in `pm_insurance_policies` or be created as part of approval; PM-32 links the referral to the policy; PM-02 owns eligibility verification

Stub schema (approval action):

// Called when referral approved
interface ApprovalPayload {
  referralId: string;       // pm_assistance_program_referrals.id
  patientId: string;        // pm_patients.id
  organizationId: string;
  policyId: string;         // pm_insurance_policies.id — must exist
}
// After: trigger PM-02 eligibility check on policyId

3. PM-16 (Patient Statement Generation & Billing Communications)

Attribute	Detail
Pattern	Same-core data read (live join)
Direction	PM-16 → PM-32 tables
Data	PM-16 queries `pm_charity_care_applications` to determine charity indicator
Join condition	`approved_at IS NOT NULL AND (expiration_date IS NULL OR expiration_date > CURRENT_DATE)`
Required index	`idx_pm_charity_care_applications_patient` on `(organization_id, patient_id, expiration_date)`
Notes	No denormalized flag; no event required; PM-32 owns the data, PM-16 reads it

4. PM-20 (Good Faith Estimate & Price Transparency)

Attribute	Detail
Pattern	Informational reference (no direct data dependency for MVP)
Direction	Financial counselor workflow context informs GFE process
Notes	When patient receives financial counseling, counselor may trigger a GFE via PM-20 for out-of-pocket cost estimate; PM-32 does not generate GFEs. PM-20 may read charity status from PM-32 tables in future phases.

5. PM-21 (Sliding Fee Discount Schedule Management)

Attribute	Detail
Pattern	Same-core data read
Direction	PM-21 → PM-32 tables
Data	PM-21 reads `fpl_percentage` from most recent authoritative session in `pm_financial_counseling_sessions` to determine sliding fee tier
Authoritative FPL	Most recent session with `income_verified_at IS NOT NULL`; fallback: most recent by `session_date`
Notes	PM-21 owns the discount schedule; PM-32 owns the income/FPL data. PM-21 does not write to PM-32 tables.

6. PF-08 (Forms)

Attribute	Detail
Pattern	Platform layer (PF-08 form reference + snapshot)
Direction	PM-32 → PF-08 (optional)
Data	`pm_financial_counseling_sessions.form_id → pf_forms.id`; `form_snapshot JSONB`
Notes	Optional: counselors may use a PF-08 intake form for income/asset collection; snapshot is stored for PHI audit trail even if PF-08 template changes

Platform Layers Used

Layer	Usage
`@/platform/clinical` (patient context)	Read patient context for counseling session; `usePatientContext(patientId)` when available
`@/platform/permissions`	`useHasPermission('pm.financial_counseling.view')`, `manage`, `approve_charity`
`PF-30` (RBAC)	Permission keys seeded: `pm.financial_counseling.view`, `manage`, `approve_charity`
`PF-10` (Notifications)	30-day charity expiration reminder; annual review reminder

Event Contracts

Events Consumed

`pm_cost_estimate_generated` (from PM-48)

Publisher: PM-48 (Patient Cost Estimation & Financial Clearance)
Event Name: pm_cost_estimate_generated
Version: 1.0

Payload Schema:

{
  estimate_id: string;
  patient_id: string;
  organization_id: string;
  patient_estimated_responsibility: number;
  service_type: string;
}

Subscription Rules: Conditional — subscribe only when patient_estimated_responsibility exceeds the configured threshold (from PF-96 jurisdiction profile or pm_module_settings.financial_clearance_threshold)
Threshold Behavior:
- Read financial_clearance_threshold from jurisdiction profile (PF-96) if available
- Fallback to pm_module_settings.financial_clearance_threshold (default: $1,000)
- Auto-create PM-32 referral record when threshold exceeded
Delivery Semantics: At-least-once; idempotent via estimate_id (check for existing referral before creating)
Retry Policy: Standard retry with exponential backoff (3 attempts)
Idempotency Keys: estimate_id — prevent duplicate referrals
ACL/Topic: pm.cost_estimates topic
Purpose: Auto-route patients to financial counseling when estimated responsibility exceeds threshold
Status: 📝 Planned

Potential future events (post-MVP):

Event	Producer	Consumers	Notes
`pm_charity_approved`	PM-32	PM-16, FA	Notify statement generation and financial accounting of charity determination. Deferred.
`pm_assistance_referral_approved`	PM-32	PM-02	Trigger eligibility check when referral status = approved. Currently a same-core call.

API Contracts

No external API contracts for MVP. All data flows are internal (same-core or platform layer). Future: AHCCCS direct submission API (deferred per Out of Scope in PM-32 spec).

Security

All tables behind pm_has_org_access SECURITY DEFINER RLS.
pm.financial_counseling.approve_charity is supervisor-level; not assigned to standard counselor role by default.
Income/financial data is PHI; no PHI written to logs; access via RLS + RBAC only.

Pending Contracts

No pending contracts for MVP. See PENDING_CONTRACTS.md if future event contracts are needed.

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

Patient Financial Counseling & Charity Care — Integration Documentation

Overview

Integration Points

1. PM-01 (Patient Registration)

2. PM-02 (Insurance Policy Management & Eligibility)

3. PM-16 (Patient Statement Generation & Billing Communications)

4. PM-20 (Good Faith Estimate & Price Transparency)

5. PM-21 (Sliding Fee Discount Schedule Management)

6. PF-08 (Forms)

Platform Layers Used

Event Contracts

Events Consumed

`pm_cost_estimate_generated` (from PM-48)

API Contracts

Security

Pending Contracts

References

​Overview

​Integration Points

​1. PM-01 (Patient Registration)

​2. PM-02 (Insurance Policy Management & Eligibility)

​3. PM-16 (Patient Statement Generation & Billing Communications)

​4. PM-20 (Good Faith Estimate & Price Transparency)

​5. PM-21 (Sliding Fee Discount Schedule Management)

​6. PF-08 (Forms)

​Platform Layers Used

​Event Contracts

​Events Consumed

​pm_cost_estimate_generated (from PM-48)

​API Contracts

​Security

​Pending Contracts

​References

Overview

Integration Points

1. PM-01 (Patient Registration)

2. PM-02 (Insurance Policy Management & Eligibility)

3. PM-16 (Patient Statement Generation & Billing Communications)

4. PM-20 (Good Faith Estimate & Price Transparency)

5. PM-21 (Sliding Fee Discount Schedule Management)

6. PF-08 (Forms)

Platform Layers Used

Event Contracts

Events Consumed

`pm_cost_estimate_generated` (from PM-48)

API Contracts

Security

Pending Contracts

References