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

# Population Health

> The /cl/population-health route redirects to /cl/population-health/care-gaps, the Care Gap Work List. Sub-routes include dashboards, quality measures, and clin…

The Population Health section of the Clinical core is accessible at `/cl/population-health`. This path redirects immediately to `/cl/population-health/care-gaps`. Sub-routes provide access to the Care Gap Work List, Population Dashboard, Quality Measures, Clinician Panel, and Supervisor Panels.

## Overview

`/cl/population-health` is a **redirect-only route** that navigates to `/cl/population-health/care-gaps`. The Population Health sub-section contains five screens:

| Sub-route                                | Component                 | Permission                     |
| ---------------------------------------- | ------------------------- | ------------------------------ |
| `/cl/population-health/care-gaps`        | `CareGapWorkListPage`     | `cl.care-gaps.view`            |
| `/cl/population-health/dashboards`       | `PopulationDashboardPage` | `cl.population-dashboard.view` |
| `/cl/population-health/quality-measures` | `QualityMeasuresPage`     | `cl.quality-measures.view`     |
| `/cl/population-health/my-panel`         | `ClinicianPanelPage`      | `cl.care-gaps.view`            |
| `/cl/population-health/panels`           | `SupervisorPanelsPage`    | `cl.population-dashboard.view` |

The Population Dashboard (`/dashboards`) renders three tabs — Risk Distribution, Care Gap Summary, and Outcome Trends — plus four summary stat cards (Total Stratified, Open Care Gaps, High/Critical Risk, Gap Types). Values below 5 are suppressed in displayed counts. An optional site filter appears when the organization has more than one site.

## Who it's for

Each sub-route has its own `RequirePermission` or `PermissionGate` wrapper. The parent `/cl/population-health` redirect itself has no permission gate.

## Before you start

* You need the permission for the specific sub-route you intend to access (see table above).
* Risk stratification and care gap data must be populated by the risk engine and care gap identification process for dashboard charts to display non-empty states.

## Steps

<Steps>
  <Step title="Navigate to Population Health">
    Go to `/cl/population-health`. The router redirects to `/cl/population-health/care-gaps`.
  </Step>

  <Step title="Review the Care Gap Work List">
    The Care Gap Work List displays open care gaps for the organization. Filter by status, priority, gap type, or site. Open a gap detail sheet or close a gap using the available actions.
  </Step>

  <Step title="View the Population Dashboard">
    Navigate to `/cl/population-health/dashboards` for aggregate charts. Use the Risk Distribution tab to see counts by risk tier. Use the Care Gap Summary tab for a bar chart of open gaps by type. The Outcome Trends tab is not yet populated (Phase 4 deliverable).
  </Step>

  <Step title="Export VBP data (if permitted)">
    On the Population Dashboard, users with `cl.quality-measures.export` permission can click "Export for VBP" to download a CSV from the `cl-vbp-export` edge function.
  </Step>

  <Step title="Review your clinician panel">
    Navigate to `/cl/population-health/my-panel` to see your assigned patients and their care gap status.
  </Step>
</Steps>

## Key concepts

| Term                     | Meaning                                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Care Gap                 | An identified gap between a patient's current care status and a clinical target                                       |
| Risk Tier                | Patient risk classification: `critical`, `high`, `medium`, or `low`                                                   |
| Small-cell suppression   | Counts below 5 are masked in displayed values (`maskSmallCell`) to protect patient privacy                            |
| VBP export               | CSV export of population health data for Value-Based Payment reporting via the `cl-vbp-export` Supabase edge function |
| `usePopulationDashboard` | Hook fetching aggregate risk distribution, care gap summary, and outcome trend data                                   |

## Related

<Columns cols={2}>
  <Card title="Clinical" icon="stethoscope" href="/cl/overview">
    Clinical core overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</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/cl.tsx
  * src/cores/cl/pages/population-health/PopulationDashboardPage.tsx
  * src/cores/cl/pages/population-health/CareGapWorkListPage.tsx
  * src/cores/cl/hooks/usePopulationDashboard.ts
  * src/cores/cl/hooks/useCareGapList.ts
  * src/cores/cl/types/care-gaps.ts
  * src/cores/cl/types/risk-stratifications.ts
</Accordion>