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

# Human Resources Entity Relationship Diagram

> Entity relationship diagram for the Human Resources module

> **Version:** 1.0.0\
> **Last Updated:** 2026-01-11

> **Module:** Human Resources\
> **Prefix:** `hr_`\
> **Tables:** 75

## Changelog

* **1.0.0** (2026-01-11): Initial ERD documentation

## Overview

The Human Resources module manages the complete employee lifecycle including positions, departments, leave management, time tracking, payroll, and applicant tracking (ATS).

## Core Employee ERD

```mermaid theme={null}
erDiagram
    hr_employees ||--o{ hr_employee_positions : "holds"
    hr_employees ||--o{ hr_employee_documents : "has docs"
    hr_employees ||--o{ hr_employee_notes : "has notes"
    hr_employees }o--|| pf_profiles : "links to"
    hr_employees }o--|| pf_organizations : "belongs to"
    
    hr_positions ||--o{ hr_employee_positions : "filled by"
    hr_positions }o--|| hr_departments_v : "in department"
    
    hr_departments_v ||--o{ hr_employees : "contains"
    
    hr_employees {
        uuid id PK
        uuid organization_id FK
        uuid user_id FK
        string employee_number
        string first_name
        string last_name
        string email
        date hire_date
        enum status
        jsonb custom_fields
    }
    
    hr_positions {
        uuid id PK
        uuid organization_id FK
        uuid department_id FK
        string title
        string job_code
        decimal min_salary
        decimal max_salary
        boolean is_active
    }
    
    hr_employee_positions {
        uuid id PK
        uuid employee_id FK
        uuid position_id FK
        date start_date
        date end_date
        boolean is_primary
    }
    
    hr_departments_v {
        uuid id PK
        uuid organization_id FK
        string name
        uuid parent_id FK
        uuid manager_id FK
    }
```

## Leave Management ERD

```mermaid theme={null}
erDiagram
    hr_employees ||--o{ hr_leave_requests : submits
    hr_employees ||--o{ hr_leave_balances : has
    hr_leave_types ||--o{ hr_leave_requests : "request type"
    hr_leave_types ||--o{ hr_leave_balances : "balance type"
    hr_leave_types ||--o{ hr_leave_accrual_policies : "accrual rules"
    
    hr_leave_requests {
        uuid id PK
        uuid employee_id FK
        uuid leave_type_id FK
        date start_date
        date end_date
        decimal hours_requested
        enum status
        uuid approved_by FK
        text notes
    }
    
    hr_leave_types {
        uuid id PK
        uuid organization_id FK
        string name
        string code
        boolean is_paid
        boolean requires_approval
        decimal max_days_per_year
    }
    
    hr_leave_balances {
        uuid id PK
        uuid employee_id FK
        uuid leave_type_id FK
        decimal balance_hours
        decimal used_hours
        decimal pending_hours
        integer year
    }
    
    hr_leave_accrual_policies {
        uuid id PK
        uuid leave_type_id FK
        enum accrual_frequency
        decimal accrual_amount
        decimal max_balance
        decimal carryover_max
    }
```

## Time & Attendance ERD

```mermaid theme={null}
erDiagram
    hr_employees ||--o{ hr_timesheet_entries : logs
    hr_employees ||--o{ hr_timesheets : submits
    hr_timesheets ||--o{ hr_timesheet_entries : contains
    
    hr_timesheets {
        uuid id PK
        uuid employee_id FK
        uuid organization_id FK
        date period_start
        date period_end
        enum status
        decimal total_regular_hours
        decimal total_overtime_hours
        uuid approved_by FK
    }
    
    hr_timesheet_entries {
        uuid id PK
        uuid timesheet_id FK
        uuid employee_id FK
        date work_date
        time start_time
        time end_time
        decimal regular_hours
        decimal overtime_hours
        string project_code
        text notes
    }
```

## Payroll ERD

