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

# Recovery Housing Reports

> Browse, search, filter, define, run, and view RH reports including census, outcomes, compliance, and grant types.

The Reports screen is at `/rh/reports` and renders the `ReportsPage` component. It loads all report definitions for the current organization from `useReportDefinitions` and provides search, type filtering, summary metrics, and actions to define new reports or run ad-hoc reports.

## Overview

Three summary cards display aggregated metrics: **Total Reports** (all report definitions), **Scheduled** (count of `is_scheduled: true` records), and **Active** (count of `is_active: true` records). All counts are scoped to the current organization via `useOrganization`.

A Filters card allows search by `report_name` and type filtering by `report_type`. The available types are: `census`, `program_completion`, `outcomes`, `discharge`, `compliance`, `grant`, `alumni`, and `custom`.

The `ReportDefinitionsTable` renders the filtered list. Clicking a row navigates to `/rh/reports/:id`.

Two header buttons are present:

* **Run Report** — links to `/rh/reports/create`.
* **New Report Definition** — opens `ReportDefinitionDialog` inline.

## Who it's for

The outer `RHViewGuard` requires `RH_PERMISSIONS.DASHBOARD_VIEW` (`rh.dashboard.view`). The `/rh/reports` route carries no additional permission gate beyond the guard.

## Before you start

* Hold the `rh.dashboard.view` permission to access any RH route.

## Steps

<Steps>
  <Step title="Navigate to Reports">
    Go to `/rh/reports`. The page loads and displays summary metric cards and the full list of report definitions.
  </Step>

  <Step title="Filter the list (optional)">
    Enter text in the search box to filter by report name. Use the Report Type dropdown to filter by type.
  </Step>

  <Step title="Open a report definition">
    Click a row in the `ReportDefinitionsTable` to navigate to `/rh/reports/:id` and view the full definition.
  </Step>

  <Step title="Create a new report definition (optional)">
    Click "New Report Definition". The `ReportDefinitionDialog` opens inline. Fill in the required fields and submit.
  </Step>

  <Step title="Run an ad-hoc report (optional)">
    Click "Run Report" to navigate to `/rh/reports/create`.
  </Step>
</Steps>

## Key concepts

| Term               | Meaning                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Report definition  | A saved configuration for a report, stored as a record accessible via `useReportDefinitions`.                                  |
| `report_type`      | Category of the report: `census`, `program_completion`, `outcomes`, `discharge`, `compliance`, `grant`, `alumni`, or `custom`. |
| `is_scheduled`     | Indicates the report is configured to run automatically.                                                                       |
| `is_active`        | Indicates the report definition is currently active.                                                                           |
| `recipient_emails` | List of email addresses that receive scheduled report output.                                                                  |

## Viewing a report

The Report Details screen is at `/rh/reports/:id` and renders the `ReportDetailPage` component. It displays a single report definition record from the data returned by `useReportDefinitionDetail` and exposes Edit, Export, and Run Now actions.

The page resolves the report by `:id` via `useReportDefinitionDetail`. The breadcrumb label is set dynamically from `report_name`. Three action buttons are shown in the header:

* **Edit** — navigates to `/rh/reports/:id/edit`.
* **Export** — stub (see SME note above).
* **Run Now** — stub (see SME note above).

The main layout uses two sections:

* **Report Configuration card** (2/3 width on md+) — displays `report_type`, active/inactive status badge, `created_by_profile.full_name`, notes, and `report_config` as formatted JSON.
* **Schedule and Recipients cards** (1/3 width on md+) — Schedule shows `schedule_frequency` when `is_scheduled` is true; Recipients lists each email in `recipient_emails`.

A Report Preview card at the bottom displays a placeholder prompting the user to run the report.

The outer `RHViewGuard` requires `rh.dashboard.view`; no additional gate exists on this route. A report definition with the target ID must exist and belong to the current organization.

