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 Last Updated: 2026-05-11 Status: ✅ Complete Spec: PM-35 Encounter-Level Cost Accounting Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

​
Overview

PM-35 adds encounter-level cost accounting to the Practice Management core: cost category configuration, rate management, automatic cost calculation on encounter completion, and margin reporting. It integrates with PM-07 (charge snapshot for margin), PM-25 (VBP cost benchmarking), and FA-35 (cost allocation) via an event contract.

​
Integration Points (from spec)

DependencyPatternPurposeStatus
PM-07Data (same core)pm_charges.charge_amount snapshot for margin calculation; pm_encounters for encounter duration and service_date✅ Implemented
PM-25Data (same core)PM-25 reads pm_encounter_costs for cost benchmarking and PMPM/TCOC calculations✅ Implemented
FA-35Event (encounter_cost_calculated)FA consumes event for program/department cost allocation (downstream consumer)📝 Schema documented in EVENT_CONTRACTS.md (≈L6126); awaiting FA-35 consumer confirmation (C-9)
PF-30Platform LayerPermission seeding — pm.cost_accounting.view, pm.cost_accounting.manage✅ Complete — view: org_admin, platform_admin, staff, finance_admin, finance_staff. manage: org_admin, platform_admin, finance_admin. (Spec’s “Billing Manager / Financial Analyst” mapped to finance_staff / finance_admin since no such system roles exist; seeded 2026-05-11.)
HRNone (future)Provider hourly rates currently entered manually; HR integration deferred to future spec⏸ Deferred

​
Data Source Tables (PM-35)

TableKey ColumnsUsed By
pm_cost_categoriesorganization_id, name, category_type, is_activeRate lookup; UI configuration
pm_cost_ratesorganization_id, cost_category_id, site_id, provider_id, rate_amount, rate_unit, effective_from, effective_toEdge function rate lookup; UI rate management
pm_encounter_costsorganization_id, encounter_id, patient_id, provider_id, site_id, service_date, total_cost, cost_breakdown, charge_amount, margin, statusPM-25 VBP queries; cost reports; FA event payload source

​
Event Contract: encounter_cost_calculated

Publisher: PM (edge function pm-calculate-encounter-cost, triggered on encounter_completed) Subscriber: FA-35 (cost allocation / program cost reporting) Status: 📝 Payload schema documented in EVENT_CONTRACTS.md (encounter_cost_calculated entry). Outstanding: FA-35 consumer confirmation of cost_breakdown field shape (see PENDING_CONTRACTS.md). Draft payload: 
{
  "event": "encounter_cost_calculated",
  "version": "1.0",
  "payload": {
    "organization_id": "uuid",
    "encounter_id": "uuid",          // → pm_encounters.id
    "cost_record_id": "uuid",        // → pm_encounter_costs.id
    "total_cost": "numeric",         // e.g. 125.50
    "cost_breakdown": {              // JSONB with per-category detail
      "provider_time": { "rate_unit": "per_hour", "rate_amount": 75.00, "quantity": 1.5, "line_cost": 112.50 },
      "facility_overhead": { "rate_unit": "flat", "rate_amount": 13.00, "quantity": 1, "line_cost": 13.00 }
    },
    "service_date": "date",          // ISO date
    "site_id": "uuid",               // optional
    "provider_id": "uuid"            // optional (no FK, opaque UUID per C-6)
  }
}
Schema pending: Finalize in EVENT_CONTRACTS.md entry during Phase 2 task generation. FA-35 team must confirm consumption fields before publishing.

​
Trigger Mechanism

Auto-cost-calculation is driven by an edge function (supabase/functions/pm-calculate-encounter-cost/index.ts) triggered by the encounter_completed event:
  1. Validates auto_calculate_encounter_cost = true in pm_module_settings
  2. Looks up effective cost rates for service_date, site_id, and provider_id
  3. Calculates cost_breakdown and total_cost per rate_unit rules (spec § Rate Calculation Rules C-8)
  4. Snapshots charge_amount from pm_charges for the encounter (C-2)
  5. Inserts pm_encounter_costs with status = 'calculated'
  6. Publishes encounter_cost_calculated event for FA
Dependency (Plan A-3): Confirm encounter_completed event is already published by PM-03/PM-07 before Phase 2 implementation begins.

​
Platform Layer Usage

LayerUsage
@/platform/schedulingEncounter context (encounter duration, provider, site) via useEncounterContext(encounterId)
@/platform/typesEncounterContext, ChargeContext shared types
@/platform/permissionsuseHasPermission('pm.cost_accounting.view') and pm.cost_accounting.manage

​
Open Items

ItemDetailsBlocked On
FA-35 consumer confirmationFA-35 to confirm cost_breakdown JSONB shape required for cost-allocation entriesFA-35 spec update (C-9)
service_line column strategy✅ Resolved (C-11) — denormalized service_line TEXT on pm_encounter_costs, mapped from pm_encounters.encounter_type at calculation time—
per_unit quantity source✅ Resolved (C-12) — auto-calc defaults quantity = 1; cost_breakdown.quantity_source = "auto_default"—
encounter_completed event publisherConfirm PM-03/PM-07 publishes this event (Plan A-3)PM-03 / PM-07 spec review

​
References

  • PM-35 Spec: specs/pm/specs/PM-35-encounter-level-cost-accounting.md
  • PM-35 Plan: specs/pm/plans/PM-35-encounter-level-cost-accounting-PLAN.md
  • PM-25 VBP Integration: docs/architecture/integrations/PM-25-VBP-APM-INTEGRATION.md
  • EVENT_CONTRACTS.md: docs/architecture/integrations/EVENT_CONTRACTS.md (encounter_cost_calculated — pending)
  • PENDING_CONTRACTS.md: docs/architecture/integrations/PENDING_CONTRACTS.md