Skip to main content
Spec Reference: HR-PAY-02 Payroll Deductions Management
Status: 🟡 Partial — Phase 1 (schema/RLS) complete; event contracts (HR-11 → HR-PAY-02) planned but not yet implemented
Last Updated: 2026-02-27 This document summarizes integration points between HR-PAY-02 (Payroll Deductions) and HR-07, HR-PAY-01, HR-11, and PF-11. Event payloads are defined in EVENT_CONTRACTS.md; API/flow details are expanded in the spec Implementation Plan and Phase 2/3 expansion.

​
Integration Summary

​
HR-11 (Benefits Administration) — Event

  • Events: hr.benefit_enrollment.created, hr.benefit_enrollment.terminated
  • Payload schema and subscriber: EVENT_CONTRACTS.md § HR-11 / HR-PAY-02
  • HR-PAY-02 behavior: On created → create hr_employee_deductions row (amount from payload, pre_tax flag); on terminated → set end_date on matching deduction. Reconciliation utility (Phase 4) can match existing deductions to enrollments.

​
HR-07 (Payroll Processing) — Data

  • Usage: Payroll run (wizard) loads active deductions per employee, calls deduction calculation service (Phase 3), shows breakdown in preview step, and on finalization writes hr_payroll_deduction_items and updates hr_employee_deductions.ytd_amount.
  • Data consumed: hr_deduction_types, hr_employee_deductions (effective date filter, status = active). No new API contract; same-core read via Supabase client with RLS.
  • Implementation: See HR-PAY-02 Implementation Plan Phase 3 and HR-PAY-02-PHASE-2-3-EXPANSION.

​
HR-PAY-01 (Tax Calculation) — Data

  • Usage: Pre-tax deductions reduce federal (and state, where applicable) taxable income before HR-PAY-01 runs. HR-07 (or deduction service) computes taxable gross after pre-tax deductions and passes it to tax calculation.
  • Contract: In-process (same payroll run); no separate API. Flow documented in spec and expansion Phase 3.
  • Implementation: Deduction service returns pre-tax total; payroll run subtracts from gross before calling HR-PAY-01 tax logic.

​
PF-11 (Document Management) — Outbound

  • Usage: Garnishment court order PDFs stored in pf-documents bucket with restricted access. hr_employee_deductions.custom_fields may store document reference (e.g., document_id or path).
  • Reference: PF-11 Document Management — use platform document APIs for upload and link; no new event contract.

​
CROSS_CORE_INTEGRATIONS.md

The following rows are recorded in CROSS_CORE_INTEGRATIONS.md:
  • HR-11 → HR-PAY-02: Event — Benefit enrollment created/terminated; EVENT_CONTRACTS.md
  • HR-PAY-02 → HR-07: Data — Payroll run consumes deductions and creates deduction items
  • HR-PAY-02 → HR-PAY-01: Data — Pre-tax deductions reduce taxable income input to tax calculation
  • HR-PAY-02 → PF-11: Outbound — Court order document storage and link from employee deduction record
Last Updated: 2026-02-27