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

> Aggregate population health charts showing risk distribution, open care gaps, and outcome trends with site filtering and VBP export.

The Population Dashboard displays aggregate population health metrics for the organization at the in-app route `/cl/population-health/dashboards`.

## Overview

The Population Dashboard is gated by `cl.population-dashboard.view` via a `PermissionGate`. The page header includes an "Export for VBP" button (requires `cl.quality-measures.export`) that calls the `cl-vbp-export` Supabase edge function and downloads a dated CSV. A site filter dropdown appears when the organization has more than one site, allowing data to be scoped to a single site. Four summary cards display total stratified patients, open care gaps, combined high/critical risk count, and the number of distinct gap types. A three-tab layout contains: "Risk Distribution" (bar chart of patient counts by risk tier with small-cell suppression), "Care Gap Summary" (bar chart of open gap counts by gap type), and "Outcome Trends" (currently an empty state shell with a ghosted line chart for PHQ-9 and GAD-7 averages).

## Who it's for

Requires permission `cl.population-dashboard.view`. Export requires the additional permission `cl.quality-measures.export`.

## Before you start

* Permission `cl.population-dashboard.view` must be granted.
* Risk stratification and care gap data must have been processed for the organization for charts to display data rather than empty states.

## Steps

<Steps>
  <Step title="Open the dashboard">
    Navigate to `/cl/population-health/dashboards`. The four summary cards load first with skeleton states while data is fetched.
  </Step>

  <Step title="Filter by site (if applicable)">
    If the organization has more than one site, use the site dropdown to scope the dashboard to a single site or view all sites.
  </Step>

  <Step title="Review Risk Distribution">
    Click the "Risk Distribution" tab to view a bar chart of patient counts by risk tier. Bars with counts below 5 are suppressed and displayed as a masked value.
  </Step>

  <Step title="Review Care Gap Summary">
    Click the "Care Gap Summary" tab to view a bar chart of open care gap counts by gap type.
  </Step>

  <Step title="Review Outcome Trends">
    Click the "Outcome Trends" tab. If sufficient longitudinal data has been collected, trend lines for PHQ-9 and GAD-7 averages are shown; otherwise an empty state is displayed.
  </Step>

  <Step title="Export VBP data (if permitted)">
    Click "Export for VBP" (requires `cl.quality-measures.export`) to download a CSV from the `cl-vbp-export` edge function. The file is named `vbp-export-{date}.csv`.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Risk tier values">
    `critical`, `high`, `medium`, `low` — from `RISK_TIER_LABELS` in `src/cores/cl/types/risk-stratifications.ts`.
  </Accordion>

  <Accordion title="Small-cell suppression">
    The `maskSmallCell` utility suppresses patient counts below 5 in all chart tooltips and summary cards to protect patient privacy.
  </Accordion>

  <Accordion title="Empty and error states">
    Each chart tab renders an `EmptyState` component when the data array is empty or all counts are zero. A card-level error state is shown when the data fetch fails.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Clinical" icon="stethoscope" href="/cl/overview">
    Overview of the Clinical 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/cl.tsx
  * src/cores/cl/pages/population-health/PopulationDashboardPage.tsx
  * src/cores/cl/types/quality-measure-periods.ts
</Accordion>