DEV Community: Kjudeh

An AI receptionist on a real WhatsApp number: architecture, routing logic, and failure modes

Kjudeh — Tue, 25 Aug 2026 21:13:39 +0000

In most of the Gulf and Levant, WhatsApp isn't a support channel — it's the front desk. Customers ask prices, book appointments, and choose between competitors based on who answers first. Which makes the default setup remarkable: a human checking a phone between tasks, going silent at 8pm.

This post walks through the architecture of a self-hosted AI receptionist on a normal WhatsApp number — what the pieces are, why each exists, and the failure modes to design around. At the end there's a one-click version if you'd rather skip the assembly.

The architecture

Four services:

WhatsApp ⇄ Evolution API → webhook → n8n workflow → LLM (Claude/GPT)
                ↑                        │
                └── send reply ──────────┘
        Postgres (sessions, messages) · Redis (instance cache)

Evolution API (9k★) speaks the WhatsApp Web protocol — you pair it with a QR scan like WhatsApp Web, and it exposes a REST API + webhooks for messages.
n8n hosts the receptionist logic as a visual workflow: filter → route → LLM call → reply.
Postgres + a small volume persist the session, so redeploys don't ask you to re-scan the QR code.
The LLM is yours — an Anthropic or OpenAI key, with the business context in the system prompt.

The routing logic that makes it a receptionist (not a toy)

The naive version — "forward every message to an LLM" — fails in production within a day. The workflow needs four branches:

1. Ignore what should be ignored. Group messages, your own outgoing messages, non-text payloads. Skipping this floods your LLM bill and spams groups.

2. Human handoff, on a keyword. When a customer types "human" (or your word of choice), the bot acknowledges, stops replying in that thread, and notifies your team. An AI that traps customers in bot-loop hell costs more goodwill than it saves labor.

3. Office-hours awareness. Out of hours, an instant "we're closed, here's when we open, leave your message" beats an AI improvising commitments at 3am.

4. Only then, the LLM. With a system prompt carrying the business's real facts (services, prices, policies, tone), a length cap, and instructions to offer the handoff word when unsure. Bilingual businesses: prompt it to answer in the customer's language — Arabic in, Arabic out.

Deployment failure modes to design around

Session loss. If WhatsApp auth lives only in the container, every redeploy needs a QR re-scan. Persist sessions in Postgres and a volume.
Version drift. Pin images by digest. (If you use Evolution API specifically: stay on the v2.3.x line — v2.4.0+ requires a license activation.)
The unofficial-client caveat, honestly: this rides the WhatsApp Web protocol, not the official Business API. Meta can restrict accounts that spam. Use a dedicated number, answer inbound rather than broadcasting, and use the official API for regulated workloads.

The one-click version

We packaged this exact architecture — Evolution API (pinned v2.3.7), n8n with the four-branch receptionist workflow pre-loaded and auto-activated, Postgres, Redis, session persistence — as an open-source (MIT) Railway template:

Deploy: https://railway.com/deploy/whatsapp-ai-receptionist?referralCode=qxxcuG
Source + workflow JSON: https://github.com/Kjudeh/whatsapp-ai-receptionist

Deploy, paste an LLM key, scan one QR code, and message your own number.

And if you'd rather have it done for you — installed on your number, persona tuned to your business in Arabic and English, live in 48 hours, optionally managed — that's what we do at Bubbles Studio.

Questions welcome in the comments — and the repo takes issues and PRs.

Running n8n in production: queue mode, workers, and the settings that keep it alive

Kjudeh — Tue, 25 Aug 2026 19:21:55 +0000

Self-hosted n8n has a failure mode almost everyone hits eventually: everything runs fine for months, then one day the editor won't load, webhooks time out, and workflows silently stop. It's rarely a mystery when you dig in — it's almost always one of two things:

Single-instance execution. By default, n8n executes workflows in the same process that serves the UI and receives webhooks. One heavy execution (a big loop, an AI agent chain, a large file) and everything else starves.
The unbounded executions table. Every run writes execution data to your database. With no pruning, the table grows until Postgres becomes the bottleneck — or the disk fills.

Both have first-class fixes in n8n itself. They're just not the defaults. This post walks through the production setup n8n's own docs recommend — queue mode — plus the hardening settings that prevent the slow-motion failures.

How queue mode works

In queue mode, n8n splits into two roles:

The main instance serves the editor UI, receives webhooks, and manages schedules — but executes nothing. When a workflow should run, it pushes a job onto a Redis queue (Bull).
One or more workers pull jobs from the queue and execute them.

Webhook/schedule → main instance → Redis queue → worker(s) → Postgres

The practical consequences:

A heavy execution can't freeze your editor or drop incoming webhooks — intake and execution are different processes.
Scaling is horizontal: more load → more worker replicas. Workers are stateless (all state lives in Postgres), so replicas "just work".
A worker crash loses nothing: queued jobs are picked up when a worker returns.

The core configuration

