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.
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 |
// 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. |
| 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 |
| 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.
References
