Encore OS — Documentation

Spec: specs/fa/specs/FA-22-accounts-payable-automation.md
Status: 📝 Planned
Constitution: §1.3 (Integration Patterns), §2.1 (Integration documentation)

Overview

FA-22 adds invoice scan/OCR, duplicate detection, and 3-way match automation. It integrates with PF-27 (Platform AI), FA-03/FA-04 (bills, POs, receipts), and FW-16 (workflow events).

Integration Points (from spec)

Dependency	Pattern	Purpose
PF-27 (AI)	Platform Layer (edge function)	Document extraction in `fa-scan-invoice`; no PHI in prompts.
FA-03 / FA-04	Same core (FA)	Read fa_vendor_bills, fa_purchase_orders, fa_po_receipts; write/update fa_vendor_bills when linking scan or flagging duplicate.
FW-16	Event-Based	Publish `fa_bill_scan_completed`, `fa_bill_duplicate_flagged` for workflow subscriptions.

Event Contracts (FW-16)

Channel: fa_events (or equivalent).
Subscribers: FW-16 (Workflow Events) – register event_type values below for workflow triggers. Canonical event names use snake_case past-tense: fa_bill_scan_completed, fa_bill_duplicate_flagged. Full contracts: EVENT_CONTRACTS.md.

fa_bill_scan_completed

When: After invoice scan completes and result is stored in fa_invoice_scans. Payload schema (JSON):

Field	Type	Required	Description
event_type	string	yes	`"fa_bill_scan_completed"`
organization_id	uuid	yes	Tenant scope
timestamp	string (ISO 8601)	yes	Event time
user_id	uuid	no	When user-initiated
correlation_id	string	no	When chaining events
scan_id	uuid	yes	fa_invoice_scans.id
vendor_bill_id	uuid \| null	yes	Set when linked to bill
confidence_score	number	yes	OCR confidence
scanned_text	string	no	Optional extracted text
scan_status	string	no	e.g. success, partial
source_system	string	no	e.g. fa-scan-invoice
metadata	object	no	Extra key-value

Example payload:

{
  "event_type": "fa_bill_scan_completed",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-12T12:00:00Z",
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "scan_id": "770e8400-e29b-41d4-a716-446655440002",
  "vendor_bill_id": null,
  "confidence_score": 0.92,
  "scan_status": "success",
  "source_system": "fa-scan-invoice"
}

fa_bill_duplicate_flagged

When: After duplicate detection creates a fa_duplicate_detection_log entry. Payload schema (JSON):

Field	Type	Required	Description
event_type	string	yes	`"fa_bill_duplicate_flagged"`
organization_id	uuid	yes	Tenant scope
timestamp	string (ISO 8601)	yes	Event time
user_id	uuid	no	When user-initiated
correlation_id	string	no	When chaining (e.g. batch)
vendor_bill_id	uuid	yes	Bill that was flagged
suspected_duplicate_of_id	uuid	yes	Existing bill it matches
match_score	number	yes	Similarity score
match_reason	string	yes	Short reason
log_id	uuid	yes	fa_duplicate_detection_log.id
invoice_id	string	no	Invoice number if available
detected_duplicates	array	no	Optional list of match ids
source_system	string	no	e.g. fa-detect-duplicates
metadata	object	no	Extra key-value

Example payload:

{
  "event_type": "fa_bill_duplicate_flagged",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-12T12:05:00Z",
  "vendor_bill_id": "880e8400-e29b-41d4-a716-446655440003",
  "suspected_duplicate_of_id": "990e8400-e29b-41d4-a716-446655440004",
  "match_score": 0.98,
  "match_reason": "Same vendor, amount within 2%, date within 30 days",
  "log_id": "aa0e8400-e29b-41d4-a716-446655440005",
  "source_system": "fa-detect-duplicates"
}

API / Edge Functions

fa-scan-invoice: Invokes PF-27 for extraction; writes to fa_invoice_scans and storage bucket fa-invoice-scans. No direct API contract with other cores; called from FA UI.
fa-detect-duplicates: Runs on bill insert or cron; writes fa_duplicate_detection_log. Internal to FA.
fa-auto-match-3way: Returns suggested matches for PO-Receipt-Bill; internal to FA or called from FA UI.

Security & Tenant Isolation

All FA-22 tables and storage bucket are scoped by organization_id.
PF-27 calls use edge function only; no PHI in prompts (anonymized identifiers if needed).
Event payloads include organization_id for subscriber filtering.

Cross-Core Integration Matrix

See CROSS_CORE_INTEGRATIONS.md: FA → FW-16 (Event) for fa_bill_scan_completed and fa_bill_duplicate_flagged.

PF-100: Platform Ambient Transcription & AI Note Generation — Integration Contract / GR-UX-10: Contract Management and Contract Creation Wizard Integration

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

Accounts Payable Automation – Integration

Overview

Integration Points (from spec)

Event Contracts (FW-16)

fa_bill_scan_completed

fa_bill_duplicate_flagged

API / Edge Functions

Security & Tenant Isolation

Cross-Core Integration Matrix

​Overview

​Integration Points (from spec)

​Event Contracts (FW-16)

​fa_bill_scan_completed

​fa_bill_duplicate_flagged

​API / Edge Functions

​Security & Tenant Isolation

​Cross-Core Integration Matrix

Overview

Integration Points (from spec)

Event Contracts (FW-16)

fa_bill_scan_completed

fa_bill_duplicate_flagged

API / Edge Functions

Security & Tenant Isolation

Cross-Core Integration Matrix