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: specs/pm/specs/PM-47-managed-care-authorization-tracking.md
Status: 📋 Planned
Last Updated: 2026-04-07
Overview
PM-47 provides managed care authorization lifecycle tracking, expiration alerting, auth-to-claim validation, and auth denial appeal workflows for behavioral health organizations. It extends PM-10 (Prior Authorization Management) with ongoing MCO-specific tracking capabilities.
Integration Points
| Dependency | Type | Description |
|---|
| PF-01 (Organizations & Sites) | Direct | Organization and site context for multi-tenant auth tracking |
| PF-02 (RBAC) | Direct | Permission checks for auth management actions |
| PF-10 (Notifications) | Platform Layer (@/platform/notifications) | Auth expiration alerts and review deadline reminders |
| PF-96 (Jurisdiction Profiles) | Platform Layer (@/platform/jurisdiction) | Payer-specific filing deadlines, review intervals, appeal windows |
Same-Core Dependencies
| Dependency | Type | Description |
|---|
| PM-10 (Prior Authorization) | Data (logical linkage: prior_auth_id) | PM-47 pm_managed_care_authorizations.prior_auth_id provides logical linkage to PM-10 pm_prior_authorizations.id. PM-10 owns PA request/approval; PM-47 owns ongoing MCO tracking. |
| PM-08 (Claims Submission) | Event / Validation Gate | PM-47 provides pre-submission auth-to-claim validation. Consumes pm.claim.posted to increment used_units. |
| PM-29 (Claims Denial Management) | Boundary | PM-29 owns claim denials (post-submission); PM-47 owns auth denials (pre-submission). Distinct workflows, actors, and timelines. |
Cross-Core References
| Core | Type | Description |
|---|
| CL-36 (Clinical Documentation) | UUID reference | Clinical docs referenced by ID in concurrent review submissions and appeal justifications. No FK, no schema changes to CL tables. |
Event Contracts
Events Published
| Event Name | Publisher | Subscribers | Payload | Status |
|---|
pm.auth.expiring | PM-47 | PM (dashboard refresh), CL (clinical review prep) | { authorization_id, patient_id, payer_id, expiration_date, days_remaining, organization_id } | 📝 Planned |
pm.auth.validation_failed | PM-47 | PM-08 (claim submission gate) | { claim_id, failed_lines: [{ line_number, reason }], organization_id } | 📝 Planned |
Events Consumed
| Event Name | Publisher | Description |
|---|
pm.claim.posted | PM-08 | Increment used_units on matching authorization when claim is paid |
API Contracts
Edge Functions
| Function | Method | Purpose | Auth |
|---|
pm-auth-expiration-alerts | Cron (daily 6:00 AM) | Check for expiring auths, send PF-10 notifications | Service role |
pm-auth-claim-validation | POST | Validate claim lines against active auths | JWT (user) |
Validation API (pm-auth-claim-validation)
Request:
{
claim_id: string;
claim_lines: Array<{
line_number: number;
date_of_service: string;
units: number;
service_type: string;
}>;
organization_id: string;
}
{
valid: boolean;
results: Array<{
line_number: number;
status: 'pass' | 'fail';
reason?: string;
authorization_id?: string;
}>;
}
| Layer | Import | Usage |
|---|
| Notifications | @/platform/notifications | Auth expiration alerts, review reminders |
| Jurisdiction | @/platform/jurisdiction | useJurisdictionProfile() for payer-specific deadlines |
| Permissions | @/platform/permissions | useHasPermission() for auth management actions |
Permission Keys
| Key | Purpose |
|---|
pm.managed_care_auth.view | View authorization list and details |
pm.managed_care_auth.create | Create new authorizations |
pm.managed_care_auth.edit | Edit authorization records |
pm.managed_care_auth.validate | Run auth-to-claim validation |
pm.managed_care_auth.override | Override validation failures (supervisor) |
pm.auth_review.manage | Manage concurrent reviews |
pm.auth_appeal.manage | Manage auth denial appeals |
Data Flow Diagram
PM-10 (PA Request)
└── pm_prior_authorizations (approved)
└── PM-47: pm_managed_care_authorizations (prior_auth_id FK)
├── Dashboard: expiration countdown, remaining units
├── Alerts: PF-10 notifications at 14/7/3/1 days
├── Concurrent reviews: pm_auth_concurrent_reviews
├── Retro-auth: structured workflow
├── Auth denial appeals: pm_auth_denial_appeals
└── Validation gate → PM-08 claim submission
└── pm.claim.posted → used_units increment
Validation Checklist
References:
- Spec:
specs/pm/specs/PM-47-managed-care-authorization-tracking.md
- PM-10 Integration:
docs/architecture/integrations/PM-10-prior-authorization-management-INTEGRATION.md
- PM-08 Integration:
docs/architecture/integrations/PM-08-claims-management-submission-INTEGRATION.md
- PM-29 Integration:
docs/architecture/integrations/PM-29-claims-denial-management-appeals-INTEGRATION.md
- PF-96 Integration:
docs/architecture/integrations/PF-96-medicaid-state-compliance-configuration-INTEGRATION.md
