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

> Recovery Housing module overview showing census stats, bed availability, daily operations, discharge planning, compliance, and outcomes widgets.

The Recovery Housing Dashboard (`RHOverview`) is the primary landing page for the RH module, accessible at `/rh/dashboard` (the root `/rh` redirects here).

## Overview

The dashboard loads live stats from `useDashboardStats` and renders a `QuickActionsSection` (editable, module `rh`, up to 6 module actions and 3 global), four summary `StatCard` tiles, and five widget sections. Widgets load lazily via `Suspense` with skeleton fallbacks.

**Stat cards** (linked to sub-routes):

* **Total Residences** — count of active residences (`rh_residences`)
* **Bed Capacity** — `occupied_beds / total_beds` with occupancy rate percentage
* **Active Episodes** — count of episodes with `status = 'admitted'`
* **Waitlist** — count of episodes with `status = 'waitlisted'`

**Widget sections** (loaded lazily):

* Census & Beds: `CensusSummaryWidget`, `BedCensusWidget`, `BedAvailabilityWidget`, `WaitlistWidget`, `RecentAdmissionsWidget`, `LicenseAlertsWidget`
* Daily Operations: `AttendanceComplianceWidget`, `ChoreCompletionWidget`, `CurfewComplianceWidget`
* Discharge Planning: `UpcomingDischargesWidget`, `DischargeReadinessWidget`, `FollowUpsDueWidget`, `ReferralSuccessWidget`
* Compliance & Staff Operations: `ComplianceStatusWidget`, `ComplianceDeadlinesWidget`, `TrainingDueWidget`, `UpcomingAuditsWidget`
* Outcomes & Alumni: `OutcomeSummaryWidget`, `SobrietyRateWidget`, `CompletionRateWidget`, `AlumniEngagementWidget`, `ReportsDueWidget`

## Who it's for

This route is protected by `RH_PERMISSIONS.DASHBOARD_VIEW` (`rh.dashboard.view`) via `RHViewGuard`. No additional per-route permission gate.

## Before you start

* Your account must hold `rh.dashboard.view`.
* An organization context must be active; all stat queries filter by `organization_id`.

## Steps

<Steps>
  <Step title="Navigate to the dashboard">
    Go to `/rh` or `/rh/dashboard`. The stat cards load immediately from `useDashboardStats`; widget skeletons display while lazy components load.
  </Step>

  <Step title="Review summary stats">
    The four stat cards at the top show Total Residences, Bed Capacity (with occupancy rate), Active Episodes, and Waitlist count. Click a card to navigate to the corresponding sub-section.
  </Step>

  <Step title="Use Quick Actions">
    The `QuickActionsSection` below the header provides up to 6 module-specific quick actions and 3 global actions. Actions are editable by the current organization.
  </Step>

  <Step title="Review widget sections">
    Scroll through the five widget sections to see daily operations status, discharge planning readiness, compliance standing, and outcomes metrics. Each widget queries data scoped to the current organization.
  </Step>
</Steps>

## Bed Census widget

The `BedCensusWidget` shows live occupancy for your organization's active residences. It reads the same data as the [RH Bed Board](/rh/bed-board), so the numbers you see on the dashboard match what's on the board.

**What it shows:**

* **Occupancy Rate** — occupied beds as a percentage of total active beds.
* **Occupied Beds** — beds with `status = 'occupied'`.
* **Available Beds** — beds with `status = 'available'`.
* **Total Capacity** — count of non-deleted beds across active residences.
* **View bed board →** — link to `/rh/bed-board` for the full grid.

**How it updates:**

* Polls every 30 seconds via React Query.
* Subscribes to realtime updates on `rh_beds` and refetches on any insert, update, or delete in your organization.
* A connection badge in the widget header shows realtime status.

**Scoping rules** (match `useBedBoard`):

* Residences are filtered to `status = 'active'` in the current organization.
* Beds are filtered to non-deleted rows (`deleted_at IS NULL`) in those residences.

If the widget shows 0 across all counts, confirm that the current organization has at least one active residence with non-deleted beds.

## Key concepts

| Term                    | Source                                       | Meaning                                                             |
| ----------------------- | -------------------------------------------- | ------------------------------------------------------------------- |
| Occupancy rate          | `useDashboardStats`, `fetchBedCensusSummary` | `(occupied_beds / total_beds) * 100`; 0 if no beds                  |
| Active episodes         | `rh_episodes.status = 'admitted'`            | Currently housed residents                                          |
| Waitlist                | `rh_episodes.status = 'waitlisted'`          | Pending applicants                                                  |
| QuickActionsSection     | Platform component                           | Configurable shortcut tiles per organization                        |
| Bed Census widget scope | `fetchBedCensusSummary`                      | Active residences + non-deleted beds, filtered by `organization_id` |

## 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/RHOverview\.tsx
  * src/cores/rh/hooks/useDashboardStats.ts
  * src/platform/dashboard/widgets/BedCensusWidget.tsx
  * src/platform/census/fetchBedCensusSummary.ts
</Accordion>