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

# Alumni

> Browse, filter, view, and create alumni records and engagement activities for program graduates in Recovery Housing.

The Alumni screen at `/rh/alumni` lists all alumni records for the current organization and provides tools to manage alumni engagements such as mentoring, volunteer work, and re-engagement milestones.

## Overview

The screen loads alumni records via `useAlumni`, which queries the `rh_alumni` table joined to `rh_resident_profiles` and `rh_episodes`, filtered by `organization_id` and ordered by `program_completion_date` descending. A search field filters on alumni `id`; a status selector filters by status values `all`, `active`, `inactive`, `lost_contact`, and `deceased`. A second card below the directory table shows Alumni Engagements — records of mentoring, volunteer work, and re-engagement milestones loaded by `useAlumniEngagements`. Users with `rh.residents.edit` permission see an Add Engagement button in that section.

## Who it's for

No route-level `RequirePermission` beyond the outer `RHViewGuard`. The outer guard requires `RH_PERMISSIONS.DASHBOARD_VIEW` (`rh.dashboard.view`). The Add Engagement button is gated by `PermissionGate` with permission `rh.residents.edit`.

## Before you start

* Hold `rh.dashboard.view` to access the RH module.
* Hold `rh.residents.edit` to add engagement records.

## Steps

<Steps>
  <Step title="Open the Alumni list">
    Navigate to `/rh/alumni`. The Alumni directory card loads with a count of records matching the current filter.
  </Step>

  <Step title="Filter alumni">
    Use the search field to filter by alumni record ID, or use the Status dropdown to narrow by `Active`, `Inactive`, `Lost Contact`, or `Deceased`.
  </Step>

  <Step title="Add an alumni record">
    Click **Add Alumni** in the page header. The `AlumniDialog` opens. Complete the form and save.
  </Step>

  <Step title="View engagement history">
    Scroll to the **Alumni Engagements** card. The `AlumniEngagementsTable` lists all engagement records across the organization.
  </Step>

  <Step title="Add an engagement (requires rh.residents.edit)">
    Click **Add Engagement** in the Alumni Engagements card header. The `AlumniEngagementDialog` opens. Complete the form and save.
  </Step>

  <Step title="Open an alumni record">
    Click a row in the Alumni directory table to navigate to `/rh/alumni/:id` for full detail.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Empty state">
    When no alumni records match the current filter, the Alumni directory card shows an **Add First Alumni** action button.
  </Accordion>

  <Accordion title="Loading state">
    While `useAlumni` is fetching, the Alumni directory card shows five skeleton rows. The record count area also renders a skeleton placeholder.
  </Accordion>
</AccordionGroup>

## Viewing an alumni record

The Alumni Details screen at `/rh/alumni/:id` shows the full record for one alumni, including program completion details, contact consent and contact information, success story status, an engagement breakdown chart, and a complete engagement history table.

The page reads the URL parameter `:id` and loads the alumni record via `useAlumniDetail`. The breadcrumb is set to `Alumni #<first 8 chars of id>`. The header badge shows `Active Alumni` (green) when `alumni.is_active` is true, and `Inactive` (secondary) otherwise. Program completion date is formatted as `MMMM d, yyyy`. Contact information (`contact_email`, `contact_phone`, `contact_address`) is rendered only when `contact_consent` is true. The success story card shows an "Approved" badge when `success_story_approved` is true, a "Pending Approval" badge with a no-op approve button when a story is present but not yet approved, or a placeholder message when no story exists. The `AlumniEngagementChart` renders when engagement data is present, aggregating records by `engagement_type`. A full `AlumniEngagementsTable` filtered by `alumniId` shows the complete engagement history. If the record is not found or an error occurs, a "Alumni record not found or an error occurred." message is displayed.

No route-level `RequirePermission` beyond the outer `RHViewGuard`, which requires `rh.dashboard.view`. The alumni record must exist; navigating to a non-existent ID shows an error card.

<Steps>
  <Step title="Open an alumni record">
    From `/rh/alumni`, click a row in the Alumni directory table to navigate to `/rh/alumni/:id`.
  </Step>

  <Step title="Review alumni information">
    The **Alumni Information** card shows Completion Type, Program Completion Date, Episode ID, and Contact Consent. Contact details (email, phone, address) are visible only when `contact_consent` is true.
  </Step>

  <Step title="Review the success story">
    The **Success Story** card shows approval status. An approved story is displayed with a green badge. A pending story shows a "Pending Approval" badge and an **Approve Story** button (currently a placeholder — see SME note).
  </Step>

  <Step title="View engagement breakdown">
    If engagement records exist, the `AlumniEngagementChart` renders a breakdown by engagement type.
  </Step>

  <Step title="Edit the record">
    Click **Edit** to navigate to `/rh/alumni/:id/edit`.
  </Step>

  <Step title="Add an engagement">
    Click **Add Engagement** to navigate to `/rh/alumni/:id/engagements/new`.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Error / not-found state">
    If `useAlumniDetail` returns an error or no data, the page renders a card with the message "Alumni record not found or an error occurred."
  </Accordion>

  <Accordion title="Loading state">
    While data is fetching, two skeleton placeholders replace the header and detail card.
  </Accordion>

  <Accordion title="Contact consent gate">
    Contact email, phone, and address fields are only rendered when `alumni.contact_consent` is `true`. This is enforced in the component JSX — not via a separate permission check.
  </Accordion>
</AccordionGroup>

## Creating an alumni record

The path `/rh/alumni/new` is not registered as a route in `src/routes/rh.tsx`. Alumni record creation is handled through an inline dialog on the `/rh/alumni` list page, not via a dedicated route. Visiting `/rh/alumni/new` directly will render the platform's Not Found page.

Before you start: navigate to `/rh/alumni` and use the **Add Alumni** button to create a new alumni record.

<Steps>
  <Step title="Navigate to the Alumni list">
    Go to `/rh/alumni`. The alumni directory for your organization is displayed.
  </Step>

  <Step title="Open the Add Alumni dialog">
    Click **Add Alumni** in the page header. The alumni creation dialog opens.
  </Step>

  <Step title="Complete and save the form">
    Fill in the alumni record details and submit the form. The dialog closes on success and the alumni list refreshes.
  </Step>
</Steps>

## 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/AlumniPage.tsx
  * src/cores/rh/pages/AlumniDetailPage.tsx
  * src/cores/rh/hooks/useAlumni.ts
  * src/cores/rh/components/forms/AlumniDialog.tsx
</Accordion>