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

# Conditional Approval Routing — Integration

> Status: \U0001F4DD Planned -conditional-approval-routing.md Last Updated: 2026-03-22

**Status:** 📝 Planned\
**Spec:** [FW-54-conditional-approval-routing.md](../../../specs/fw/archive/FW-54-conditional-approval-routing.md)\
**Last Updated:** 2026-03-22

## Purpose

FW-54 selects `fw_approval_chains` at approval submission time using prioritized routing rules (`fw_approval_routing_rules`), optionally driven by FW-45 decision tables and FW-17 conditions. It extends FW-34 without changing cross-core boundaries: consuming cores (FA, HR, RH, etc.) continue to submit approvals through existing platform/workflow entry points.

## Architecture Pattern

* **Pattern:** Intra–Forms & Workflow core + Platform (PF-10 notifications, PF-30 permissions).
* **No new cross-core imports:** Entity types such as `fa_expense_reports` are string identifiers in routing configuration; resolution uses tenant-scoped data access from FW approval submission context.

## Dependencies

| Component | Role                                             |
| --------- | ------------------------------------------------ |
| FW-34     | Chains, steps, requests, assignments, escalation |
| FW-45     | Decision table evaluation for chain id output    |
| FW-17     | Condition JSON format for linear rules           |
| FW-35     | SLA / timer alignment for fallback               |
| PF-10     | Notify fallback assignees                        |
| PF-30     | `fw.approval_routing.manage`                     |

## Data Flow (High Level)

1. Caller submits approval for `entity_type` + entity payload (existing FW-34 flow).
2. Router loads active `fw_approval_routing_rules` for `(organization_id, entity_type)` ordered by `priority`.
3. First match: either FW-17 condition evaluates true against payload, or FW-45 table returns `target_chain_id`.
4. If none match: select default chain (`is_default`, `applies_entity_type`).
5. Persist `routing_rule_id`, optional `routing_decision_table_id`, `routing_matched_conditions`, `routing_evaluated_at` on `fw_approval_requests`.

## Events

No mandatory new domain events for MVP. Optional future: extend `fw_approval_history` event types for `routing_evaluated` / `fallback_activated` — align with [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md) when implemented.

## Security & Tenancy

* All rows scoped by `organization_id`; RLS via `fw_has_org_access`.
* Dynamic approver resolution: SECURITY DEFINER helper with **allowlisted** lookup tables only.
* Routing snapshots must not store PHI; admin guide documents allowed field classes.

## API / Edge Functions

* **approval-escalation** (existing): extend to honor FW-54 fallback semantics where configured; avoid duplicate cron jobs.
* No new public REST surface required for MVP beyond existing Supabase access patterns.

## Consumer Cores (Read-Only Reference)

FA, HR, RH integration guides should reference FW-54 when documenting amount-based or category-based approval routing:

* [FA-FW Integration](./FA-FW-INTEGRATION.md)
* [HR-FW Integration](./HR-FW-INTEGRATION.md)
* [RH-FW Integration](./RH-FW-INTEGRATION.md)

(Update those docs in the documentation task when routing ships.)

## Contract Validation

Use [CONTRACT\_VALIDATION\_CHECKLIST.md](./CONTRACT_VALIDATION_CHECKLIST.md) when adding events or external APIs in later phases.