Encore OS — Documentation

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 — PO-specific approval contract (this document supersedes it as the comprehensive guide). Cross-cutting guide: See FW Cross-Core Integration Guide 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

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

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 for detailed API contract)

Purpose

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

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

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

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

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

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

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

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

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

// 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
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

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

​Overview

​Integration Pattern

​Event Contracts (FA → FW)

​FA-12: Expense Management Events

​Event: fa_expense_report_submitted

Purpose

Payload Schema

Consumer Actions

​Event: fa_expense_report_approved

Purpose

Payload Schema

​FA-04: Purchase Order Events

​Event: fa_purchase_order_created

Purpose

Payload Schema

Consumer Actions

​FA-02: Vendor Bill & Journal Entry Events

​Event: fa_vendor_bill_received

Purpose

Payload Schema

​Event: fa_journal_entry_pending

Purpose

Payload Schema

​FA-08: Budget Events

​Event: fa_budget_approved

Purpose

Payload Schema

​FA-22: AP Automation Events

​Event: fa_bill_scan_completed

Payload Schema

​Event: fa_bill_duplicate_flagged

Payload Schema

​FA-19: Period Close Events

​Event: fa_close_period_started

Payload Schema

​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

​Testing Requirements

​Unit Tests

​Integration Tests

​E2E Tests

​RLS Tests

​Implementation Status

​Related Documentation

Overview

Integration Pattern

Event Contracts (FA → FW)

FA-12: Expense Management Events

Event: `fa_expense_report_submitted`

Event: `fa_expense_report_approved`

FA-04: Purchase Order Events

Event: `fa_purchase_order_created`

FA-02: Vendor Bill & Journal Entry Events

Event: `fa_vendor_bill_received`

Event: `fa_journal_entry_pending`

FA-08: Budget Events

Event: `fa_budget_approved`

FA-22: AP Automation Events

Event: `fa_bill_scan_completed`

Event: `fa_bill_duplicate_flagged`

FA-19: Period Close Events

Event: `fa_close_period_started`

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

Testing Requirements

Unit Tests

Integration Tests

E2E Tests

RLS Tests

Implementation Status

Related Documentation