Encore OS — Documentation

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)

Dependency	Pattern	Purpose	Status
PM-07	Data (same core)	`pm_charges.charge_amount` snapshot for margin calculation; `pm_encounters` for encounter duration and service_date	✅ Implemented
PM-25	Data (same core)	PM-25 reads `pm_encounter_costs` for cost benchmarking and PMPM/TCOC calculations	✅ Implemented
FA-35	Event (`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-30	Platform Layer	Permission 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.)
HR	None (future)	Provider hourly rates currently entered manually; HR integration deferred to future spec	⏸ Deferred

Data Source Tables (PM-35)

Table	Key Columns	Used By
`pm_cost_categories`	organization_id, name, category_type, is_active	Rate lookup; UI configuration
`pm_cost_rates`	organization_id, cost_category_id, site_id, provider_id, rate_amount, rate_unit, effective_from, effective_to	Edge function rate lookup; UI rate management
`pm_encounter_costs`	organization_id, encounter_id, patient_id, provider_id, site_id, service_date, total_cost, cost_breakdown, charge_amount, margin, status	PM-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:

Validates auto_calculate_encounter_cost = true in pm_module_settings
Looks up effective cost rates for service_date, site_id, and provider_id
Calculates cost_breakdown and total_cost per rate_unit rules (spec § Rate Calculation Rules C-8)
Snapshots charge_amount from pm_charges for the encounter (C-2)
Inserts pm_encounter_costs with status = 'calculated'
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

Layer	Usage
`@/platform/scheduling`	Encounter context (encounter duration, provider, site) via `useEncounterContext(encounterId)`
`@/platform/types`	`EncounterContext`, `ChargeContext` shared types
`@/platform/permissions`	`useHasPermission('pm.cost_accounting.view')` and `pm.cost_accounting.manage`

Open Items

Item	Details	Blocked On
FA-35 consumer confirmation	FA-35 to confirm `cost_breakdown` JSONB shape required for cost-allocation entries	FA-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 publisher	Confirm 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

↔ PM-07: Problem List → Encounter Diagnosis Pre-population — Integration Integration Documentation: PM-50 — AI-Powered Denial Prediction & Prevention

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

Encounter-Level Cost Accounting — Integration

Overview

Integration Points (from spec)

Data Source Tables (PM-35)

Event Contract: `encounter_cost_calculated`

Trigger Mechanism

Platform Layer Usage

Open Items

References

​Overview

​Integration Points (from spec)

​Data Source Tables (PM-35)

​Event Contract: encounter_cost_calculated

​Trigger Mechanism

​Platform Layer Usage

​Open Items

​References

Overview

Integration Points (from spec)

Data Source Tables (PM-35)

Event Contract: `encounter_cost_calculated`

Trigger Mechanism

Platform Layer Usage

Open Items

References