Employee Directory & Org Structure — Integration

​

Overview

​

Integration Points

​

Platform Foundation (PF) Dependencies

• PF-01 (Organizations & Sites): organization_id, site_id references for multi-tenancy
• PF-02 (RBAC): has_role(), has_org_access() functions, pf_user_roles table for permission checks
• PF-03 (App Launcher): HR module card in dashboard navigation
• PF-04 (Audit Logging): Track employee record changes (create, update, terminate) via audit triggers
• PF-06 (User Profile): Link hr_employees.profile_id to pf_profiles, avatar uploads via PF-11

​

Consumer Core Dependencies (Downstream)

• HR-02 (Credentialing): Links credentials to employees, filters by is_clinical
• HR-03 (Onboarding): New hire workflow creates hr_employees record
• HR-04 (Scheduling): Fetches employees for shift assignments, respects primary_site_id
• HR-05 (Time Tracking): Clock in/out tied to employee_id
• HR-06 (PTO): Leave requests reference employee_id
• HR-07 (Payroll): Payroll processing uses employment_type, is_exempt fields

• RH (Recovery Housing): Staff assignments for recovery housing sites (via event subscription)
• FM (Facilities): Technician assignments for work orders (via employee lookup)
• FA (Finance): Payroll processing (via employee lookup, future HR-07)

​

Event Contracts

​

Event: hr_employee_created (canonical)

interface HrEmployeeCreatedPayload {
  event_type: 'hr_employee_created';
  employee_id: uuid;
  organization_id: uuid;
  department_id?: uuid;
  position_id?: uuid;
  hire_date: timestamp;
  is_clinical: boolean;
  timestamp: timestamptz;
}

​

Event: hr_employee_assigned_to_site

interface HrEmployeeAssignedToSitePayload {
  event_type: 'hr_employee_assigned_to_site';
  employee_id: uuid;
  site_id: uuid;
  organization_id: uuid;
  assignment_date: timestamp;
  role: 'staff' | 'manager' | 'admin';
  department_id?: uuid;
  timestamp: timestamptz;
}

​

Event: hr_employee_terminated

interface HrEmployeeTerminatedPayload {
  event_type: 'hr_employee_terminated';
  employee_id: uuid;
  organization_id: uuid;
  termination_date: timestamp;
  termination_reason?: string;
  timestamp: timestamptz;
}

​

API Contracts

​

API: Employee Lookup

// Other cores query hr_employees (RLS enforces org isolation)
const employees = await supabase
  .from('hr_employees')
  .select('id, full_name, job_title, primary_site_id')
  .eq('organization_id', currentOrg.id)
  .eq('employment_status', 'active');

​

API: Org Chart Data

​

Platform Integration Layer Usage

• PF-11 (Document Management): Employee documents, credential storage (via HR-02)
• PF-10 (Notifications): Employee-related notifications (via HR-02)
• PF-12 (Reports): Employee directory reports, org charts

​

Integration Examples

​

Example 1: RH Core Subscribes to Employee Assignment Event

// In RH Core edge function or client
const channel = supabase
  .channel('employee-assignments')
  .on(
    'postgres_changes',
    {
      event: 'INSERT',
      schema: 'public',
      table: 'hr_employee_site_assignments',
    },
    async (payload) => {
      // Notify recovery housing site of new staff assignment
      await sendNotification({
        type: 'staff_assigned',
        site_id: payload.new.site_id,
        employee_id: payload.new.employee_id
      });
    }
  )
  .subscribe();

​

Example 2: FA Core Queries Employee Data for Payroll

// In FA Core (payroll processing)
const employees = await supabase
  .from('hr_employees')
  .select('id, employment_type, is_exempt, primary_site_id')
  .eq('organization_id', currentOrg.id)
  .eq('employment_status', 'active');

// Process payroll for each employee
for (const employee of employees.data) {
  await processPayroll(employee.id, {
    employment_type: employee.employment_type,
    is_exempt: employee.is_exempt
  });
}

​

Security Considerations

​

Multi-Tenancy

• ✅ RLS Enforcement: All hr_* tables filtered by organization_id via RLS policies
• ✅ Site Scoping: Queries respect site_id for site-level admins
• ✅ Cross-Org Isolation: Platform admins can access all orgs, others cannot

​

Role-Based Access Control

• ✅ HR Admin: Full access to all employee data (CRUD)
• ✅ Manager: View direct reports, limited update permissions
• ✅ Staff: View directory (active employees only), own profile

​

Data Protection

• ✅ PII Handling: Employee contact information, emergency contacts protected by RLS
• ✅ Audit Trail: All employee record changes logged via PF-04

​

Testing Requirements

• Event payload structure validation
• Event fires on trigger condition (employee creation, site assignment, termination)
• Correct organization_id included in all events
• Subscribers handle events correctly (GR-01, RH-01, HR-04, HR-05)
• RLS policies enforce org isolation on employee queries
• API consumers can query employee data with proper filters

​

References

• HR-01 Spec
• EVENT_CONTRACTS.md
• API_CONTRACTS.md
• CROSS_CORE_INTEGRATIONS.md