Example scope & report

# n8n: decide when to introduce queue mode

An architecture decision for a self-hosted automation team

[← All services](/services)

Public reference: n8n. Independent example based on public documentation. Not commissioned by or affiliated with n8n.

[Download all 7 reports (PDF) ↓](/examples/upserto-example-reports.pdf)[Download Markdown ↓](/examples/architecture-decision.md)

## Decision brief

Recommended next decision

| Question | Recommendation |
| --- | --- |
| Decision | Choose n8n queue mode only after the workload and operating model justify it. |
| Why it matters | More workers can amplify database or provider contention instead of removing the bottleneck. |
| Acceptance | The decision names the limiting resource, operational cost and a rehearsed recovery path. |
| Scope boundary | Selected customer-owned workflows and deployment; capacity or cost savings require measurement. |

## The proposed engagement

Proposed brief: an operations team runs self-hosted n8n and sees long-running workflows overlap with incoming webhook work. It is considering queue mode. Upserto would measure the actual constraint, compare the current deployment with a main/Redis/worker topology, and prepare an implementation decision with operating costs and a rollback plan. Queue mode would be recommended only if the workload and team can justify the extra components.

Inputs required. Deployment/configuration; representative workflows; execution history; database/Redis constraints; operations coverage.

## System boundary and assumptions

The reference is n8n’s public queue-mode documentation: a main instance coordinates triggers, Redis carries execution work and workers run executions using shared database state. The proposed assessment covers the customer deployment and selected workflows, not an audit of n8n. Required evidence includes execution duration, concurrency, database waits, binary-data handling and the team’s recovery responsibilities.

## How Upserto would approach it

First separate workflow wait time from CPU, database and provider latency. Compare tuning the existing deployment with introducing workers; do not attribute every slow workflow to worker capacity. Inventory credentials/encryption configuration, binary data and version-specific constraints. Cost the recovery and monitoring work alongside application changes. Record conditions that would reverse the decision.

## What the team would receive

- A short architecture decision record with measured evidence and option trade-offs.

- A deployment/dependency plan and capacity assumptions to validate.

- A rehearsal checklist, operational ownership and rollback/queue-drain procedure.

Compare topology against the operating constraintQueue mode changes the deployment and recovery responsibilities. The choice should follow a representative workload baseline, not an assumed throughput gain.Left: existing regular mode · Right: proposed queue-mode option · Dashed: shared database dependency

Read the diagram- Regular mode keeps execution and trigger handling in the main deployment.

- Queue mode introduces Redis and workers, with shared configuration and database dependencies.

- Choose after measuring the constraint and rehearsing credentials, binary-data handling and recovery.

## Starting point and proposed change

Items to inspect in the customer integration, the proposed control and the evidence needed for acceptance.

Design comparison

| Control | Inspect first | Proposed change | Acceptance evidence |
| --- | --- | --- | --- |
| Scaling decision | Review a worker proposal without a baseline. | Choose against measured resource and workflow constraints. | Baseline and decision criteria are recorded. |
| Dependencies | Review application-only implementation estimates. | Include Redis, workers, credentials and binary storage. | Representative worker rehearsal succeeds with the agreed configuration. |
| Recovery | Review restart-as-recovery assumptions. | Owned pause, drain and resume procedure. | Failure rehearsal records execution state and duplicate-effect handling. |

## Decisions and approval owners

Decisions to agree before implementation

| Decision | Proposed default | Approval owner |
| --- | --- | --- |
| Topology | Compare tuning the current instance with main/Redis/worker mode against the same workload. | Engineering lead |
| Operational readiness | Name the operator, confirm storage and credentials configuration, and rehearse pause and recovery. | Platform + operations owners |

## Review questions and implementation risks

P1 Resolve before releasing the affected workflow, or record an explicit acceptance decision. P2 Assign an owner and an agreed follow-up milestone; do not leave the item unowned.

