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: FA-10
Status: 📝 Planned
Last Updated: 2026-02-12 This document describes the integration interfaces between FA-10 (Tax Reporting & Compliance) and linked systems: FA-03 (Accounts Payable), HR-07 (Payroll), and PF (Notifications, Documents).

​
Integration Summary

FromToPatternDescription
FA-10PF-10EventTax form generated / tax year closed → notifications (deadlines, delivery confirmations)
FA-10PF-11Platform LayerTax form PDF storage via Documents
HR-07FA-10API / EventPayroll data for W-2 and 941/940; payroll_run_completed event
FA-03FA-10API / EventVendor payments for 1099; vendor_payment_processed event

​
Event Contracts (FA-10 as Publisher)

  • tax_1099_generated — PF-10 (Notifications). Payload: organization_id, tax_year_id, vendor_id, form_type, generated_at. See EVENT_CONTRACTS.md when implemented.
  • tax_w2_generated — PF-10, HR-07. Payload: organization_id, tax_year_id, employee_id, generated_at.
  • tax_year_closed — PF-10, FA-07. Payload: organization_id, tax_year_id, tax_year, closed_at, closed_by.

​
Event Contracts (FA-10 as Consumer)

  • payroll_run_completed (HR-07) — Trigger W-2 generation.
  • vendor_payment_processed (FA-03) — Update 1099 totals.

​
API Contracts

APIs Exposed by FA-10:
  • POST /api/v1/fa/tax/1099/generate — Request: tax_year_id, optional form_type. Response: job or form identifiers. Internal (FA module) only.
APIs Consumed by FA-10:
  • /api/v1/hr/payroll/tax-data (HR-07) — Payroll data for W-2 and 941/940.
  • /api/v1/fa/vendors/payments (FA-03) — Vendor payments for 1099.
Full request/response schemas to be defined in implementation plan or OpenAPI.

​
CROSS_CORE_INTEGRATIONS.md

FA-10 is already referenced in CROSS_CORE_INTEGRATIONS.md (events and APIs). This doc is the detailed integration reference for FA-10.

​
Dual-System Architecture: HR-PAY-04 vs FA-10

Tax forms are generated by two independent systems with different data sources:
SystemData SourceForm TypesAuthoritative For
HR-PAY-04Payroll runs (hr_payroll_runs, hr_payroll_line_items)W-2, W-3, 941, 940, AZ A1-QRT, AZ A1-R, 1099-NEC (payroll contractors), New HireEmployee wage statements, employer payroll tax returns
FA-10General ledger (fa_journal_entries, fa_transactions)1099-NEC/MISC (AP vendors), W-2 (GL reconciliation), 941 (GL view)Vendor 1099s from Accounts Payable, GL-based tax reconciliation

​
Key Design Decisions

  1. HR-PAY-04 is authoritative for payroll-derived forms (W-2, 941, 940). These are generated from actual payroll run data with employee-level detail.
  2. FA-10 is authoritative for AP-derived 1099s. Vendor payments tracked through Accounts Payable generate 1099-NEC/MISC forms.
  3. Cross-core sync: HR-PAY-04 publishes hr.employer_tax_liability.calculated events via Supabase Realtime (hr_events channel). FA subscribes for GL posting of employer FICA, FUTA, and SUTA liabilities.
  4. No direct imports: Integration uses event-based patterns only. HR-PAY-04 never imports from FA, and vice versa.

​
Event Flow

HR-PAY-04 (quarterly run) → publishEmployerTaxLiabilityEvent()
  → Supabase Realtime channel: hr_events
    → FA listener: creates GL journal entries for employer tax liabilities

​
Spec Reference