```mermaid theme={null}
erDiagram
    hr_employees ||--o{ hr_payroll_records : receives
    hr_payroll_runs ||--o{ hr_payroll_records : contains
    hr_employees ||--o{ hr_employee_compensation : has
    hr_employees ||--o{ hr_employee_deductions : has
    
    hr_payroll_runs {
        uuid id PK
        uuid organization_id FK
        date pay_period_start
        date pay_period_end
        date pay_date
        enum status
        decimal total_gross
        decimal total_net
        uuid processed_by FK
    }
    
    hr_payroll_records {
        uuid id PK
        uuid payroll_run_id FK
        uuid employee_id FK
        decimal gross_pay
        decimal net_pay
        decimal federal_tax
        decimal state_tax
        decimal benefits_deduction
        jsonb earnings_breakdown
        jsonb deductions_breakdown
    }
    
    hr_employee_compensation {
        uuid id PK
        uuid employee_id FK
        enum pay_type
        decimal pay_rate
        enum pay_frequency
        date effective_date
    }
    
    hr_employee_deductions {
        uuid id PK
        uuid employee_id FK
        string deduction_type
        decimal amount
        boolean is_pretax
        boolean is_active
    }
```

## Applicant Tracking (ATS) ERD

```mermaid theme={null}
erDiagram
    hr_job_postings ||--o{ hr_applications : receives
    hr_applications ||--o{ hr_interviews : scheduled
    hr_applications ||--o{ hr_application_notes : has
    hr_applications }o--|| hr_applicants : "submitted by"
    
    hr_job_postings {
        uuid id PK
        uuid organization_id FK
        uuid position_id FK
        string title
        text description
        enum status
        date posted_date
        date closing_date
        string location
    }
    
    hr_applicants {
        uuid id PK
        uuid organization_id FK
        string first_name
        string last_name
        string email
        string phone
        string resume_url
        jsonb custom_fields
    }
    
    hr_applications {
        uuid id PK
        uuid job_posting_id FK
        uuid applicant_id FK
        enum status
        date applied_date
        string source
        integer rating
    }
    
    hr_interviews {
        uuid id PK
        uuid application_id FK
        timestamp scheduled_at
        integer duration_minutes
        string location
        enum status
        uuid interviewer_id FK
        text feedback
        integer rating
    }
```

## RLS Policy Coverage

| Table                      | SELECT | INSERT | UPDATE | DELETE | WITH CHECK | Status      |
| -------------------------- | ------ | ------ | ------ | ------ | ---------- | ----------- |
| hr\_employees              | ✅      | ✅      | ✅      | ✅      | ✅          | Complete    |
| hr\_positions              | ✅      | ✅      | ✅      | ✅      | ✅          | Complete    |
| hr\_departments\_v         | ✅      | ✅      | ✅      | ✅      | ✅          | Complete    |
| hr\_leave\_requests        | ✅      | ✅      | ✅      | ✅      | ✅          | Complete    |
| hr\_leave\_balances        | ✅      | ✅      | ✅      | ✅      | ✅          | Complete    |
| hr\_timesheets             | ✅      | ✅      | ✅      | ✅      | ✅          | Complete    |
| hr\_timesheet\_entries     | ✅      | ✅      | ✅      | ✅      | ✅          | Complete    |
| hr\_payroll\_runs          | ✅      | ✅      | ✅      | ✅      | ✅          | Complete    |
| hr\_payroll\_records       | ✅      | ✅      | ✅      | ✅      | ✅          | Complete    |
| hr\_payroll\_audit\_log    | ✅      | ✅      | -      | -      | -          | Audit table |
| hr\_ssn\_access\_log       | ✅      | ✅      | -      | -      | -          | Audit table |
| hr\_document\_access\_logs | ✅      | ✅      | -      | -      | -          | Audit table |

## Key Tables

### hr\_employees

Core employee record with personal info, employment status, and org assignment.

### hr\_positions

Job positions with salary ranges, requirements, and department assignment.

### hr\_leave\_requests

Leave/PTO requests with approval workflow integration.

### hr\_timesheets

Weekly/bi-weekly time tracking with approval status.

### hr\_payroll\_runs

Payroll processing batches with summary totals.

## Helper Functions

| Function                                           | Purpose                            |
| -------------------------------------------------- | ---------------------------------- |
| `hr_has_org_access(org_id, user_id)`               | Check HR module access             |
| `hr_is_manager_of(employee_id, user_id)`           | Check management hierarchy         |
| `hr_get_direct_reports(manager_id)`                | Get employees reporting to manager |
| `hr_calculate_leave_balance(employee_id, type_id)` | Calculate current balance          |

## Cross-Module Dependencies

* **PF:** Organizations, profiles, user roles
* **FA:** Payroll journal entries, expense reimbursements
* **FW:** Leave request workflows, onboarding forms
* **FM:** Employee assigned assets