Skip to main content

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.

Version: 1.0.0
Last Updated: 2026-03-19
Owner: Platform / FW (cross-cutting)
Related: EVENT_CONTRACTS.md, FW_BUSINESS_AUTOMATION_WORKFLOW_RECOMMENDATIONS.md (R-FW-12) This document explains which delivery mechanism to use when integrating features with domain events, automations, and workflows. It does not replace per-spec payloads; use EVENT_CONTRACTS for event names and schemas.

​
1. Table-driven path (FW automation / workflows)

Flow (high level): publishEvent() (client or server) → fw_domain_events → DB trigger fw_process_domain_event() → matching automation rules / workflow definitions → fw_workflow_executions rows in queued (and pgmq enqueue per FW-46) → workflow-executor-worker processes steps. Use when:
  • You need durable, retried execution with DLQ (FW-47), checkpoints (FW-48), and execution timeouts (FW-49).
  • Triggers are registered against fw_workflow_events / FW-16 event names.
Do not use for: Fire-and-forget UI-only updates (use realtime instead).

​
2. HTTP event-consumer path

Flow: supabase.functions.invoke('event-consumer', { body: { event_type, payload, ... } }) (or equivalent server-side invoke) → handlers registered for that consumer. Use when:
  • You need immediate side effects (e.g. cross-core notifications, lightweight transitions) where FW’s queued execution model is unnecessary.
  • Handlers are idempotent where possible; consider that this path may not offer the same DLQ/checkpoint guarantees as FW-46 unless you add them explicitly.
When to add handlers: When a core needs synchronous-style reactions to an event type that is not modeled as an FW automation trigger, or when migrating legacy pg_notify consumers.

​
3. Realtime path (UI only)

Mechanisms: Supabase Postgres Changes, Broadcast, or app-level subscriptions. Use when:
  • Screens and dashboards must refresh when data changes.
  • You want low-latency UX without polling.
Never use for: Authoritative server-side routing of business logic, payment, or compliance-critical chains. Realtime delivery is best-effort from the UI perspective; durable work belongs in §1.

​
4. External delivery (webhooks / outbound)

Flow: Platform event subscriptions (e.g. PF-35 webhooks) forward selected events to external systems. Use when:
  • A vendor, data warehouse, or partner needs outbound notification.
  • You have contracts and retries appropriate for external HTTP (timeouts, signing, secret rotation).

​
5. Decision tree

QuestionIf yes →
Must the action survive restarts and support DLQ / step replay?§1 Table-driven (FW-46+)
Is it only to refresh a React view?§3 Realtime
Is it outbound to a third-party URL with subscription management?§4 External / PF-35
Is it a one-off server reaction with no workflow?§2 HTTP consumer (evaluate idempotency)

​
6. FW-49 / FW-47 events in the catalog

Timeout and DLQ operational events (e.g. workflow.execution.timed_out, DLQ threshold alerts) are documented in EVENT_CONTRACTS.md. They complement the table-driven path: timeouts and permanent failures are detected by scheduled/worker logic and recorded or notified per FW-49 / FW-47.

​
See also