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

# RH-HR Integration Architecture

> This document explains the architectural decision regarding the integration between the Recovery Housing (RH) core and Human Resources (HR) core, specifically…

**Created:** 2025-12-18\
**Status:** Architecture Decision Record\
**Related Specs:** RH-06 (Compliance & Staff Operations)

***

## Overview

This document explains the architectural decision regarding the integration between the Recovery Housing (RH) core and Human Resources (HR) core, specifically around staff employee references.

## Architecture Decision: No Foreign Key Constraints for `staff_employee_id`

### Context

RH-06 introduces several tables that reference staff employees:

* `rh_staff_assignments.staff_employee_id`
* `rh_staff_trainings.staff_employee_id`
* `rh_shift_notes.staff_employee_id`

### Decision

These `staff_employee_id` columns intentionally **do not have foreign key constraints** to HR tables (`hr_employees`).

### Rationale

Per the Encore OS Platform constitution (§1.2, §1.3):

1. **Core Isolation Principle**: Cores depend ONLY on Platform Foundation (PF), never on each other directly. Foreign key constraints would create a direct database-level dependency between RH and HR.

2. **Deployment Independence**: Each core should be deployable and testable independently. FK constraints would require HR schema to exist for RH migrations to succeed.

3. **Cross-Core Integration Patterns**: The constitution mandates that cross-core communication use one of:

   * Platform Integration Layer (hooks, components in `@/platform/`)
   * Event-based integration (pg\_notify/webhooks)
   * API contracts (edge functions)

   Not direct database references.

### Implementation Details

#### Data Integrity Approach

Instead of FK constraints, RH-06 uses:

1. **Application-Level Validation**: UI components use `@/platform/workforce` hooks to look up and validate employee IDs before saving.

2. **UUID Type Enforcement**: The `staff_employee_id` columns are typed as `UUID`, ensuring only valid UUIDs can be stored.

3. **RLS Policies**: Access control is enforced via organization-scoped RLS policies, not FK relationships.

#### Employee Lookup Pattern

```typescript theme={null}
// ✅ CORRECT - Use Platform Integration Layer
import { useWorkforceEmployees } from '@/platform/workforce';

function StaffAssignmentForm() {
  const { employees } = useWorkforceEmployees(organizationId);
  // Use employees for dropdown selection
}

// ❌ WRONG - Direct core import
import { useEmployees } from '@/cores/hr/hooks/useEmployees';
```

### Implications

1. **Orphaned References**: If an employee is deleted from HR, RH records referencing that employee will have orphaned `staff_employee_id` values. This is acceptable because:
   * Historical records should be preserved
   * Soft-delete is the standard pattern (HR uses `deleted_at`)
   * UI can gracefully handle "Unknown Employee" display

2. **Data Migration**: When migrating data, ensure employee IDs exist in HR before creating RH staff records.

3. **Testing**: RLS tests can create test users directly in `auth.users` without needing HR employee records.

### Alternative Considered

**Option: Add FK constraint to `pf_profiles`**

Rejected because:

* Not all staff may have platform profiles (contractors, external auditors)
* Would still create cross-table dependency issues in tests
* `pf_profiles` is for platform users, not necessarily all staff

## Related Documentation

* [Constitution §1.2-1.3: Core Architecture](https://github.com/Encore-OS/encoreos/blob/development/constitution.md)
* [Platform Integration Layers](/architecture/integrations/PLATFORM_INTEGRATION_LAYERS)
* [RH-06 Spec Errata E-05](https://github.com/Encore-OS/encoreos/blob/development/specs/rh/specs/RH-06-compliance-staff-operations.md)

***

**Last Updated:** 2025-12-18