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

# FA ↔ FW Cross-Core Integration Contract

> Version: 1.0.0 Status: 📝 Planned Created: 2026-03-21 Last Updated: 2026-03-21 Constitution Reference: Section 1.3 (Integration Patterns — Pattern 1: Platform…

**Version:** 1.0.0
**Status:** 📝 Planned
**Created:** 2026-03-21
**Last Updated:** 2026-03-21
**Constitution Reference:** Section 1.3 (Integration Patterns — Pattern 1: Platform Integration Layer, Pattern 2: Event-Based, Pattern 3: API Contracts)

***

## Overview

This document defines the comprehensive integration contract between the **FA (Fund Accounting)** core and the **FW (Forms & Workflow)** core. FA uses FW extensively for financial approval workflows, expense forms, purchase order routing, budget approvals, and amount-based decision table routing.

**Related Specifications:**

* 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 Features Consumed:**

* 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)

**Existing Integration:** [FA-UX-05 / FW-03 Integration](./FA-UX-05-FW-03-INTEGRATION.md) — PO-specific approval contract (this document supersedes it as the comprehensive guide).

**Cross-cutting guide:** See [FW Cross-Core Integration Guide](../../../specs/cross-cutting/FW-CROSS-CORE-INTEGRATION-GUIDE.md) for shared patterns, platform layer imports, and testing requirements.

***

## Integration Pattern

**Primary Pattern:** Pattern 1 — Platform Integration Layer
**Secondary Pattern:** Pattern 2 — Event-Based Integration
**Tertiary Pattern:** Pattern 3 — API Contracts (for PO approval submission)

FA accesses FW capabilities through:

* `@/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)

Events published by FA that trigger FW automations and workflows.

### FA-12: Expense Management Events

#### Event: `fa_expense_report_submitted`

**Event:** `fa_expense_report_submitted`
**Channel:** `fa_events`
**Publisher:** FA (FA-12 Expense Management)
**Subscribers:** FW-34 (approval workflow), PF-10 (notification)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Purpose

Triggers expense report approval workflow when an employee submits an expense report.

##### Payload Schema

```typescript theme={null}
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

| Consumer             | Action                                   | Status |
| -------------------- | ---------------------------------------- | ------ |
| FW-45 Decision Table | Determine approval chain based on amount | 📝     |
| FW-34 Approval       | Route to amount-tiered approval chain    | 📝     |
| PF-10 Notification   | Notify next approver                     | 📝     |

***

#### Event: `fa_expense_report_approved`

**Event:** `fa_expense_report_approved`
**Channel:** `fa_events`
**Publisher:** FA (FA-12 Expense Management)
**Subscribers:** FW-03 (reimbursement automation), PF-10 (notification)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Purpose

Triggers reimbursement processing when an expense report is fully approved.

##### Payload Schema

```typescript theme={null}
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`

**Event:** `fa_purchase_order_created`
**Channel:** `fa_events`
**Publisher:** FA (FA-04 / FA-UX-05)
**Subscribers:** FW-34 (PO approval workflow)
**Status:** 📝 Planned (see [FA-UX-05-FW-03-INTEGRATION.md](./FA-UX-05-FW-03-INTEGRATION.md) for detailed API contract)

##### Purpose

Triggers PO approval workflow when a purchase order is created via the PO wizard.

##### Payload Schema

