FA ↔ FW Cross-Core Integration Contract

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.

​

Overview

• FA-02: Vendor Bills & Journal Entries
• FA-03: Payments
• FA-04: Purchase Orders & Procurement
• FA-08: Budgeting
• FA-12: Expense Management
• FA-19: Period Close
• FA-22: Accounts Payable Automation
• FA-UX-05: Purchase Order Creation Wizard
• FA-UX-07: Expense Report Wizard

• FW-01/FW-05: Forms (expense reports, purchase requisitions)
• FW-03: Automation Engine (AP automation, payment processing triggers)
• FW-15: Form Field Lookups (vendors, GL accounts, funds, cost centers)
• FW-16: Event-Based Workflow Triggers
• FW-34: Approval Workflows (multi-level financial approvals)
• FW-45: Decision Tables (amount-based approval routing)

​

Integration Pattern

• @/platform/forms — expense report and purchase requisition forms
• @/platform/approvals — financial approval chain submission
• @/platform/events — publishing FA events for FW automation triggers
• @/platform/data-lookup — vendor, GL account, fund lookups in forms
• @/platform/calendar — business day calculations for payment deadlines

​

Event Contracts (FA → FW)

​

FA-12: Expense Management Events

​

Event: fa_expense_report_submitted

Purpose

Payload Schema

interface FaExpenseReportSubmittedPayload {
  organization_id: string;
  expense_report_id: string;    // UUID - fa_expense_reports.id
  employee_id: string;          // UUID - submitter
  department_id: string;        // UUID - pf_departments.id
  total_amount: number;         // Total expense amount
  currency: string;             // ISO currency code
  line_count: number;           // Number of expense lines
  fund_id?: string;             // UUID - fa_funds.id
  project_id?: string;          // UUID - fa_projects.id
  timestamp: string;
}

Consumer Actions

​

Event: fa_expense_report_approved

Purpose

Payload Schema

interface FaExpenseReportApprovedPayload {
  organization_id: string;
  expense_report_id: string;
  employee_id: string;
  total_amount: number;
  approved_by: string;          // UUID - final approver
  timestamp: string;
}

​

FA-04: Purchase Order Events

​

Event: fa_purchase_order_created

Purpose

Payload Schema

interface FaPurchaseOrderCreatedPayload {
  organization_id: string;
  purchase_order_id: string;    // UUID - fa_purchase_orders.id
  po_number: string;
  vendor_id: string;            // UUID - fa_vendors.id
  total_amount: number;
  department_id: string;
  fund_id?: string;
  project_id?: string;
  submitted_by: string;         // UUID
  timestamp: string;
}

Consumer Actions

​

FA-02: Vendor Bill & Journal Entry Events

​

Event: fa_vendor_bill_received

Purpose

Payload Schema

interface FaVendorBillReceivedPayload {
  organization_id: string;
  bill_id: string;              // UUID - fa_vendor_bills.id
  vendor_id: string;
  total_amount: number;
  due_date: string;             // ISO date
  fund_id?: string;
  is_auto_scanned: boolean;     // True if captured via FA-22 AP automation
  timestamp: string;
}

​

Event: fa_journal_entry_pending

Purpose

Payload Schema

interface FaJournalEntryPendingPayload {
  organization_id: string;
  journal_entry_id: string;     // UUID - fa_journal_entries.id
  entry_type: string;           // 'standard' | 'adjusting' | 'closing' | 'reversing'
  total_debits: number;
  total_credits: number;
  fund_id?: string;
  prepared_by: string;          // UUID
  timestamp: string;
}

​

FA-08: Budget Events

​

Event: fa_budget_approved

Purpose

Payload Schema

interface FaBudgetApprovedPayload {
  organization_id: string;
  budget_id: string;
  fiscal_year: number;
  budget_type: string;          // 'operating' | 'capital' | 'project'
  total_amount: number;
  department_id?: string;
  fund_id?: string;
  approved_by: string;
  timestamp: string;
}

​

FA-22: AP Automation Events

​

Event: fa_bill_scan_completed

Payload Schema

interface FaBillScanCompletedPayload {
  organization_id: string;
  scan_id: string;
  bill_id: string;
  vendor_id?: string;           // Auto-detected vendor
  total_amount?: number;        // OCR-extracted amount
  confidence_score: number;     // 0-1 extraction confidence
  timestamp: string;
}

​

Event: fa_bill_duplicate_flagged

Payload Schema

interface FaBillDuplicateFlaggedPayload {
  organization_id: string;
  bill_id: string;
  duplicate_bill_id: string;    // UUID - potential duplicate
  similarity_score: number;     // 0-1 similarity confidence
  timestamp: string;
}

​

FA-19: Period Close Events

​

Event: fa_close_period_started

Payload Schema

interface FaClosePeriodStartedPayload {
  organization_id: string;
  close_period_id: string;
  fiscal_period: string;        // e.g., '2026-03'
  fiscal_year: number;
  timestamp: string;
}

​

Approval Chain Configurations

​

Expense Report Approval

​

Purchase Order Approval

​

Journal Entry Approval

​

Budget Approval

​

Vendor Bill Approval

​

Decision Tables

​

Expense Approval Routing

​

PO Approval Levels

​

Budget Exception Routing

​

Form Templates

​

Planned Form Templates

​

Workflow Templates

​

Planned Workflow Templates (From Recommended Templates)

​

Form Field Lookups

​

Platform Layer Usage

​

Hooks FA Components Import

// Forms
import { useFormTemplate, FormRenderer } from '@/platform/forms';

// Approvals
import { useSubmitApprovalRequest, useApprovalInbox } from '@/platform/approvals';

// Events
import { publishEvent } from '@/platform/events';
import type { KnownEventName } from '@/platform/events';

// Data lookups for form fields
import { useLookupOptions } from '@/platform/data-lookup';

// Business calendar for payment deadlines
import { useBusinessCalendar, calculateDeadline } from '@/platform/calendar';

​

Testing Requirements

​

Unit Tests

• FA event payloads match documented schemas
• Expense routing decision table returns correct chain for each amount tier
• PO approval decision table handles sole-source and new-vendor escalation
• Budget exception routing returns correct actions per variance
• No PII/PHI in event payloads

​

Integration Tests

• fa_expense_report_submitted event triggers approval chain in FW
• fa_purchase_order_created event routes through PO approval (FA-UX-05 contract)
• Amount-based conditional steps activate/skip correctly
• Approval completion updates FA entity status (e.g., PO → approved)
• Rejection updates FA entity status and notifies submitter
• Form field lookups return correct vendors, GL accounts, funds

​

E2E Tests

• Complete expense report flow: form → decision table → approval → reimbursement
• Complete PO flow: wizard → approval → goods receipt → payment
• Budget approval flow: submission → multi-level approval → activation
• Month-end close: period start → checklist tasks → completion

​

RLS Tests

• FA events filtered by organization_id
• Approval requests scoped to submitter’s organization
• Form submissions isolated per tenant
• Vendor and GL account lookups filtered by organization

​

Implementation Status

​

Related Documentation

• FA-UX-05 / FW-03 Integration — PO-specific approval API contract
• FW Cross-Core Integration Guide — Shared patterns
• Event Contracts — FA event registry
• Cross-Core Integration Matrix — Platform-wide matrix
• Recommended Workflow Templates — FA templates (6)
• FW-28 HR/FA Template Plan — Implementation roadmap