> ## 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.

# Compliance Reports

> On-demand timely filing, clean claim rate, modifier usage, and coding patterns reports across a configurable date range.

This page is the Compliance Reports hub, accessible at `/pm/compliance`.

## Overview

The Compliance Reports page provides four on-demand billing compliance reports for a user-selected date range. Reports are not pre-loaded; the user must click "Run Report" to trigger data fetch. Switching tabs resets the run state so each tab requires its own "Run Report" action. An "Export CSV" button becomes active after a report is run. The four tabs are: Timely Filing, Clean Claim Rate, Modifier Usage, and Coding Patterns. Users lacking the `pm.compliance.reports` permission see an access-denied alert instead of the report UI.

## Who it's for

Requires permission `pm.compliance.reports` (route guard: `PM_PERMISSIONS.COMPLIANCE_REPORTS`; component also checks `pm.compliance.reports` via `useHasPermission`).

## Before you start

* Claims data (`pm_claims`) and charges data (`pm_charges`) must exist for the selected date range.
* The default date range on page load is 90 days ending today.

## Steps

<Steps>
  <Step title="Open Compliance Reports">
    Navigate to `/pm/compliance`. The page loads with a 90-day default date range and the Timely Filing tab active. No report data is loaded until you click "Run Report."
  </Step>

  <Step title="Set the date range">
    Enter a "From" and "To" date in the date inputs. Changing either date resets the run state; you must click "Run Report" again after adjusting dates.
  </Step>

  <Step title="Select a report tab">
    Click one of the four tab triggers: "Timely Filing", "Clean Claim Rate", "Modifier Usage", or "Coding Patterns". Switching tabs also resets the run state for the new tab.
  </Step>

  <Step title="Run the report">
    Click "Run Report." The selected tab fetches data for the chosen date range and displays summary metric cards. An error alert is shown if the query fails.
  </Step>

  <Step title="Review results">
    * **Timely Filing**: shows Total Claims, Filed Within Window, and Rate (%).
    * **Clean Claim Rate**: shows Total Claims, Clean Claims, and Rate (%).
    * **Modifier Usage**: shows Total Charges, With Modifiers, Usage Rate (%), and a per-modifier breakdown table (modifier code, count, % of charges).
    * **Coding Patterns**: shows Total Charges, Unique Codes, Top Code, and a CPT code breakdown table (CPT code, count, % of charges) for up to 20 codes.
  </Step>

  <Step title="Export a report">
    Click "Export CSV" (active only after running a report) to export the current report data.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Timely filing calculation">
    The <Tooltip tip="Measures whether claims were submitted within a filing deadline window">timely filing</Tooltip> rate compares `service_date_from` to `created_at` on `pm_claims` records within the date range. The default filing deadline is 365 days. Claims where the interval exceeds the deadline are counted as outside the window.
  </Accordion>

  <Accordion title="Clean claim rate">
    The <Tooltip tip="Percentage of claims that passed validation and reached a billable status without requiring rework">clean claim rate</Tooltip> counts claims with status `submitted`, `accepted`, or `paid` as clean, divided by total claims created in the date range.
  </Accordion>

  <Accordion title="Modifier usage">
    Modifier usage queries `pm_charges` for the `modifiers` array column within the date range. It reports what fraction of charges carry at least one modifier and provides a per-modifier breakdown capped at 20 entries.
  </Accordion>

  <Accordion title="Coding patterns">
    Coding patterns queries `pm_charges.cpt_code` within the date range, counting occurrences of each CPT code and returning the top 20 by frequency.
  </Accordion>

  <Accordion title="Empty / no-data states">
    Each tab shows a placeholder empty state before "Run Report" is clicked. After running, if `totalClaims` or `totalCharges` is 0, a "No data for this report in the selected range" message is displayed.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Practice Management" icon="briefcase" href="/pm/overview">
    Overview of the Practice Management core.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/pm.tsx
  * src/cores/pm/pages/ComplianceReportsPage.tsx
  * src/cores/pm/hooks/useComplianceReports.ts
  * src/cores/pm/hooks/useCodingPatternsReport.ts
  * src/cores/pm/hooks/useModifierUsageReport.ts
  * src/platform/permissions/constants.ts
</Accordion>