```typescript theme={null}
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

| Consumer             | Action                                       | Status |
| -------------------- | -------------------------------------------- | ------ |
| FW-45 Decision Table | Determine PO approval levels based on amount | 📝     |
| FW-34 Approval       | Route through amount-tiered approval chain   | 📝     |
| PF-10 Notification   | Notify purchasing manager, next approver     | 📝     |

***

### FA-02: Vendor Bill & Journal Entry Events

#### Event: `fa_vendor_bill_received`

**Event:** `fa_vendor_bill_received`
**Channel:** `fa_events`
**Publisher:** FA (FA-02 / FA-22)
**Subscribers:** FW-34 (bill approval workflow), FW-03 (AP automation)
**Status:** 📝 Planned

##### Purpose

Triggers bill approval workflow when a vendor bill is received (manually entered or auto-scanned via FA-22).

##### Payload Schema

```typescript theme={null}
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`

**Event:** `fa_journal_entry_pending`
**Channel:** `fa_events`
**Publisher:** FA (FA-02 Journal Entries)
**Subscribers:** FW-34 (JE approval workflow)
**Status:** 📝 Planned

##### Purpose

Triggers journal entry approval when a JE is submitted for review.

##### Payload Schema

```typescript theme={null}
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`

**Event:** `fa_budget_approved`
**Channel:** `fa_events`
**Publisher:** FA (FA-08 Budgeting)
**Subscribers:** FW-03 (budget activation automation), PF-10 (notification)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Purpose

Triggers budget activation when a budget is approved through the approval chain.

##### Payload Schema

```typescript theme={null}
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`

**Event:** `fa_bill_scan_completed`
**Channel:** `fa_events`
**Publisher:** FA (FA-22 AP Automation)
**Subscribers:** FW-03 (auto-matching workflow)
**Status:** 📝 Planned (referenced in EVENT\_CONTRACTS.md)

##### Payload Schema

```typescript theme={null}
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`

**Event:** `fa_bill_duplicate_flagged`
**Channel:** `fa_events`
**Publisher:** FA (FA-22 AP Automation)
**Subscribers:** FW-03 (duplicate review workflow)
**Status:** 📝 Planned (referenced in EVENT\_CONTRACTS.md)

##### Payload Schema

```typescript theme={null}
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`

**Event:** `fa_close_period_started`
**Channel:** `fa_events`
**Publisher:** FA (FA-19 Period Close)
**Subscribers:** FW-03 (close checklist automation)
**Status:** ✅ Implemented (registered in `KnownEventName`)

##### Payload Schema

```typescript theme={null}
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

**Chain ID:** `fa-expense-report-approval`
**Entity Type:** `fa_expense_reports`
**Based On:** FA-12, FA-UX-07

| Step | Approver Type            | Condition         | Timeout | Escalation               |
| ---- | ------------------------ | ----------------- | ------- | ------------------------ |
| 1    | `submitter_manager`      | Always            | 48h     | `department_head`        |
| 2    | `role: finance_manager`  | Amount > \$500    | 48h     | `role: finance_director` |
| 3    | `role: finance_director` | Amount > \$5,000  | 72h     | `role: cfo`              |
| 4    | `role: cfo`              | Amount > \$25,000 | 72h     | —                        |

***

### Purchase Order Approval

**Chain ID:** `fa-purchase-order-approval`
**Entity Type:** `fa_purchase_orders`
**Based On:** FA-04, FA-UX-05

| Step | Approver Type              | Condition         | Timeout | Escalation               |
| ---- | -------------------------- | ----------------- | ------- | ------------------------ |
| 1    | `submitter_manager`        | Always            | 48h     | `department_head`        |
| 2    | `role: purchasing_manager` | Amount > \$1,000  | 48h     | `role: finance_director` |
| 3    | `role: finance_director`   | Amount > \$10,000 | 72h     | `role: cfo`              |
| 4    | `role: cfo`                | Amount > \$50,000 | 72h     | —                        |

See [FA-UX-05-FW-03-INTEGRATION.md](./FA-UX-05-FW-03-INTEGRATION.md) for the detailed PO approval API contract.

***

### Journal Entry Approval

**Chain ID:** `fa-journal-entry-approval`
**Entity Type:** `fa_journal_entries`
**Based On:** FA-02

| Step | Approver Type       | Condition                                    | Timeout | Escalation         |
| ---- | ------------------- | -------------------------------------------- | ------- | ------------------ |
| 1    | `role: gl_reviewer` | Always                                       | 48h     | `role: controller` |
| 2    | `role: controller`  | Amount > \$10,000 OR adjusting/closing entry | 72h     | `role: cfo`        |

***

### Budget Approval

**Chain ID:** `fa-budget-approval`
**Entity Type:** `fa_budgets`
**Based On:** FA-08

