RH ↔ FW Cross-Core Integration Contract

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.

​

Overview

• RH-01: Census & Beds (resident admission/discharge)
• RH-02: Programs & Phases (phase progression, intake/exit forms)
• RH-03: Safety Events & Compliance (incidents, UDS testing, pass requests)
• RH-04: Participation & Attendance (attendance threshold monitoring)
• RH-06: Compliance & Staff Operations (regulatory deadlines)

• FW-01/FW-05: Forms (intake assessments, incident reports, UDS documentation, multi-page)
• FW-03: Automation Engine (compliance reminders, escalation triggers)
• FW-15: Form Field Lookups (residents, programs, phases, houses/beds)
• FW-16: Event-Based Workflow Triggers
• FW-33: Signature Capture (consent forms, pass agreements)
• FW-34: Approval Workflows (phase progression, pass requests, incident closure)
• FW-45: Decision Tables (safety event severity routing)

​

Integration Pattern

• @/platform/forms — intake assessments, incident reports, phase assessments, exit surveys
• @/platform/approvals — phase progression and pass request approval chains
• @/platform/events — publishing RH events for FW automation triggers
• @/platform/data-lookup — resident, program, phase, and staff lookups in forms
• @/platform/signatures — consent forms and pass agreement signatures

• rh_programs.intake_form_id → fw_forms.id
• rh_programs.assessment_form_id → fw_forms.id
• rh_programs.exit_survey_form_id → fw_forms.id

​

Event Contracts (RH → FW)

​

RH-01: Resident Lifecycle Events

​

Event: rh_resident_admitted

Purpose

Payload Schema

interface RhResidentAdmittedPayload {
  organization_id: string;
  resident_id: string;          // UUID - rh_residents.id
  program_id: string;           // UUID - rh_programs.id
  house_id: string;             // UUID - rh_houses.id
  bed_id?: string;              // UUID - rh_beds.id
  admission_date: string;       // ISO date
  admission_type: string;       // 'new' | 'readmission' | 'transfer'
  referral_source?: string;     // 'self' | 'court' | 'provider' | 'insurance'
  site_id?: string;
  timestamp: string;
}

Consumer Actions

​

Event: rh_resident_discharged

Purpose

Payload Schema

interface RhResidentDischargedPayload {
  organization_id: string;
  resident_id: string;
  program_id: string;
  house_id: string;
  bed_id?: string;              // UUID - bed to release
  discharge_date: string;       // ISO date
  discharge_type: string;       // 'completed' | 'ama' | 'administrative' | 'transfer' | 'relapse'
  timestamp: string;
}

Consumer Actions

​

RH-02: Phase Progression Events

​

Event: rh_phase_advanced

Purpose

Payload Schema

interface RhPhaseAdvancedPayload {
  organization_id: string;
  resident_id: string;
  program_id: string;
  previous_phase_id: string;    // UUID - rh_phases.id
  new_phase_id: string;         // UUID - rh_phases.id
  progression_type: string;     // 'automatic' | 'manual_approved'
  approved_by?: string;         // UUID - approver (if manual)
  timestamp: string;
}

Consumer Actions

​

Event: rh_phase_progression_requested

Purpose

Payload Schema

interface RhPhaseProgressionRequestedPayload {
  organization_id: string;
  resident_id: string;
  program_id: string;
  current_phase_id: string;
  requested_phase_id: string;
  requested_by: string;         // UUID - staff member requesting progression
  assessment_score?: number;    // Phase assessment result
  timestamp: string;
}

​

RH-03: Safety Event & Compliance Events

​

Event: rh_safety_event_created

Purpose

Payload Schema

interface RhSafetyEventCreatedPayload {
  organization_id: string;
  safety_event_id: string;      // UUID - rh_safety_events.id
  event_type: string;           // 'significant_event' | 'behavioral' | 'medical' | 'property' | 'other'
  severity: string;             // 'low' | 'medium' | 'high' | 'critical'
  resident_id?: string;         // UUID - involved resident (if applicable)
  house_id: string;
  site_id?: string;
  reported_by: string;          // UUID - staff member
  timestamp: string;
}

Consumer Actions

​

Event: rh_uds_test_positive

Purpose

Payload Schema

interface RhUdsTestPositivePayload {
  organization_id: string;
  uds_test_id: string;          // UUID - rh_uds_tests.id
  episode_id: string;           // UUID - context for downstream workflows
  tested_at: string;            // ISO 8601 timestamp
  correlation_id?: string;
}