<Steps>
  <Step title="Navigate to Reports">
    Go to `/rh/reports`. The Reports Hub lists all report definitions for the current organization.
  </Step>

  <Step title="Open a report definition">
    Click a row in the `ReportDefinitionsTable`. The browser navigates to `/rh/reports/:id`.
  </Step>

  <Step title="Review report configuration">
    The Report Configuration card shows the report type, active status, creator, notes, and raw `report_config` JSON.
  </Step>

  <Step title="Review schedule and recipients">
    The Schedule card shows the frequency if `is_scheduled` is true. The Recipients card lists configured email addresses.
  </Step>

  <Step title="Edit the report definition (optional)">
    Click "Edit" to navigate to `/rh/reports/:id/edit`.
  </Step>

  <Step title="Export or run the report (pending)">
    The Export and Run Now buttons are present in the UI but their actions are not yet fully wired (see SME note above).
  </Step>
</Steps>

### Key concepts

| Term                 | Meaning                                                                                |
| -------------------- | -------------------------------------------------------------------------------------- |
| `report_name`        | Display name of the report definition.                                                 |
| `report_type`        | Category of the report (e.g., `census`, `outcomes`, `compliance`, `grant`).            |
| `is_active`          | Whether the report definition is active.                                               |
| `is_scheduled`       | Whether the report runs on an automatic schedule.                                      |
| `schedule_frequency` | Frequency of automatic runs when `is_scheduled` is true (SME: confirm allowed values). |
| `recipient_emails`   | List of email addresses that receive scheduled report outputs.                         |
| `report_config`      | JSON configuration object for the report (SME: confirm structure).                     |

## Creating a report

The New Report screen provides a form to create a new report definition for Recovery Housing, accessible at `/rh/reports/new`.

The New Report screen renders a single `Card` containing `ReportDefinitionForm`, a tabbed form with **Basic Info** and **Schedule** tabs. After clicking **Create Report**, the form calls `createReport` and navigates to `/rh/reports`. No wizard shell is used; this is a flat form. No additional permission beyond the outer `rh.dashboard.view` guard is required. Identify the report type and whether you want the report to run on a schedule before opening the form.

<Steps>
  <Step title="Fill in Basic Info">
    On the **Basic Info** tab, enter the **Report Name** (required) and select a **Report Type**: Census, Program Completion, Outcomes, Discharge, Compliance, Grant, Alumni, or Custom. Optionally add **Notes**. The **Active** toggle (default: on) controls whether the report is available for use.
  </Step>

  <Step title="Configure Schedule (optional)">
    Switch to the **Schedule** tab. Toggle **Enable Scheduling** to reveal scheduling options. Select a **Frequency**: Daily, Weekly, Monthly, Quarterly, or Annual. For weekly schedules, select a **Day of Week**. For monthly, quarterly, or annual schedules, enter a **Day of Month** (1–31). Enter comma-separated **Recipient** email addresses to receive the scheduled report.
  </Step>

  <Step title="Submit">
    Click **Create Report**. On success the page navigates to `/rh/reports`. On error, the mutation handles the error response.
  </Step>
</Steps>

### Key concepts

| Term        | Code identifier      | Notes                                             |
| ----------- | -------------------- | ------------------------------------------------- |
| Report Name | `report_name`        | Required; free-text identifier                    |
| Report Type | `report_type`        | Enumerated category                               |
| Active      | `is_active`          | Controls report availability                      |
| Scheduling  | `is_scheduled`       | Enables automatic report generation               |
| Frequency   | `schedule_frequency` | Recurrence cadence when scheduling is enabled     |
| Recipients  | `recipient_emails`   | Comma-separated email list for scheduled delivery |

## Related

<Columns cols={2}>
  <Card title="Recovery Housing" icon="house" href="/rh/references">
    Recovery Housing references and overview.
  </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/rh.tsx
  * src/cores/rh/pages/ReportsPage.tsx
  * src/cores/rh/pages/ReportDetailPage.tsx
  * src/cores/rh/pages/ReportCreatePage.tsx
  * src/cores/rh/hooks/useReportDefinitions.ts
  * src/cores/rh/hooks/useReportDefinitionDetail.ts
  * src/cores/rh/components/forms/ReportDefinitionForm.tsx
</Accordion>