| Step | Approver Type            | Condition                  | Timeout          | Escalation               |
| ---- | ------------------------ | -------------------------- | ---------------- | ------------------------ |
| 1    | `department_head`        | Always                     | 5 business days  | `role: finance_director` |
| 2    | `role: finance_director` | Always                     | 5 business days  | `role: cfo`              |
| 3    | `role: cfo`              | Budget > \$100K            | 5 business days  | —                        |
| 4    | `role: board_treasurer`  | Capital budget OR > \$500K | 10 business days | —                        |

***

### Vendor Bill Approval

**Chain ID:** `fa-vendor-bill-approval`
**Entity Type:** `fa_vendor_bills`
**Based On:** FA-02

| Step | Approver Type      | Condition                         | Timeout | Escalation         |
| ---- | ------------------ | --------------------------------- | ------- | ------------------ |
| 1    | `role: ap_clerk`   | Always (3-way match verification) | 48h     | `role: ap_manager` |
| 2    | `role: ap_manager` | Amount > \$5,000                  | 48h     | `role: controller` |
| 3    | `role: controller` | Amount > \$25,000                 | 72h     | `role: cfo`        |

***

## Decision Tables

### Expense Approval Routing

**Table ID:** `fa-expense-approval-routing`
**Hit Policy:** FIRST (first matching rule wins)

| Amount           | Category    | Department | → Approval Chain                            |
| ---------------- | ----------- | ---------- | ------------------------------------------- |
| \< \$500         | Any         | Any        | `manager_only`                              |
| $500 – $5,000    | Any         | Any        | `manager_finance`                           |
| $5,000 – $25,000 | Any         | Any        | `manager_finance_director`                  |
| > \$25,000       | Any         | Any        | `manager_finance_cfo`                       |
| Any              | `travel`    | Any        | `manager_finance` (always requires finance) |
| Any              | `equipment` | Any        | `manager_finance_it` (includes IT review)   |

***

### PO Approval Levels

**Table ID:** `fa-po-approval-levels`
**Hit Policy:** FIRST

| Amount            | Vendor Type   | → Required Approvals                          |
| ----------------- | ------------- | --------------------------------------------- |
| \< \$1,000        | Any           | Manager only                                  |
| $1,000 – $10,000  | Any           | Manager → Purchasing                          |
| $10,000 – $50,000 | Any           | Manager → Purchasing → Finance Director       |
| > \$50,000        | Any           | Manager → Purchasing → Finance Director → CFO |
| Any               | `sole_source` | +1 additional approval level                  |
| Any               | `new_vendor`  | +Vendor verification step                     |

***

### Budget Exception Routing

**Table ID:** `fa-budget-exception-routing`
**Hit Policy:** FIRST

| Variance % | Budget Category | → Action                                              |
| ---------- | --------------- | ----------------------------------------------------- |
| \< 5%      | Any             | Auto-approve, log only                                |
| 5-10%      | Operating       | Manager → Finance notification                        |
| 5-10%      | Capital         | Manager → Finance → Director                          |
| > 10%      | Any             | Manager → Finance Director → CFO → Board notification |

***

## Form Templates

FA uses these FW form templates:

| Template ID                      | Type   | Spec Location                                                  | Description                    |
| -------------------------------- | ------ | -------------------------------------------------------------- | ------------------------------ |
| `fa-expense-report-form`         | Form   | `specs/fw/templates/forms/fa-expense-report-form.md`           | Expense report with line items |
| `fa-purchase-requisition-form`   | Form   | `specs/fw/templates/forms/fa-purchase-requisition-form.md`     | Purchase request data capture  |
| `fa-expense-report-bundle`       | Bundle | `specs/fw/templates/bundles/fa-expense-report-bundle.md`       | Form + approval workflow       |
| `fa-purchase-requisition-bundle` | Bundle | `specs/fw/templates/bundles/fa-purchase-requisition-bundle.md` | Form + PO approval workflow    |

### Planned Form Templates

| Template ID               | Priority | Description                        |
| ------------------------- | -------- | ---------------------------------- |
| `fa-vendor-setup-form`    | P2       | New vendor onboarding form         |
| `fa-budget-request-form`  | P2       | Budget amendment/exception request |
| `fa-payment-request-form` | P2       | Manual payment request form        |

***

## Workflow Templates

