Skip to main content

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.

Version: 1.0.0
Last Updated: 2026-02-27
Status: ✅ Complete
Spec: PM-20-good-faith-estimate-price-transparency

​
Overview

PM-20 implements No Surprises Act (NSA) Good Faith Estimate generation, delivery timing compliance, acknowledgment tracking, and dispute resolution for uninsured/self-pay patients. It depends on PF and same-core PM features only; no cross-core imports.

​
Quick Reference

I need to…PatternLocation
Identify self-pay patients for GFEPM-02 insurance status (uninsured/self-pay)Contract: Same-Core (PM)
Build estimate from scheduled servicesPM-03 appointment + PM-07 fee scheduleContract: Same-Core (PM)
Deliver GFE via email/portalPF-10 notifications + PM-16 statement channelsContract: Platform Foundation
Ensure tenant isolation on GFE/dispute dataRLS via pm_has_org_access; permission keys pm.gfe.*Security & Tenant Isolation

​
Integration Matrix

IntegrationSpecDirectionPatternStatus
Organizations & SitesPF-01PM-20 → PFDirect📝 Planned
RBAC / PermissionsPF-02 (PF-30)PM-20 → PFDirect📝 Planned
Notifications (GFE ready/delivered)PF-10PM-20 → PFPlatform Integration Layer📝 Planned
Patient Registration & DemographicsPM-01PM-20 → PMSame core📝 Planned
Insurance & Eligibility (self-pay check)PM-02PM-20 → PMSame core📝 Planned
Appointment Scheduling (trigger)PM-03PM-20 → PMSame core📝 Planned
Charge Capture & Fee Schedules (rates)PM-07PM-20 → PMSame core📝 Planned
Patient Statements & CommunicationsPM-16PM-20 → PMSame core📝 Planned

​
Cross-Core Summary (CROSS_CORE_INTEGRATIONS.md)

From CoreTo CoreIntegration PatternStatusDocumentation
PM (PM-20)PF-01, PF-02, PF-10, PM-01, PM-02, PM-03, PM-07, PM-16Platform Layer / Data📝PM-20 Good Faith Estimate & Price Transparency

​
Contract: Platform Foundation

​
PF-01 (Organizations & Sites)

  • Usage: Tenant context (organization_id) on all PM-20 tables; RLS and app-level filtering.
  • Contract: Standard multi-tenant pattern; no custom API.

​
PF-02 / PF-30 (Permissions)

  • Usage: Permission keys pm.gfe.view, pm.gfe.create, pm.gfe.manage for UI and actions.
  • Contract: Keys defined in spec; seeded in migration; checks via pf_has_permission() and useHasPermission().

​
PF-10 (Notifications)

  • Usage: Optional notification when GFE is ready or delivered to patient.
  • Contract: Use @/platform/notifications (Platform Integration Layer). Payload contains only system-generated UUIDs (patient_id, gfe_id, organization_id); no PHI in notification payloads. Display names resolved via authorized UI calls.

​
Contract: Same-Core (PM)

​
PM-01 (Patient Registration & Demographics)

  • Usage: Patient context for GFE — pm_good_faith_estimates.patient_id references pm_patients.id. Patient name displayed on GFE list and detail views.
  • Contract: Direct table join within PM core; FK enforced at database level.

​
PM-02 (Insurance & Eligibility)

  • Usage: Identify self-pay/uninsured patients eligible for GFE. PM-02 insurance status determines whether GFE is required per NSA.
  • Contract: Query pm_insurance_policies for active policies; if none (or self-pay plan type), patient qualifies for GFE. Direct table access within PM.

​
PM-03 (Appointment Scheduling)

  • Usage: Scheduling trigger for GFE generation. pm_good_faith_estimates.appointment_id references pm_appointments.id. Appointment date determines delivery timing (1 vs 3 business days).
  • Contract: Direct table access within PM. When a self-pay patient is scheduled, GFE generation can be triggered automatically or on demand. Appointment type drives CPT mapping for estimate itemization.

​
PM-07 (Charge Capture & Fee Schedules)

  • Usage: Fee schedule lookup for CPT code rates. GFE itemized amounts come from org fee schedule rates for mapped CPT codes.
  • Contract: Direct query of pm_fee_schedules / pm_fee_schedule_items within PM. Appointment type → CPT mapping (via pm_gfe_appointment_cpt_mapping) provides codes; PM-07 fee schedule provides rates.

​
PM-16 (Patient Statements & Communications)

  • Usage: GFE delivery channels — portal posting, email delivery, print. Reuse PM-16 communication infrastructure where applicable.
  • Contract: Direct PM hooks/queries for delivery method recording. Portal delivery uses PM-12 patient portal scope.

​
Event Contracts

No cross-core events required for PM-20. Internal events (e.g., gfe_generated, gfe_delivered, gfe_dispute_filed) may be added for audit or workflow automation (PM-19); document in EVENT_CONTRACTS.md if added.

​
API Contracts

No public cross-core APIs. Internal PM hooks and utilities (GFE build logic, business day calculation, variance monitoring) are documented in implementation tasks.

​
Security & Tenant Isolation

  • All PM-20 data scoped by organization_id; RLS via pm_has_org_access and app-level filter on every mutation.
  • PHI: GFE and dispute data are PHI; no PHI in logs or notification payloads; access via RLS and permission keys only.
  • Integration with PF-10: no PHI in notification payloads; use system-generated UUIDs only (patient_id, gfe_id, organization_id); resolve display names via authorized API calls in the UI.
  • DELETE restricted to org admins via pf_is_org_admin(auth.uid(), organization_id).
  • UPDATE policies include WITH CHECK to prevent organization_id mutation.

​
Open Items

  • Confirm PM-19 workflow event registration for gfe_generated / gfe_delivered if automation is desired.
  • Phase 2: GFE template management per service line/program (deferred from Phase 1).
  • Phase 2: Org-configured holidays for business day calculation (Phase 1 uses calendar weekdays).