Skip to main content

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.

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

FromToPatternDescription
HR-07, HR-PAY-01, HR-PAY-02HR-PAY-04Data (inbound)Payroll runs, YTD wages/taxes, deductions for W-2/941/940
HR-01, HR-03HR-PAY-04Data (inbound)Employee and employer master data; new hire data for New Hire Report
HR-PAY-03HR-PAY-04ConsistencyPay stub data alignment
HR-12HR-PAY-04Platform / existingEmployee access to W-2 in self-service portal; hr_tax_documents
HR-PAY-04FAEventEmployer 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 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 needSourceNotes
W-2 / W-3HR-07 payroll run tables (e.g. hr_payroll_runs, hr_payroll_run_items or equivalent); HR-PAY-01 for withholding/wage basesExact table names TBD when HR-07/HR-PAY-01 schema is final
1099-NECContractor compensation from HR payroll (contractor payment source TBD in implementation)FA handles AP/vendor 1099s separately
New Hirehr_employees (hire_date, name, address) + HR-03 onboarding; CSV per AZ DES formatExport within 20 days of hire
W-2 distributionhr_tax_documents (existing); HR-12 self-service and notificationsPDFs 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: HR → FA event hr.employer_tax_liability.calculated. This doc is the detailed integration reference for HR-PAY-04.

​
References

Last Updated: 2026-02-27