Both main and workers share most configuration. The critical rule: main and workers must run the same n8n version and the same encryption key, or credentials break in confusing ways.

# Shared by main + workers
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=<postgres-host>
DB_POSTGRESDB_DATABASE=<db>
DB_POSTGRESDB_USER=<user>
DB_POSTGRESDB_PASSWORD=<password>
N8N_ENCRYPTION_KEY=<same value everywhere!>

EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=<redis-host>
QUEUE_BULL_REDIS_PORT=6379
QUEUE_BULL_REDIS_PASSWORD=<redis-password>

# Main instance only
N8N_WEBHOOK_URL=https://your-domain/
OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true

# Workers: start with `n8n worker`; enable its health endpoint
QUEUE_HEALTH_CHECK_ACTIVE=true

The worker is the same image/binary started with n8n worker — it connects to the same Postgres and Redis and begins consuming jobs (default concurrency: 10 parallel executions per worker).

The hardening most setups skip

Execution pruning. This is the one that kills instances. Cap the history:

EXECUTIONS_DATA_PRUNE=true
EXECUTIONS_DATA_MAX_AGE=336        # keep 14 days
EXECUTIONS_DATA_PRUNE_MAX_COUNT=50000

Database backups you can actually restore. Workflows, credentials, and history all live in Postgres — it's the single point of loss. A compressed nightly pg_dump to any S3-compatible bucket costs cents; the part people skip is verifying restores. A backup you've never restored is a hope, not a backup.

Boring but worth setting: N8N_DIAGNOSTICS_ENABLED=false (telemetry off), pin your n8n image by version and digest so main and workers can never drift apart, and keep Postgres/Redis off the public internet.

Scaling checklist

When executions start queuing up:

Add worker replicas (they're stateless — this is safe).
Watch Postgres — execution writes are the next bottleneck; pruning keeps it manageable.
Only then think about the main instance — it rarely needs scaling, since it executes nothing.

The one-click version

If you'd rather not assemble this by hand: we packaged this exact architecture — main + worker on a single digest-pinned image, Redis, Postgres, pruning defaults, and S3 database backups wired in — as an open-source (MIT) Railway template:

Deploy: https://railway.com/deploy/n8n-production-stack-queue-mode
Source: https://github.com/Kjudeh/n8n-production-stack

Full disclosure: we (Bubbles Studio) built and maintain it — versions are bumped through weekly reviewed PRs and the stack is test-deployed from scratch before every update. Everything in this post applies to it 1:1, because it is this post's architecture.

Questions about queue mode or the template — comments are open, and so are issues on the repo.

Your PostgreSQL Backups Are Probably Broken (Here's How to Know for Sure)

Kjudeh — Thu, 19 Feb 2026 05:17:25 +0000

73% of backup restores fail in production.

Not because the backup software broke. Because no one tested the restore.

I've been running PostgreSQL in production for years. I've seen teams religiously back up their databases every hour, upload to S3, check the green checkmark, and sleep soundly. Then disaster hits, they try to restore, and... nothing works. Corrupted dumps. Wrong permissions. Missing extensions. Schema drift.

The backup worked. The restore didn't. And they only found out when it mattered most.

The Problem With "Just Back It Up"

Most backup setups look like this:

pg_dump → gzip → S3 →✓ done

That checkmark is a lie. It tells you the file uploaded. It doesn't tell you:

Can this dump actually be restored?
Will the data be intact?
Do the row counts match?
Are the indexes valid?

You don't know until you try. And most teams never try until it's too late.

The Fix: Automated Restore Verification

I built a backup system that doesn't just dump and pray. Every day, it:

Downloads the latest backup from S3
Restores it to an isolated verification database
Runs integrity checks (table counts, row validation, custom queries)
Reports success or failure
Cleans up automatically

If the restore fails, I know immediately — not when production is on fire.

How It Works

The system has two services:

Backup Service — Runs pg_dump on a schedule (default: hourly), compresses with gzip, uploads to any S3-compatible storage. Handles retention automatically.

Verify Service — Downloads backups daily and restores them to a separate PostgreSQL instance. Runs sanity checks. Proves the backup works.

Both run as lightweight containers. Works with AWS S3, Backblaze B2, Cloudflare R2, DigitalOcean Spaces, Wasabi, or MinIO.

One-Click Deploy on Railway

If you're running PostgreSQL on Railway, you can deploy this in minutes:

Just add your database URL and S3 credentials. The services start working immediately.

What you get:

Hourly backups to S3 (configurable)
Daily restore verification
7-day retention (configurable)
AES-256 encryption (optional)
Slack/Discord alerts on failure
Zero maintenance after setup

The Code

Fully open source:

GitHub: github.com/Kjudeh/railway-postgres-backups

Works with Docker, docker-compose, or any container platform — not just Railway.

Stop Hoping. Start Verifying.

Every backup you haven't restored is a backup you can't trust.

Set up automated verification once. Sleep better forever.

Questions? Drop a comment or open an issue on GitHub.