External Command Outbox

Summary

External commands separate deciding to perform a side effect from executing it. That separation is essential when side effects touch accounting, procurement, email, or provider systems.

Problem

Inline external writes make retries dangerous. A request can succeed outside the platform and fail internally, leaving no clear way to resume safely.

Principle

Represent external writes as durable commands with eligibility, dependencies, attempts, results, and operator affordances.

Platform Shape

The shared workflow command package provides generic command concepts. POA uses command rendering and dispatch for ServiceTitan, Spectrum, and QuickBooks Online side effects. Marketing runtime actions use a similar outbox posture for post-render and transition-triggered actions.

Source Evidence

• services/workflow/commands
• services/poa/commands
• services/marketing/runtime/actions
• jobs/poa/dispatch_external_commands

Related Reading

• docs/engineering/concepts/idempotency-in-operational-jobs.md
• docs/engineering/reference/quickbooks-online-integration.md