### ADR-01 · P1 · Is queue capacity the actual bottleneck?

If time is spent waiting on a database lock or external rate limit, extra workers can increase contention instead of resolving it.

Proposed approach. Measure a representative workflow set and separate resource limits from external waits before choosing worker count.

### ADR-02 · P1 · Are shared configuration and storage ready for workers?

Queue mode adds dependencies and has documented binary-data storage constraints. A topology diagram alone does not establish that workflows can run on another process.

Proposed approach. Inventory database, Redis, encryption/credentials configuration and binary data. Confirm the deployed version and any edition-specific capabilities before the proposal is costed.

### ADR-03 · P2 · Can the team pause and recover the new topology?

More instances introduce more failure and recovery paths. The team needs to know how running and queued work behaves during maintenance.

Proposed approach. Assign an operator, rehearse worker loss and define stop, drain and rollback steps. Do not promise replay correctness without checking workflow side effects.

## Example technical output

Proposed architecture decision template

```text
decision: pending_workload_and_operational_evidence
option_A: tune_current_deployment
option_B: queue_mode_main_redis_workers
measure: execution_age + concurrency + DB_waits + provider_delay
check: credentials_config + binary_storage + version_constraints
rollout_gate: representative_worker_and_recovery_rehearsal
revisit_when: measured_constraint_or_operating_cost_changes
execution_result: TO_VERIFY
```

## Delivery plan and ownership

Proposed action plan

| Priority | Review item | Accountable role | Acceptance gate |
| --- | --- | --- | --- |
| P1 | ADR-01 | Engineering lead | A baseline names the limiting resource and the representative workload used. |
| P1 | ADR-02 | Platform + workflow owners | A separate worker completes the agreed workflow and its binary-data path in a rehearsal. |
| P2 | ADR-03 | Operations owner | A named operator can pause, inspect and recover the agreed execution without an unintended duplicate effect. |

## Acceptance checks

Run these checks before accepting the proposed changes.

Acceptance checks

| Scenario | Required evidence / expected behavior | Status |
| --- | --- | --- |
| Representative busy workflow set | Baseline separates queue, database and provider waits | To verify |
| Workflow runs on a separate worker | Credentials and agreed binary-data behavior work as intended | To verify |
| Worker stops during an external call | Execution state and duplicate-effect recovery are understood | To verify |
| Maintenance pause and rollback | Named operator follows the agreed drain/recovery procedure | To verify |

## Rollout and recovery

Make the decision record before changing topology. If queue mode is justified, rehearse the exact version and dependencies in an isolated environment, then begin with an agreed workflow scope. Define how new triggers pause and existing work drains. Monitor execution age and downstream completion, not only process health.

## Handover and limits

The team would receive the option comparison, baseline, configuration plan and operating guide. Queue mode is a documented capability; the right configuration and its benefit depend on the customer’s workload. The proposal makes no throughput or cost-saving claim before measurement.

## Access and evidence handling

Controls for the agreed engagement

| Area | Required control |
| --- | --- |
| Access | Review deployment settings and redacted execution metadata before requesting workflow payloads. |
| Secrets | Keep credential values and encryption keys out of the decision record; reference approved configuration names. |
| Evidence | Agree retention for execution samples and remove unnecessary personal or customer content. |

## Public documentation used

The sources below establish product capabilities and API contracts. The implementation choices above are Upserto’s proposed approach for a customer integration.

- [n8n: Enable queue mode ↗](https://docs.n8n.io/deploy/host-n8n/configure-n8n/scaling/enable-queue-mode.md)Documents main/Redis/worker flow, shared configuration and binary-data storage constraint.

Discuss the same kind of work for your system, with an agreed scope and acceptance criteria.

[Explore IT consulting and delivery planning ↗](/services/it-consulting)[Discuss a similar scope ↗](/contact)

Contact: [hello@upserto.com](mailto:hello@upserto.com)