| Template ID                  | Spec Location                                                | Description                           |
| ---------------------------- | ------------------------------------------------------------ | ------------------------------------- |
| `fa-expense-approval`        | `specs/fw/templates/workflows/fa-expense-approval.md`        | Amount-tiered expense approval        |
| `fa-purchase-order-approval` | `specs/fw/templates/workflows/fa-purchase-order-approval.md` | PO approval through procurement chain |

### Planned Workflow Templates (From Recommended Templates)

| Template ID                 | Priority | Description                                                       |
| --------------------------- | -------- | ----------------------------------------------------------------- |
| `fa-budget-approval`        | P1       | Multi-level budget approval with board escalation                 |
| `fa-journal-entry-approval` | P1       | Preparer → Reviewer → Controller JE approval                      |
| `fa-month-end-close`        | P1       | Period close checklist with task assignment and deadline tracking |
| `fa-vendor-bill-approval`   | P2       | 3-way match verification + amount-based approval                  |
| `fa-payment-authorization`  | P2       | Payment batch approval with dual authorization                    |

***

## Form Field Lookups

FA exposes these data sources for FW form field lookups (FW-15):

| Lookup Source      | Table                   | Value Column | Label Column                          | Filter              | Used By               |
| ------------------ | ----------------------- | ------------ | ------------------------------------- | ------------------- | --------------------- |
| Vendors            | `fa_vendors`            | `id`         | `name`                                | `status = 'active'` | PO forms, bill forms  |
| GL Accounts        | `fa_accounts`           | `id`         | `account_number \|\| ' - ' \|\| name` | `is_active = true`  | Expense, JE forms     |
| Funds              | `fa_funds`              | `id`         | `fund_number \|\| ' - ' \|\| name`    | `status = 'active'` | All FA forms          |
| Projects           | `fa_projects`           | `id`         | `project_number \|\| ' - ' \|\| name` | `status = 'active'` | Expense, PO forms     |
| Cost Centers       | `pf_departments`        | `id`         | `name`                                | `organization_id`   | Expense, budget forms |
| Expense Categories | `fa_expense_categories` | `id`         | `name`                                | `is_active = true`  | Expense report form   |

***

## Platform Layer Usage

### Hooks FA Components Import

```typescript theme={null}
// 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

| Integration                   | Status     | Notes                                                                                 |
| ----------------------------- | ---------- | ------------------------------------------------------------------------------------- |
| FA events in `KnownEventName` | ✅ Partial  | Expense, budget, close events registered; bill, JE events pending                     |
| PO approval (FA-UX-05)        | 📝 Planned | Detailed contract in [FA-UX-05-FW-03-INTEGRATION.md](./FA-UX-05-FW-03-INTEGRATION.md) |
| Expense approval chain        | 📝 Planned | Form + workflow templates ready                                                       |
| Budget approval chain         | 📝 Planned | Events registered; chain config needed                                                |
| JE approval chain             | 📝 Planned | Events and chain not yet registered                                                   |
| Vendor bill approval          | 📝 Planned | Events and chain not yet registered                                                   |
| Decision tables               | 📝 Planned | No FA-specific decision tables created yet                                            |
| Form field lookups            | 📝 Planned | FA table lookup configs not yet registered                                            |
| AP automation (FA-22)         | 📝 Planned | Scan + duplicate events in EVENT\_CONTRACTS.md                                        |
| Period close workflow         | 📝 Planned | Events registered; workflow template needed                                           |

***

## Related Documentation

* [FA-UX-05 / FW-03 Integration](./FA-UX-05-FW-03-INTEGRATION.md) — PO-specific approval API contract
* [FW Cross-Core Integration Guide](../../../specs/cross-cutting/FW-CROSS-CORE-INTEGRATION-GUIDE.md) — Shared patterns
* [Event Contracts](./EVENT_CONTRACTS.md) — FA event registry
* [Cross-Core Integration Matrix](./CROSS_CORE_INTEGRATIONS.md) — Platform-wide matrix
* [Recommended Workflow Templates](../../../specs/fw/recommendations/RECOMMENDED_WORKFLOW_TEMPLATES.md) — FA templates (6)
* [FW-28 HR/FA Template Plan](../../../specs/fw/archive/FW-28-HR-FA-WORKFLOW-TEMPLATES-PLAN.md) — Implementation roadmap