Payer Optimization

Trust tier roll-up

RBAC matrix (IC 0–100 scale)

Patient access hard rule: Patients have no access to any Payer Optimization data — not the config, not the rules, not the suggestions, not the audit log. Payer-margin data is never exposed to patients, and the patient-facing experience is identical whether Payer Optimization is enabled or disabled at the practice.

FK Relationship Diagram

erDiagram
    Organization ||--o| PayerOptimizationConfig : "has"
    PayerOptimizationConfig ||--o{ OptimizationAuditEntry : "audits"
    User ||--o{ OptimizationAuditEntry : "ActorUserID"
    Patient ||--o{ OptimizationAuditEntry : "PatientID"
    Encounter ||--o{ CodingOptimizationSuggestion : "generates"
    

Optimization Suggestion Flow

flowchart TD
    A[Encounter coding completed] --> B[Optimization engine evaluates PayerRules]
    B --> C{Suggestion generated?}
    C -- No --> D[No action]
    C -- Yes --> E{IsCompliant check}
    E -- false --> F[Suppress from UI]
    F --> G[Log NonCompliantSuppressed in audit]
    E -- true --> H[Display to Clinician]
    H --> I{Clinician decision}
    I -- Accept --> J[Update code on ClaimLine]
    J --> K[Log SuggestionAccepted in audit]
    I -- Reject --> L[Keep original code]
    L --> M[Log SuggestionRejected in audit]
    

Functional Requirements

1. P0 The system SHALL enforce all four hard guardrails (no Medicare/Medicaid access reduction, no protected-category discrimination, no patient visibility, no non-compliant suggestion display) at the application layer with no override mechanism.
2. P0 The system SHALL validate every PayerRule against guardrails before activation and reject non-compliant rules with a detailed error message.
3. P0 The system SHALL maintain an immutable, append-only OptimizationAuditEntry log for every action (config changes, rule creation, suggestion acceptance/rejection, non-compliant suppression).
4. P0 The system SHALL suppress CodingOptimizationSuggestion records with IsCompliant=false from all user-facing views; these records are retained exclusively for audit.
5. P0 The system SHALL provide a master on/off switch (PayerOptimizationConfig.IsEnabled) that immediately disables all suggestion generation when set to false.
6. P1 The system SHALL generate coding optimization suggestions by evaluating encounter codes against active PayerRules for the encounter's payer.
7. P1 The system SHALL allow clinicians to accept or reject compliant suggestions, with the decision recorded in the audit trail.
8. P1 The system SHALL support five rule types: Modifier, PreAuth, Documentation, CodingThreshold, and Bundling.
9. P1 The system SHALL allow Billing Managers to create, modify, and deactivate PayerRules with effective dates.
10. P1 The system SHALL display disclosure text to staff when optimization is active, as configured in PayerOptimizationConfig.DisclosureText.
11. P2 The system SHALL provide optimization impact reporting (acceptance rate, revenue impact, denial reduction) for Practice Owners.
12. P2 The system SHALL support rule versioning so that historical rule definitions are preserved when rules are updated.
13. P2 The system SHALL allow Compliance Officers read-only access to all entities including non-compliant suggestions for audit review.
14. P2 The system SHALL support payer-plan-level rule targeting (PayerRule.PayerPlanId) for granular optimization.

Non-Functional Requirements

• Latency: Suggestion generation completes within 2 seconds per encounter (99th percentile).
• Guardrail Enforcement: Guardrail validation runs synchronously on every rule save and suggestion display; no async bypass.
• Audit Immutability: OptimizationAuditEntry table has no UPDATE or DELETE permissions at the database level; append-only enforced.
• Audit Retention: Audit entries retained for minimum 10 years; no purge without compliance officer approval.
• Availability: Optimization engine 99.9% uptime; graceful degradation (show original codes) on failure.
• Encryption: All optimization data encrypted at rest (AES-256); TLS 1.2+ in transit.
• Scalability: Support 100 active PayerRules per organization; evaluate all rules per encounter within latency SLA.
• Compliance Testing: Guardrail enforcement covered by automated integration tests run on every deployment; deployment blocked if any guardrail test fails.

icApplication Overrides

How the four Payer Optimization AMI schemas turn into a live application: module-specific stack additions, override component bindings, the coding optimization pipeline, the payer rules engine integration with Coding / CDS, 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:

Payer Optimization override bindings P0

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

Coding optimization pipeline P1

The coding optimization pipeline runs after the clinician completes an encounter and before the charge is captured. It is triggered via CDS Hooks from the Coding / CDS module, with payer-specific rules applied as an additional CDS card overlay:

flowchart TD
  A[Clinician completes encounter] --> B{PayerOptimizationConfig
IsEnabledBool?}
  B -- No --> Z[No suggestions generated]
  B -- Yes --> C[Fetch active PayerRule set
for the encounter's payer]
  C --> D[Invoke CDS Hooks via
Coding / CDS module]
  D --> E[Evaluate base coding rules
ICD-10 / CPT / E/M levels]
  E --> F[Apply payer-specific
rule overlay]
  F --> G{Compliance validation:
IsCompliantBool?}
  G -- false --> H[Discard suggestion
log to internal audit]
  G -- true --> I{E/M downcode
candidate?}
  I -- Yes --> J[Create downcode
CodingOptimizationSuggestion]
  I -- No --> K[Create upcode/modifier
CodingOptimizationSuggestion]
  J --> L[Surface suggestion cards
to clinician]
  K --> L
  L --> M{Clinician accepts
or rejects?}
  M -- Accept --> N[Apply suggested code
set WasAcceptedBool = true
create OptimizationAuditEntry]
  M -- Reject --> O[Preserve original code
set WasAcceptedBool = false
create OptimizationAuditEntry]
    

The pipeline is synchronous from the clinician’s perspective (suggestions appear within 2 seconds per NFR-PO-001), but the compliance validation and audit entry creation are asynchronous to avoid blocking the clinical workflow. The IsEnabledBool check at step B is cached (1-hour TTL) to avoid a database round-trip on every encounter.

Payer rules engine — integration with Coding / CDS P0

Payer-specific rules are layered on top of the base coding rules from Coding / CDS. The integration uses CDS Hooks as the transport mechanism:

The payer rules evaluator (rules-evaluator.ts) runs in-process (not a separate microservice) to minimize latency. It evaluates the active PayerRule set for the encounter’s payer against the coding context and produces a list of payer-specific suggestions that are merged with the base CDS suggestions. The compliance validation step runs after the merge, discarding any suggestion where IsCompliantBool = false.

Versioning — worked example P0

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

CodingOptimizationSuggestion 1.0.0.20260301T120000Z — Initial schema. 5 business fields plus org-scoped audit columns. Component ic-ng21-payer-opt-1-suggestion-panel and ic-ng21-payer-opt-1-downcode-alert bind to coding-optimization-suggestion@1.0.0.* via the DI manifest.

CodingOptimizationSuggestion 1.1.0.20260615T093000Z — feature bump — Adds a single optional field, PayerRuleID (Guid, FK → PayerRule), to link the suggestion to the specific payer rule that triggered it. Per the IC change matrix:

Because the change is backward-compatible, the component tag stays ic-ng21-payer-opt-1-suggestion-panel. Existing UI consumers continue to bind coding-optimization-suggestion@1.x.* and ignore the new field. New UI surfaces that need payer-rule traceability bind coding-optimization-suggestion@^1.1.0. No new database is required (IC rule #13 only applies to break bumps).

CodingOptimizationSuggestion 2.0.0.20280101T120000Z — break bump (illustrative) — An illustrative future break bump: SuggestionReasonString200 is replaced by a structured set of fields (SuggestionCategoryString50, SuggestionDetailText, SupportingDocumentationRefString200). Per the IC change matrix this is change field type + add required fields — 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-payer-opt-2-suggestion-panel; consumers must re-bind. The old database stays live for the configured grace period (default 90 days) for rollback.

Payer Optimization environment details

Payer Optimization RBAC notes

• Opt-in gate. The opt-in dialog (ic-ng21-payer-opt-1-opt-in-dialog) only renders for users at level ≥ 80 (practice owner). Suggestion cards only render for users at level ≥ 60 (clinician). Audit log viewer only renders for users at level ≥ 70 (billing manager, compliance officer). Patient-level (10) users see nothing from this module.
• Guardrail enforcement. The three hard guardrails (no Medicare/Medicaid access reduction, no protected-category discrimination, no payer-margin patient visibility) are enforced at the rules-evaluator level and at the API layer. They cannot be overridden by any configuration or role level.

Cross-Module Dependencies

• Coding / CDS — authors and versions the coding rules (ICD-10, CPT, E/M level, modifier rules) invoked at charge-capture time via CDS Hooks. Payer Optimization is a consumer of CDS rules and adds payer-specific overlays; it does not author base coding rules.
• Scheduling — scheduling-side payer prioritization provides advisory input to the Scheduling module. The Scheduling module owns the appointment; Payer Optimization provides guidance only, subject to the three hard guardrails.
• RCM — denial data flows from RCM into the ROI dashboard; coding suggestions flow from Payer Optimization into the charge captured in RCM. Claim scrubbing and submission remain in RCM; Payer Optimization does not touch the claim.
• Clinical Documentation — the coding optimization engine reads clinical documentation (encounter notes, diagnoses, procedures) as its source of truth for suggestion generation. Documentation is global; suggestions are org-scoped.
• Data Model — all four Payer Optimization entities are org-scoped operational data following the operational-is-org-scoped pattern. Clinical data read by the engine is global following the clinical-facts-are-global pattern.

Cross-Module Links

• RCM — accepted suggestions update ClaimLine codes; scrub rules reference PayerRules
• Task Management — suggestion review tasks in clinician worklist
• eRx & EPCS — formulary tier data informs coding context