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

# Significant Events

> The Significant Events screen at /rh/significant-events displays a filterable, real-time-updated list of significant events for the current organization and…

The Significant Events screen at `/rh/significant-events` displays a filterable, real-time-updated list of significant events for the current organization and allows staff to report new events via a dialog.

## Overview

The page loads significant events via `useSignificantEvents`, which queries the `rh_significant_events` table joined to `rh_significant_event_types` and a nested `rh_episodes` → `rh_residences` + `rh_resident_profiles` join, filtered by `organization_id` and ordered by `event_date` descending. The hook also subscribes to all events on `rh_significant_events` via `useRealtimeSubscription`; any change triggers a refetch. Separately, `useSignificantEventAlerts` subscribes to `INSERT` events on `rh_significant_events` and fires a Sonner toast: destructive (`toast.error`, 10 s) for `critical` or `major` severity, warning (`toast.warning`, 6 s) for others.

Filters available: free-text search (`description.ilike` / `incident_summary.ilike`), status (`draft`, `submitted`, `under_review`, `closed`), and severity (`minor`, `moderate`, `major`, `critical`). The **Report Event** button (shown to all users with `rh.dashboard.view`) opens `SignificantEventDialog`. The `RealtimeConnectionBadge` next to the heading reflects whether any real-time channels are active.

Individual event rows navigate to `/rh/significant-events/:id`. Creating a new event through the wizard requires `RH_PERMISSIONS.SIGNIFICANT_EVENTS_CREATE` at `/rh/significant-events/new`.

## Who it's for

No route-level `RequirePermission` beyond the outer `RHViewGuard` (`rh.dashboard.view`) on `/rh/significant-events`. Creating events via the wizard at `/rh/significant-events/new` requires `RH_PERMISSIONS.SIGNIFICANT_EVENTS_CREATE` (`rh.significant-events.create`).

## Before you start

* Hold `rh.dashboard.view` to access the RH module and view the significant events list.
* Hold `rh.significant-events.create` to access the new-event wizard at `/rh/significant-events/new`.
* Understand the status lifecycle and severity classifications for your organization (confirm with SME).

## Steps

<Steps>
  <Step title="Open Significant Events">
    Navigate to `/rh/significant-events`. The table loads all events ordered by most recent event date first.
  </Step>

  <Step title="Check real-time connection">
    The `RealtimeConnectionBadge` next to the heading shows whether live updates are active. New events trigger toast alerts automatically while the page is open.
  </Step>

  <Step title="Filter the list">
    Use the search input to match `description` or `incident_summary` text. Use the **Status** dropdown to filter by `draft`, `submitted`, `under_review`, or `closed`. Use the **Severity** dropdown to filter by `minor`, `moderate`, `major`, or `critical`.
  </Step>

  <Step title="Review an event">
    Click a row to navigate to `/rh/significant-events/:id` for the full event detail.
  </Step>

  <Step title="Report a new event (inline)">
    Click **Report Event** to open `SignificantEventDialog`. Complete the form and save. The table updates in real time.
  </Step>

  <Step title="Use the reporting wizard (if authorized)">
    Users with `rh.significant-events.create` may navigate to `/rh/significant-events/new` to use the `SignificantEventReportingWizardPage` for a guided submission flow.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Real-time updates and alerts">
    `useSignificantEvents` subscribes to all events (`INSERT`, `UPDATE`, `DELETE`) on `rh_significant_events` and refetches on any change. `useSignificantEventAlerts` subscribes separately to `INSERT` events and fires toast notifications: 10-second destructive toasts for `critical`/`major` severity, 6-second warning toasts for others. Both subscriptions are scoped to `organization_id` via `autoInjectOrgId`.
  </Accordion>

  <Accordion title="Status workflow">
    Observable status values: `draft`, `submitted`, `under_review`, `closed`. The transition rules and authorization requirements for each step should be confirmed with a subject-matter expert.
  </Accordion>

  <Accordion title="Severity levels">
    Observable severity values: `minor`, `moderate`, `major`, `critical`. The operational and regulatory meaning of each level should be confirmed with a subject-matter expert.
  </Accordion>

  <Accordion title="Event types">
    Events reference `rh_significant_event_types` via `event_type_id`. The specific event type taxonomy is stored in that table; the values are not enumerated in the UI code reviewed.
  </Accordion>

  <Accordion title="Positive UDS link">
    `UDSTestDetailPage` displays a prompt to navigate to `/rh/significant-events` when a UDS test result is `positive`, indicating operational coupling between UDS results and significant event reporting.
  </Accordion>
</AccordionGroup>

## Viewing an event

The Event Details page (`/rh/significant-events/:id`) loads a significant event by `id` from `rh_significant_events`, joined with the event type, the linked episode (including resident profile and residence), and the associated investigation and its corrective actions.

The page renders four primary sections: (1) **Event header** — event type name (or date fallback), formatted event date, severity badge, status badge; (2) **Event Details card** — episode number, residence name, and the user who reported the event; (3) **Description card** — the `event_details` free-text field; (4) **Event Summary card** — the `event_summary` field (shown only if present); (5) **Investigation card** — current investigation status with findings text; staff can start or edit an investigation via `InvestigationDialog`; (6) **Corrective Actions card** — list of actions linked to the investigation; the **Add Action** button is disabled until an investigation exists; actions are opened for editing via `InvestigationActionDialog`.

Status workflow buttons in the **Actions** card allow progressing a finding through `open → in_progress → resolved → closed`.

Permission required: `rh.dashboard.view` (applied to all RH routes via `RHViewGuard`). No additional inner permission gate on this detail route. Creating new significant events requires `rh.significant-events.create` (enforced on the `/rh/significant-events/new` route).

1. From **Recovery Housing → Significant Events**, click a row to navigate to `/rh/significant-events/<id>`.
2. Read the **Event Details** card (episode, residence, reporter) and the **Description** card. If an Event Summary is present, it appears below the description.
3. Click **Start Investigation** (or **Edit Investigation** if one already exists) to open the investigation dialog. Fill in or update the findings and save.
4. Once an investigation exists, click **Add Action** in the Corrective Actions card. Enter the action description and target completion date.
5. Click an existing corrective action row to open the action dialog and update its status. Use the workflow buttons (**Mark In Progress**, **Mark Resolved**, **Close Finding**) to advance the status.

**Key concepts:**

* **Significant event** — an incident or occurrence recorded against a resident episode that may require investigation and corrective follow-up.
* **Investigation** — a structured record of findings linked to a significant event; one investigation per event.
* **Corrective action** — a time-bound task linked to an investigation, tracked from `open` through `in_progress`, `resolved`, to `closed`.
* **Severity** — displayed as a badge; values are stored in `rh_significant_events.severity`.
* **Event type** — a lookup value from `rh_significant_event_types` that categorizes the nature of the event.

## 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/SignificantEventsPage.tsx
  * src/cores/rh/pages/SignificantEventDetailPage.tsx
  * src/cores/rh/hooks/useSignificantEvents.ts
  * src/cores/rh/hooks/useSignificantEventAlerts.ts
  * src/cores/rh/hooks/useSignificantEventDetail.ts
  * src/cores/rh/hooks/useInvestigation.ts
  * src/cores/rh/hooks/useInvestigationActions.ts
  * src/cores/rh/types/index.ts
</Accordion>