Consumer Actions

​

Event: rh_pass_requested

Purpose

Payload Schema

interface RhPassRequestedPayload {
  organization_id: string;
  pass_id: string;              // UUID - rh_passes.id
  resident_id: string;
  pass_type: string;            // 'day' | 'overnight' | 'weekend' | 'extended'
  departure_date: string;
  return_date: string;
  destination: string;          // General area, not specific address
  house_id: string;
  timestamp: string;
}

​

RH-04: Attendance Events

​

Event: rh_attendance_threshold_breached

Purpose

Payload Schema

interface RhAttendanceThresholdBreachedPayload {
  organization_id: string;
  resident_id: string;
  program_id: string;
  activity_type: string;        // 'group' | 'meeting' | 'counseling' | 'community_service'
  attendance_rate: number;       // 0-100 percentage
  threshold: number;             // Required minimum percentage
  period_start: string;
  period_end: string;
  timestamp: string;
}

​

RH-06: Compliance Events

​

Event: rh_compliance_deadline_approaching

Purpose

Payload Schema

interface RhComplianceDeadlinePayload {
  organization_id: string;
  compliance_item_id: string;
  compliance_type: string;      // 'fire_inspection' | 'license_renewal' | 'staff_training' | 'audit'
  deadline_date: string;
  days_until_deadline: number;
  house_id?: string;
  site_id?: string;
  timestamp: string;
}

Consumer Actions

​

Approval Chain Configurations

​

Phase Progression Approval

​

Pass Request Approval

​

Safety Event Investigation Closure

​

Discharge Approval

​

Decision Tables

​

Safety Event Severity Routing

​

Pass Approval Routing

​

Form Templates

​

Existing Templates

​

Planned Form Templates

​

Workflow Templates

​

Planned Workflow Templates (From Recommended Templates)

​

Form Field Lookups

​

Database References (RH → FW)

-- rh_programs table references fw_forms for associated forms
ALTER TABLE rh_programs
  ADD COLUMN intake_form_id UUID REFERENCES fw_forms(id),
  ADD COLUMN assessment_form_id UUID REFERENCES fw_forms(id),
  ADD COLUMN exit_survey_form_id UUID REFERENCES fw_forms(id);

• Intake: Filled during resident admission (RH-01)
• Assessment: Filled during phase transition evaluation (RH-02)
• Exit Survey: Filled during discharge (RH-01)

​

Platform Layer Usage

​

Hooks RH Components Import

// Forms
import { useFormTemplate, FormRenderer } from '@/platform/forms';

// Approvals
import { useSubmitApprovalRequest, useMyApprovalRequests } from '@/platform/approvals';

// Events
import { publishEvent } from '@/platform/events';
import type { KnownEventName } from '@/platform/events';

// Data lookups for form fields
import { useLookupOptions } from '@/platform/data-lookup';

// Signatures for consent forms
import { SignatureCapture, useFormSignature } from '@/platform/signatures';

​

Testing Requirements

​

Unit Tests

• RH event payloads match documented schemas
• Safety event severity decision table returns correct response workflow
• Pass approval routing decision table handles all phase × risk combinations
• No PII/PHI in event payloads (resident names, DOBs, substance details)

​

Integration Tests

• rh_resident_admitted event triggers intake workflow in FW
• rh_phase_progression_requested event routes to phase approval chain
• rh_safety_event_created event routes through severity decision table
• rh_pass_requested event routes through pass approval chain
• Phase assessment form linked to program via rh_programs.assessment_form_id
• Form field lookups return correct residents, programs, houses

​

E2E Tests

• Complete intake flow: admission → intake form → orientation → assessment → bed assignment
• Phase progression flow: assessment → score → approval → phase update → privilege change
• Incident flow: report → severity routing → investigation → corrective action → closure approval
• Pass flow: request → risk assessment → approval chain → departure → return check-in
• Discharge flow: request → approval → exit survey → room inspection → billing close

​

RLS Tests

• RH events filtered by organization_id
• Approval requests scoped to submitter’s organization
• Form submissions isolated per tenant
• Resident lookups filtered by organization

​

Implementation Status

​

Related Documentation

• FW Cross-Core Integration Guide — Shared patterns
• RH-04 Attendance Integration — Attendance threshold events
• RH-06 Compliance Integration — Compliance events
• Event Contracts — RH event registry
• Cross-Core Integration Matrix — Platform-wide matrix
• Recommended Workflow Templates — RH templates (3)