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.1
Last Updated: 2026-03-02 (manual follow-up: FA journal entry guidance, deleted_at, pending contracts updated)
Status: 📋 Planned
Spec: PM-33 Capitation & PMPM Revenue Reconciliation
Constitution Reference: Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

​
Overview

PM-33 adds capitation contract management, roster tracking (enrollment/dis-enrollment), monthly period generation, and payment reconciliation for PMPM contracts. It integrates with PM-01 (patient/member identity for roster events), PM-09 (payment posting), PM-11 (RCM dashboard — capitation revenue and utilization), PM-23 (contract terms reference), and FA (revenue recognition via capitation_payment_received event).

​
Integration Points (from spec)

DependencyPatternPurposeStatus
PM-01Data (same core)Patient/member identity for pm_capitation_roster_events.patient_id📋 Planned
PM-09Data (same core)Future: link capitation payment posting to PM-09 payment records📋 Deferred (MVP: PM-33 dedicated flow)
PM-11Data (same core)Capitation revenue and utilization vs. cap in RCM dashboard📋 Planned
PM-23Data (same core)Contract terms cross-reference (no FK in MVP; future: link to pm_contracts)📋 Deferred
FAEvent (capitation_payment_received)Revenue recognition — FA consumes event for AR/revenue posting📋 Planned
PF-30Platform LayerPermission seeding — pm.capitation.view, pm.capitation.manage📋 Planned

​
Data Source Tables (PM-33)

TableKey ColumnsUsed By
pm_capitation_contractsorganization_id, payer_id, pmpm_rate, effective_from, effective_to, roster_source, deleted_atContract list (active only: WHERE deleted_at IS NULL), period generation
pm_capitation_periodscontract_id, period_start_date, enrolled_member_count, expected_revenue, received_revenue, statusRCM dashboard (PM-11), reconciliation
pm_capitation_roster_eventscontract_id, patient_id, member_id_external (encrypted), event_type, effective_date, sourceRoster management, enrollment count
pm_capitation_reconciliationsperiod_id, expected_amount, received_amount, variance_amount, variance_disposition, reconciled_byVariance tracking, audit trail

​
Event Contract: capitation_payment_received

Publisher: PM (pm_capitation_reconciliations on payment post)
Subscriber: FA (AR / revenue recognition)
Status: 📋 Pending — EVENT_CONTRACTS.md entry to be created as a generate-tasks task. Draft payload: 
{
  "event": "capitation_payment_received",
  "version": "1.0",
  "payload": {
    "organization_id": "uuid",
    "contract_id": "uuid",       // → pm_capitation_contracts.id
    "period_id": "uuid",         // → pm_capitation_periods.id
    "amount": "numeric",         // received_amount
    "payment_date": "date",
    "payer_id": "uuid",          // → pm_payers.id
    "reconciliation_id": "uuid"  // → pm_capitation_reconciliations.id
  }
}
Security: Event payload must not include member_id_external or any PHI. organization_id is required for FA tenant isolation.

​
FA Journal Entry Guidance (GAAP ASC 606)

Capitation revenue is recognized ratably over the service period (not upon cash receipt). The FA consumer of capitation_payment_received should post the following journal entry:
AccountDr / CrAmountNotes
Cash / AR (asset)DramountCash received from MCO
Capitation Revenue (revenue)CramountRecognized for period_id service period
Period matching: FA must use period_id (→ pm_capitation_periods.period_start_date / period_end_date) to post revenue to the correct accounting period. Payments received outside the service month (early or late) must still credit the revenue account for the period covered, not the cash receipt date — confirm with CFO/Controller. Deferred revenue consideration: If MCO pays capitation in advance of the service month, FA may need a deferred revenue liability entry until the period begins. Confirm with FA team whether advance capitation payments occur in practice. FA team confirmation required (PENDING_CONTRACTS.md): FA team must confirm the chart of accounts structure (account codes for MCO capitation revenue, payer-specific AR) before EVENT_CONTRACTS.md entry is finalized.

​
Platform Layer Usage

  • PM-11: Reads pm_capitation_periods (expected_revenue, received_revenue, status) and pm_encounters (encounter count vs. capitation amount) for dashboard widgets. No new event contracts; same-core data access.
  • PF-30 Permissions: pm.capitation.view and pm.capitation.manage seeded via migration; checked via useHasPermission in UI.
  • @/platform/csv: Bulk import pattern for CSV roster upload; column mapping derived from pm_capitation_roster_events schema.

​
Integration Matrix

FromToPatternStatusDoc
PM (PM-33)FAEvent (capitation_payment_received)📋 PlannedThis doc; EVENT_CONTRACTS.md stub pending
PM (PM-33)PM-11Data (same core)📋 PlannedThis doc
PM (PM-33)PM-01Data (same core, patient_id FK)📋 PlannedThis doc
PM (PM-33)PM-09Data (same core, future payment link)📋 DeferredThis doc
PM (PM-33)PM-23Data (same core, future contract FK)📋 DeferredThis doc

​
Pending Contracts

ContractBlocked OnWhat’s Needed
capitation_payment_received EVENT_CONTRACTS.md entryPM-33 implementationFormalize event payload; FA team to confirm chart of accounts (capitation revenue account codes, payer-specific AR) and deferred revenue handling for advance MCO payments — see FA Journal Entry Guidance above
PM-33 to PM-11 utilization queryPM-11 implementationDefine SQL: encounter count per contract per period vs. capitation amount; join pm_capitation_periods + pm_encounters on organization_id + period date range; confirm join key with PM-11 implementation

​
Security Notes

  • All four PM-33 tables are RLS-protected with pm_has_org_access(organization_id, auth.uid()).
  • UPDATE policies include WITH CHECK preventing organization_id modification.
  • member_id_external is PHI; encrypted at rest via pgcrypto; decrypt only via pm_decrypt_member_id() SECURITY DEFINER function.
  • capitation_payment_received event must never include PHI in payload.

​
References