Skip to main content
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):

​
Spec status

See specs/rh/summaries/DEFERRED-PHASES-SUMMARY.md for the complete deferred / planned backlog and 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):
⚠️ Only /rh/settings is wrapped in <RequirePermission> 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. ERD: docs/database/erd/RH_ERD.md.
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

​
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

Last updated: 2026-04-18 (RH Audit & Optimization — Phase 0)