> ## 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 — Engineering snapshot > Engineering snapshot (schema, route map, integration points) for the Recovery Housing module. Full user docs live at /rh/overview. > This file is an **engineering snapshot** (schema, route map, integration points) intended for developers working in `src/cores/rh/`. Published end-user / admin documentation lives in the Mintlify `docs/rh/` surface (slug `/rh/overview`). ## Overview The Recovery Housing module manages the full **episode-based** resident lifecycle for sober-living, recovery-housing, psychiatric-residential, and inpatient settings. It supports intake → admitted → on\_hold → discharged transitions, 120-day phase progression, daily operations, compliance & audit, discharge planning, and outcomes / alumni tracking. The `rh_episodes` status field drives the core state machine (`rh_update_episode_status`): ```mermaid theme={null} stateDiagram-v2 [*] --> referred referred --> waitlisted referred --> admitted waitlisted --> admitted admitted --> on_hold on_hold --> admitted admitted --> discharged on_hold --> discharged discharged --> [*] ``` ## Spec status | Spec | Status | | -------------------------------------------------- | ---------------------------------------- | | RH-01 Census, Beds & Episodes | ✅ Complete | | RH-01.1 Bed Board & Facility Types | ✅ Complete | | RH-02 Programs & Phases (120-Day Model) | ✅ Complete | | RH-03 Safety Events, Incidents & Compliance | ✅ Complete | | RH-04 Participation, Attendance & Daily Operations | ✅ Complete | | RH-05 Discharge Planning | ✅ Complete | | RH-06 Compliance & Staff Operations | ✅ Complete | | RH-07 Outcomes, Alumni & Reporting | ✅ Complete | | RH-08 Advanced Analytics & Predictive Insights | 📝 Deferred (Phase 2; needs ≥ 6 mo data) | | RH-09 Resident Grievance Management | 📋 Spec | | RH-10 Fire & Life Safety Compliance | 📋 Spec | | RH-11 NARR Level & AzRHA Certification | 📋 Spec | | RH-04 EN-4 UDS / 42 CFR Part 2 access controls | 📋 Spec — **HIGH** priority | See [`specs/rh/summaries/DEFERRED-PHASES-SUMMARY.md`](https://github.com/Encore-OS/encoreos/blob/development/specs/rh/summaries/DEFERRED-PHASES-SUMMARY.md) for the complete deferred / planned backlog and [`specs/rh/reports/rh-deep-review-20260418.md`](https://github.com/Encore-OS/encoreos/blob/development/specs/rh/reports/rh-deep-review-20260418.md) for the latest deep review. ## End-user / admin documentation Published Mintlify surface (`docs/rh/`, slug `/rh/overview`): * **User guides:** Census & Operations · Programs & Phases · Safety & Compliance · Daily Operations · Discharge Planning · Compliance & Staff Operations · Outcomes & Alumni * **Admin guides:** property setup · room configuration · program management · RH settings · compliance setup · audit setup · outcome indicators setup · report definitions setup * **Wizards:** admission (as-built RH-UX-00); program creation, significant event reporting, discharge planning, compliance setup, outcomes assessment, grievance filing (planned reference) * **Planned (spec-only):** RH-08, RH-09, RH-10, RH-11, RH-04 EN-4 > Within `docs/rh/`, this engineering snapshot plus `database-tables.md` and `references.md` are engineering / regulatory references; the remaining `*-user-guide.md` / `*-admin-guide.md` pages are the user-facing guides. ## Routes `src/routes/rh.tsx` defines 53 routes. Top-level groups (URL prefix `/rh`): | Area | Routes | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Dashboard / overview | `/rh`, `/rh/dashboard`, `/rh/forms` | | Census & Operations | `/rh/bed-board`, `/rh/residences`, `/rh/residences/:id`, `/rh/episodes`, `/rh/episodes/:id`, `/rh/admissions/new` | | Programs & Phases | `/rh/programs`, `/rh/programs/:id` | | Safety & Compliance | `/rh/significant-events`, `/rh/significant-events/:id`, `/rh/uds-tests`, `/rh/uds-tests/:id`, `/rh/passes`, `/rh/passes/:id`, `/rh/med-audits`, `/rh/med-audits/:id` | | Daily Operations | `/rh/schedule-templates`, `/rh/attendance`, `/rh/chores`, `/rh/transport`, `/rh/curfew-checks` | | Discharge Planning | `/rh/discharge-plans`, `/rh/discharge-plans/:id`, `/rh/referrals`, `/rh/referrals/:id`, `/rh/follow-ups`, `/rh/follow-ups/:id`, `/rh/discharge-documents` | | Compliance & Staff Ops | `/rh/compliance`, `/rh/compliance/requirements`, `/rh/compliance/requirements/:id`, `/rh/compliance/checklists`, `/rh/staff-operations/assignments`, `/rh/staff-operations/training`, `/rh/staff-operations/shift-notes`, `/rh/staff-operations/shift-notes/:id`, `/rh/audits`, `/rh/audits/:id`, `/rh/audits/:auditId/findings/:id` | | Outcomes & Alumni | `/rh/outcomes`, `/rh/outcomes/assessments`, `/rh/outcomes/assessments/:id`, `/rh/outcomes/indicators`, `/rh/alumni`, `/rh/alumni/:id`, `/rh/reports`, `/rh/reports/new`, `/rh/reports/:id` | | Settings | `/rh/settings` (gated by `RH_PERMISSIONS.SETTINGS_ADMIN`) | > ⚠️ Only `/rh/settings` is wrapped in `` today. The remaining \~52 routes rely on RLS + nav gating only. A route-level permission sweep is filed as a HIGH-MEDIUM backlog item in `DEFERRED-PHASES-SUMMARY.md`. ## Data model (key entities only) > Engineering DB cheat sheet: [`docs/rh/database-tables.md`](/rh/database-tables). ERD: [`docs/database/erd/RH_ERD.md`](/database/erd/RH_ERD). **Census, residences, beds:** * `rh_residences` — properties / facilities (with `facility_type`: `recovery_housing` POS 55, `psychiatric_residential` POS 56, `inpatient_unit` POS 51) * `rh_beds` — bed inventory (with optional `unit_label` for inpatient grouping) * `rh_census_snapshots` — census timeseries **Resident lifecycle (episode-based):** * `rh_resident_profiles` — long-lived demographic record * `rh_episodes` — one row per admission; `bed_id`, status, admission/discharge dates * `rh_episode_payment_status` — FA balance cache (populated by `fa-episode-balance` edge function) * `rh_eligibility_checklists`, `rh_resident_agreements` — gating + agreements **Programs & phases (RH-02):** * `rh_programs`, `rh_program_phases`, `rh_phase_milestones`, `rh_phase_privileges` * `rh_episode_programs`, `rh_episode_phases`, `rh_milestone_completions` **Safety, incidents, UDS, passes (RH-03):** * `rh_significant_event_types`, `rh_significant_events`, `rh_significant_event_investigations`, `rh_significant_event_actions` * `rh_uds_random_schedule`, `rh_uds_tests` ⚠️ **42 CFR Part 2 protected** * `rh_passes` * `rh_med_storage_audits` **Daily operations (RH-04):** * `rh_schedule_templates`, `rh_schedule_instances`, `rh_attendance_records` * `rh_chore_assignments`, `rh_transport_requests`, `rh_curfew_checks` * `rh_participation_metrics` **Discharge (RH-05):** * `rh_discharge_plans`, `rh_discharge_checklists`, `rh_discharge_documents` * `rh_referrals` * `rh_follow_up_schedules`, `rh_follow_up_contacts` **Compliance & staff ops (RH-06):** * `rh_compliance_requirements`, `rh_compliance_checklists` * `rh_staff_assignments`, `rh_staff_trainings`, `rh_shift_notes` * `rh_audit_schedules`, `rh_audit_findings` **Outcomes & alumni (RH-07):** * `rh_outcome_indicators`, `rh_outcome_checkpoints`, `rh_outcome_assessments`, `rh_outcome_measurements` * `rh_alumni`, `rh_alumni_engagement` * `rh_report_definitions` **Module config:** * `rh_module_settings` — one row per organisation (defaults, follow-up cadence, notification toggles, sender address) **Helper functions (SECURITY DEFINER):** * `rh_update_episode_status(p_episode_id, p_new_status, p_user_id)` — drives the episode state machine * `rh_assign_bed_to_episode(p_episode_id, p_bed_id, p_user_id)` — validates + assigns + emits event * `rh_get_residence_census(p_residence_id, p_as_of)` — live census * `rh_trigger_invoice_creation(p_agreement_id)` — agreement → FA invoice request **Domain event triggers (since 2026-03-20):** * `rh_resident_admitted`, `rh_resident_discharged`, `rh_phase_advanced` → persisted to `fw_domain_events`. Consumers in FA / PM / HR are **not yet wired** (see deep-review actions tracker). ## Status enum reference | Entity | Statuses | | | | -------------------------------------------------------- | ----------------------------------------------------------- | -------------------- | ----------- | | Episode (`rh_episodes.status`) | `referred → waitlisted → admitted → on_hold → discharged` | | | | Bed (`rh_beds.status`) | `available · occupied · reserved · maintenance` | | | | Significant event (`rh_significant_events.status`) | `draft → submitted → under_review → closed` (+ `cancelled`) | | | | Discharge plan (`rh_discharge_plans.status`) | \`not\_started → in\_progress → ready → completed | cancelled\` | | | Referral (`rh_referrals.status`) | \`draft → sent → accepted | declined → completed | cancelled\` | | Compliance checklist (`rh_compliance_checklists.status`) | `pending → completed → verified` (+ `non_compliant`) | | | | Audit schedule (`rh_audit_schedules.status`) | `scheduled → in_progress → completed` (+ `cancelled`) | | | | Audit finding (`rh_audit_findings.status`) | `open → in_progress → resolved → closed` | | | | Audit finding severity | `critical · major · minor · observation` | | | ## Integration points * **Platform Foundation (PF):** multi-tenant org/site, auth/RBAC (`RH_PERMISSIONS.*`), navigation, notifications (PF-10), document storage (PF-11; bucket `pf-documents`), forms (PF-08), CSV import (PF), templates (PF), wizards (PF-41 — RH wizard registration pending), jurisdiction profiles (PF-96). * **FW (Forms & Workflow):** intake, discharge, safety, custom assessments. Domain events persisted to `fw_domain_events`. * **HR (Human Resources):** staff lookup via the **Platform Workforce Layer** (`@/platform/workforce`) — **no direct FK to `hr_employees`**. * **FA (Finance & Accounting):** episode billing balance via the `fa-episode-balance` edge function (`useFaEpisodeBalance`); planned event consumer for `rh_resident_admitted`. * **CL (Clinical):** future — current-residence API for patient chart housing context (not yet implemented). ## Reference * [`docs/rh/database-tables.md`](/rh/database-tables) — engineering DB cheat sheet * [`docs/rh/references.md`](/rh/references) — regulatory & standards references * [`docs/database/erd/RH_ERD.md`](/database/erd/RH_ERD) — entity-relationship diagram * [`docs/compliance/RH_RECOVERY_HOUSING_COMPLIANCE_TRACKING.md`](/compliance/RH_RECOVERY_HOUSING_COMPLIANCE_TRACKING) — live compliance tracker * [`src/cores/rh/AGENTS.md`](https://github.com/Encore-OS/encoreos/blob/development/src/cores/rh/AGENTS.md) — AI agent instructions for `src/cores/rh/` * [`specs/rh/`](https://github.com/Encore-OS/encoreos/tree/development/specs/rh) — module specs, enhancement specs, UX wizard specs, deep reviews * Published end-user / admin docs: the Mintlify `docs/rh/` surface (slug `/rh/overview`) *** **Last updated:** 2026-04-18 (RH Audit & Optimization — Phase 0)