ADR-0003 · Accepted · 2026-08
Why background execution belongs outside the web application
Long-running work must not share the request lifecycle of the product API.
Context
Product APIs often start imports, exports, AI jobs, reconciliations, or report generation inside the same process that serves HTTP. Under load, or after a deploy, those jobs die mid-flight. Retries become ad hoc. Operators cannot see what is running without reading application logs.
Decision
Treat execution as a separate plane. The application creates a task (or emits an event). An execution system owns scheduling, workers, logs, retries, and operator visibility.
Consequences
- One more system to run — deliberately. The cost is paid once instead of once per feature that needs background work.
- The application stays simpler: it does not become an orchestrator.
- Failure modes become inspectable: queued, running, failed, recovered.