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

# HR-PAY-04: Tax Forms & Compliance — Integration

> This document describes the integration interfaces between HR-PAY-04 (Tax Forms & Compliance) and linked systems: HR-07 (Payroll), HR-PAY-01 (Tax Calculation),…

**Spec ID:** HR-PAY-04\
**Status:** ✅ Phase 1 Complete; Phase 2/3 Planned\
**Last Updated:** 2026-02-27

This document describes the integration interfaces between HR-PAY-04 (Tax Forms & Compliance) and linked systems: HR-07 (Payroll), HR-PAY-01 (Tax Calculation), HR-PAY-02 (Deductions), HR-PAY-03 (Direct Deposit & Pay Stubs), HR-01 (Employee Directory), HR-03 (Onboarding), HR-12 (Self-Service), and FA (Finance).

***

## Integration Summary

| From                        | To        | Pattern             | Description                                                          |
| --------------------------- | --------- | ------------------- | -------------------------------------------------------------------- |
| HR-07, HR-PAY-01, HR-PAY-02 | HR-PAY-04 | Data (inbound)      | Payroll runs, YTD wages/taxes, deductions for W-2/941/940            |
| HR-01, HR-03                | HR-PAY-04 | Data (inbound)      | Employee and employer master data; new hire data for New Hire Report |
| HR-PAY-03                   | HR-PAY-04 | Consistency         | Pay stub data alignment                                              |
| HR-12                       | HR-PAY-04 | Platform / existing | Employee access to W-2 in self-service portal; `hr_tax_documents`    |
| HR-PAY-04                   | FA        | Event               | Employer tax liability events for GL posting                         |

***

## Event Contracts (HR-PAY-04 as Publisher)

### `hr.employer_tax_liability.calculated`

* **Subscribers:** FA (Finance) — for GL posting and liability tracking.
* **Payload schema:** See [EVENT\_CONTRACTS.md](/architecture/integrations/EVENT_CONTRACTS#hr-pay-04-employer-tax-liability-events-tax-forms-compliance) for full payload (organization\_id, tax\_period\_type, federal\_income\_tax\_withheld, employer\_ss\_tax, employer\_medicare\_tax, total\_liability, etc.).
* **Purpose:** Notify FA when employer-side tax liability has been calculated so FA can post to GL (or queue for manual posting).

***

## Data Sources (Internal)

| Data need        | Source                                                                                                                        | Notes                                                      |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| W-2 / W-3        | HR-07 payroll run tables (e.g. `hr_payroll_runs`, `hr_payroll_run_items` or equivalent); HR-PAY-01 for withholding/wage bases | Exact table names TBD when HR-07/HR-PAY-01 schema is final |
| 1099-NEC         | Contractor compensation from HR payroll (contractor payment source TBD in implementation)                                     | FA handles AP/vendor 1099s separately                      |
| New Hire         | `hr_employees` (hire\_date, name, address) + HR-03 onboarding; CSV per AZ DES format                                          | Export within 20 days of hire                              |
| W-2 distribution | `hr_tax_documents` (existing); HR-12 self-service and notifications                                                           | PDFs uploaded after generation                             |

***

## Platform Integration Layer Usage

* **PF-11 (Documents):** W-2 PDFs stored and accessed via existing document storage; employee access via HR-12.
* **PF-10 (Notifications):** Optional notification when W-2 is available (per spec).
* **Permissions (PF-30):** `hr.tax_forms.view`, `hr.tax_forms.manage`; constants in `src/platform/permissions/constants.ts`; seed `pf_module_permissions` and `pf_role_permissions`.

***

## CROSS\_CORE\_INTEGRATIONS.md

HR-PAY-04 is referenced in [CROSS\_CORE\_INTEGRATIONS.md](/architecture/integrations/CROSS_CORE_INTEGRATIONS): HR → FA event `hr.employer_tax_liability.calculated`. This doc is the detailed integration reference for HR-PAY-04.

***

## References

* **Spec:** `specs/hr/specs/HR-PAY-04-tax-forms-compliance.md`
* **Event payload:** [EVENT\_CONTRACTS.md](/architecture/integrations/EVENT_CONTRACTS#hr-pay-04-employer-tax-liability-events-tax-forms-compliance)
* **Matrix:** [CROSS\_CORE\_INTEGRATIONS.md](/architecture/integrations/CROSS_CORE_INTEGRATIONS)

**Last Updated:** 2026-02-27