Eligibility

FK Relationship Diagram

erDiagram
    Patient ||--o{ Coverage : "insured by"
    InsurancePlan ||--o{ Coverage : "plan for"
    Patient ||--o{ EligibilityCheck : "verified for"
    Coverage ||--o{ EligibilityCheck : "checked against"
    EligibilityCheck ||--o{ BenefitDetail : "yields"
    Patient ||--o{ PriorAuth : "requests"
    Coverage ||--o{ PriorAuth : "authorized under"
    Provider ||--o{ PriorAuth : "ordered by"
    Encounter ||--o| PriorAuth : "linked to"
  

Prior Auth State Machine

stateDiagram-v2
    [*] --> Pending : Submitted
    Pending --> Approved : Payer approves
    Pending --> Denied : Payer denies
    Pending --> Pended : Payer requests more info
    Pending --> Cancelled : Practice cancels
    Pended --> Pending : Additional info submitted
    Pended --> Cancelled : Practice cancels
    Denied --> Pending : Appeal submitted
    Approved --> [*]
    Denied --> [*]
    Cancelled --> [*]
  

Functional Requirements

1. P0 The system shall maintain InsurancePlan records with payer ID, plan type, line of business, and X12/FHIR capability flags.
2. P0 The system shall store Coverage records linking patients to insurance plans with subscriber details and primary/secondary/tertiary ranking.
3. P0 The system shall perform real-time eligibility checks via X12 270/271 or FHIR CoverageEligibilityRequest at configurable triggers (Booking, T-24h, CheckIn, Manual).
4. P0 The system shall parse X12 271 responses into structured BenefitDetail records with copay, coinsurance, deductible, and OOP amounts per service category.
5. P0 The system shall encrypt raw X12/FHIR request and response payloads at rest (AES-256).
6. P0 The system shall submit prior-authorization requests via X12 278, FHIR DaVinci PAS, fax, or payer portal.
7. P0 The system shall enforce CMS-0057-F decision deadlines: 72 hours for expedited, 7 calendar days for standard requests.
8. P0 The system shall track PA decision status (Pending, Approved, Denied, Pended, Cancelled) with auth numbers and approved units/dates.
9. P0 The system shall surface eligibility status on the Scheduling module's Appointment entity (Active, Inactive, Pending, Unknown).
10. P1 The system shall support batch eligibility checks for next-day appointments via a nightly job.
11. P1 The system shall detect and flag coverage gaps (TerminationDate in the past, no active coverage) at check-in.
12. P1 The system shall route PA denials to a task queue for appeal workflow with clinical justification attachment.
13. P1 The system shall track clearinghouse routing (Stedi, Availity, Waystar) and response latency per transaction.
14. P2 The system shall provide a dashboard showing eligibility check success rates, average latency, and PA turnaround times by payer.

Non-Functional Requirements

• Latency: Real-time eligibility check round-trip must complete within 10 seconds (clearinghouse + parsing).
• Throughput: Support 200 concurrent eligibility checks per organization during morning check-in surge.
• Encryption: Raw X12/FHIR payloads encrypted at rest (AES-256) and in transit (TLS 1.2+).
• Retry: Failed eligibility checks automatically retried 3 times with exponential backoff before marking Error.
• Audit Trail: Every eligibility check and PA state change logged with actor, timestamp, and prior value.
• Retention: Eligibility check records and PA records retained for 7 years per HIPAA guidance.
• HIPAA: Subscriber PII fields (name, DOB) encrypted at rest; access logged.
• Availability: Eligibility endpoints 99.9% uptime; graceful degradation to "Unknown" status when clearinghouse is unreachable.

icApplication Overrides

How the five Eligibility AMI schemas turn into a live application: module-specific stack additions, override component bindings, a versioning worked example, environment cascade, and RBAC enforcement.

Technology stack P0

The shared platform stack (Cosmos DB, Redis, IC-generated API, Angular 21, SQS+SNS, OpenTelemetry, etc.) is documented in the IC Reference. Module-specific additions:

Eligibility-specific override bindings P1

These overrides are declared in rules/*.rules.json and replace the default for the matching field name pattern.

Versioning — worked example P0

All Eligibility artifacts are versioned break.feature.bug.buildtimestamp per IC hard rule #9. The example below traces a feature bump on InsurancePlan.

InsurancePlan 1.0.0.20260301T120000Z — Initial schema. Eight business fields plus three audit fields. Component ic-ng21-eligibility-1-app and ic-ng21-eligibility-1-coverage-card bind to insuranceplan@1.0.0.* via the DI manifest.

InsurancePlan 1.1.0.20260415T093000Z — feature bump — Adds a single optional field, FormularySupportedBool, to flag plans whose payer surfaces formulary data via the eRx-side RTPB. Per the IC change matrix:

Because the change is backward-compatible, the component tag stays ic-ng21-eligibility-1-coverage-card. Existing UI consumers continue to bind insuranceplan@1.x.* and ignore the new field. New UI surfaces that need the flag bind insuranceplan@^1.1.0. No new database is required (IC rule #13 only applies to break bumps).

InsurancePlan 2.0.0.20271101T120000Z — break bump (illustrative) — An illustrative future break bump: PlanTypeString50 is split into a strongly-typed PlanTypeEnum field. Per the IC change matrix this is change field type — break bump, EditAMI (90) approval, and per IC rule #13 a new database is provisioned with ETL from the old one. The component tag becomes ic-ng21-eligibility-2-coverage-card; consumers must re-bind. The old database stays live for the configured grace period (default 90 days) for rollback.

Eligibility environment details

Eligibility RBAC notes

• Raw-response access. Read raw RawRequestText / RawResponseText requires ≥ 70; this is enforced even for the patient’s own data because raw payloads can leak unrelated coverage details.
• PA decisions. The PriorAuth.DecisionStatusString50 column is writable only by the system service account (transcribing payer responses) or by users at level ≥ 70 (manager / clinician override). Level 51 (biller) can submit and cancel but cannot record a decision.
• Self-pay override. The eligibility-gate self-pay override (FR-EL-008) requires level ≥ 30 plus a SelfPayAcknowledgedBool patient acknowledgement; both are recorded in audit.

Cross-Module Links

• Scheduling — Eligibility check triggered at booking/T-24h/check-in; status surfaced on Appointment.
• Revenue Cycle Management — Coverage and BenefitDetail feed claim generation; PA AuthNumber attached to claims.
• Patient Portal — Patients view coverage summary, benefit details, and PA status.
• eRx / EPCS — Medication prior-auth triggered from eRx formulary check.
• Task Management — PA denials and pending items generate tasks for billing/clinical staff.
• Coding & CDS — Diagnosis and procedure codes feed PA service/diagnosis code fields.

Cross-Module Dependencies

• Scheduling — emits the appointment-confirmed event consumed by FR-EL-001; consumes the eligibility-status-changed event for FR-EL-008 visit-type gating.
• RCM — reads Coverage and BenefitDetail for claim routing and remit reconciliation; supplies contract rates back to the cost-estimator (FR-EL-007).
• Patient Portal — surfaces patient cost estimates and PA status to the patient; respects read-access audit per Terms of Care.
• eRx / EPCS — medical-side PA flow handed off here when the prescribing flow detects a medical-benefit (vs. pharmacy-benefit) requirement (e.g., infused biologics).
• Task Management — PA decisions create FHIR Task rows in clinician / biller queues; SLA breach alerts route here too.
• Coding / CDS — supplies CPT/HCPCS catalog and CDS Hooks rules that flag PA requirements alongside the parsed BenefitDetail signal.

See also: Eligibility walkthrough · IC Reference