ADR-0002. Mode-based deployment (FULL / API / WORKER)
| Field | Value |
|---|---|
| Status | Accepted |
| Date | 2026-02-05 |
| Deciders | payment-team, SRE |
| Supersedes | — |
Context
- Payment service handles two distinct workloads:
- REST + IPN ingestion — synchronous, latency-sensitive, scales with provider traffic.
- BullMQ workers — asynchronous (scheduler + confirmation), scales with queue depth.
- Running both in one process limits independent scaling and amplifies crash blast radius.
- However, dev environments need everything in one pod.
Decision
Single image, three deployment modes selected via APP_ENV_MQ_PAY_MODE:
| Mode | Controllers | Queue producer | Workers | Use case |
|---|---|---|---|---|
FULL (default) | ✓ | ✓ | ✓ | Dev — single pod |
API | ✓ | ✓ | ✗ | Production REST tier — scale by request rate |
WORKER | ✗ | ✗ | ✓ | Production worker tier — scale by queue depth |
Production pattern: 1× API + N× WORKER. Each WORKER pod must have a unique APP_ENV_NODE_ID (Snowflake worker ID = 91, 92, …).
Consequences
| Pros | Cons |
|---|---|
| REST and worker scale independently | Three deployment manifests to maintain |
| Worker crashes don't take down API | Shared encryption key requirement (APP_ENV_APPLICATION_SECRET) |
| Dev still uses single pod (FULL) | WORKER pods need unique snowflake IDs — error-prone |
| Standard "API + worker" topology | Mode mismatch can cause silent dead queue |
Alternatives Considered
| Option | Pros | Cons | Why rejected |
|---|---|---|---|
| Single mode (always full) | Simpler ops | Can't scale REST and workers independently | Wrong tradeoff for production |
| Separate API and WORKER images | Clear boundary | Build pipeline complexity; image drift risk | Single-image-multi-mode is industry standard |
| Stateless workers without BullMQ | No Redis dependency | No retry / scheduler / persistence | mq-pay needs queue semantics |
References
@nx/mq-pay/src/common/constants.ts:11-14(MQPayRunModes)@nx/mq-pay/src/component.ts:437-444(mode validation)src/components/payment.component.ts:124-125(mode resolution)