worker

Home Helper — Background Worker

The background job processor for Home Helper, a full-stack booking platform for on-demand home services. Built with Node.js, TypeScript, BullMQ, and Prisma, this service consumes jobs enqueued by the back-end API and runs everything that shouldn't block an HTTP response. See the root README for how this service fits into the overall platform.

What this service does

• Runs one BullMQ worker per job type, each consuming from its own Redis-backed queue
• Status notification jobs — notify internal staff by WhatsApp/email when a booking's status changes
• Cart-abandonment recovery — detects bookings stuck at checkout and triggers a recovery flow
• Platform/CRM reprocessing — retries failed CRM/sales-funnel sync actions
• Shares the same PostgreSQL database and Prisma schema as the back-end API, so it can read/update booking state directly

Tech stack

Node.js · TypeScript · BullMQ · Redis · Prisma ORM · PostgreSQL · Nodemailer · tsyringe (DI) · Pino (structured logging)

Architecture

src/worker.ts is the entrypoint: it connects to Postgres and Redis, then boots one BullMQ Worker per job exported from src/modules/jobs/index.ts. Adding a new background job means creating a new folder under src/modules/jobs/, exporting { name, jobFunction }, and re-exporting it from that index — no other wiring required.

src/jobBuilder.ts is a manual entrypoint for enqueuing/testing a job by hand against the shared Redis queue.

External integrations (payment gateway, WhatsApp/messaging, CRM) reuse the same Factory/Resolver/Provider adapter pattern as the back-end service under src/modules/providers/.

Getting started

# Install dependencies
yarn install

# Copy the example env file and fill in your own values
cp .env.example .env

# Start the worker in watch mode
yarn worker

Available scripts

Script	What it does
yarn worker	Start all job workers in watch mode (nodemon + tsx)
yarn job-builder	Manually enqueue a job for local testing
yarn build / yarn start	Compile to dist/ and run the compiled output
yarn db:generate / db:migrate:dev / db:migrate:deploy / db:seed / db:view	Prisma commands against the shared database

Environment variables

See .env.example. Requires DATABASE_URL and REDIS_URI at minimum, plus mail/WhatsApp/CRM credentials matching whatever the back-end API is configured with.