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.

Spec: PM-31 OTP/MAT-Specific Billing
Status: 🚧 In Progress (Phase 1 complete; Phase 2 OTP scrubbing rules pending)
Last Updated: 2026-03-26 Owner: PM (Practice Management)

​
Overview

PM-31 implements OTP/MAT-specific billing within the Practice Management core. It integrates with PM-07 (charge capture), PM-08 (claims), PM-09 (payments), PM-10 (prior auth), PM-15 (clearinghouse submission), PM-18 (claim scrubbing), CL-17 (PDMP reference), and PF-70 (HCPCS code library). All integration follows the Platform Integration Layer pattern. No direct CL→PM imports.

​
Integration Points

​
PM-07 — Charge Capture & Fee Schedules

Pattern: Data (same core) / Platform Layer
Direction: PM-31 → PM-07
Description: Approved OTP billing periods trigger charge creation via PM-07. OTP HCPCS codes (G2067–G2080, G2215/G2216, H0020, T1012) are stored as standard entries in pm_fee_schedules; no separate OTP rate table. Data Flow:
  • PM-31 billing period (approved status) → useCreatePmCharge() hook (PM-07) → creates pm_charges row
  • charge_id written back to pm_otp_billing_periods.charge_id
  • OTP rate lookup: pm_fee_schedules filtered by payer + HCPCS code
Contract: Existing PM-07 charge creation contract; OTP adds no new events.

​
PM-08 — Claims Management & Submission

Pattern: Data (same core) / Platform Layer
Direction: PM-31 → PM-08
Description: OTP charges feed into claim generation via PM-08. Claim includes OTP HCPCS codes with modifier and unit rules from payer_specific_config. Data Flow:
  • PM-31 charge_id → PM-08 claim generation → pm_claims row
  • claim_id written back to pm_otp_billing_periods.claim_id
  • Modifier rules from pm_otp_programs.payer_specific_config applied during 837P segment construction
Contract: Existing PM-08 claim generation contract; no new event schema required.

​
PM-09 — Payment Posting & ERA Processing

Pattern: Data (same core)
Direction: PM-09 → PM-31 (via pm_claims)
Description: ERA payment posting updates pm_claims status; PM-31 billing period status reflects claim payment status. No direct PM-31 tables modified by PM-09.

​
PM-10 — Prior Authorization Management

Pattern: Data (same core) / Platform Layer
Direction: PM-31 → PM-10 (auth check); PM-10 → PM-31 (auth status)
Description: For payers requiring prior auth (e.g., AHCCCS H0020), PM-31 claim generation checks for active PM-10 authorization. Auth linked to patient + service type. Data Flow:
  • Claim generation: usePmPriorAuth(patient_id, payer_id, service_type) → active auth check
  • If no active auth and payer requires auth: warn or block claim generation per payer_specific_config

​
PM-15 — Clearinghouse & 837P Submission

Pattern: Data (same core) → External
Direction: PM-15 consumes PM-08 claims (including OTP claims)
Description: 837P submission via PM-15; OTP HCPCS codes included in claim segments. No PM-31-specific submission logic; submission handled by PM-15 standard flow.

​
PM-18 — Claim Scrubbing

Pattern: Data (same core)
Direction: PM-18 scrubs PM-08 claims (including OTP)
Description: PM-31 Phase 2 will seed five OTP-specific rule definitions into pm_scrub_rule_definitions (PM-18 engine table): otp_code_in_program, otp_period_approved, otp_prior_auth_present, otp_units_positive, otp_period_date_range. These will extend the PM-18 engine without modifying its architecture. Orgs may disable or downgrade to warning via pm_scrub_rule_overrides.
TODO(PM-31-P2): Phase 2 seeding migration has not yet been created. Requires PM-18 engine tables to exist before seeding.
Data Flow (planned):
  • PM-31 Phase 2 migration will seed rules → pm_scrub_rule_definitions
  • PM-18 scrubbing engine will evaluate OTP rules during claim generation (PM-08)
  • No PM-31-specific scrubbing code; rules are data-driven per PM-18 architecture

​
CL-17 — Arizona CSPMP/PDMP Integration

Pattern: Cross-core reference (ADR-002 UUID; no FK)
Direction: CL-17 → PM-31 (reference only)
Description: pm_otp_billing_periods.pdmp_reference_id stores a UUID reference to a CL-17 PDMP dispensing record for medical necessity documentation. No PHI is stored in PM tables; the reference supports audit trail only. ADR-002 compliance: No FK constraint on pdmp_reference_id; cross-core UUID reference only.

​
PF-70 — Medical Terminology & Code Libraries

Pattern: Platform Layer
Direction: PM-31 → PF-70 (read-only)
Description: PF-70 HCPCS code set used for application-layer validation of bundled_codes, add_on_codes, and pm_otp_service_components.hcpcs_code. DB CHECK enforces format; PF-70 enforces code membership at write time. Reference: PF-70 Integration

​
Platform Layers Used

LayerUsage
@/platform/permissionsuseHasPermission('pm.otp.view'), useHasPermission('pm.otp.manage')
@/platform/table-v2OTP programs list, billing periods list, service components table
@/platform/formsProgram create/edit form, billing period form
PF-70 HCPCS lookupCode type-ahead and validation in forms

​
Security & Compliance Notes

  • All OTP tables use RLS with pm_has_org_access(organization_id, auth.uid()) (2-arg SECURITY DEFINER).
  • OTP data is SUD-related PHI subject to 42 CFR Part 2 and HIPAA. Disclosure logging via PF-40. TPO consent enforced by CL-11 layer; PM-31 billing flows under TPO exception.
  • No PHI stored in PM-31 tables beyond patient_id FK and billing metadata (organization_id, codes, amounts). Dispensing detail remains in CL-17 / dispensing system.

​
Pending Contracts

  • PM-18 OTP scrubbing rules (Phase 2 — not yet implemented): 5 rule definitions (otp_code_in_program, otp_period_approved, otp_prior_auth_present, otp_units_positive, otp_period_date_range) defined in PM-31 spec. Seeding migration not yet created. Requires PM-18 engine tables (pm_scrub_rule_definitions) to exist before seeding.

​
References