# Redis ו־BullMQ

> תיעוד מקור. מקור: docs/platform/redis-bullmq.md · 6a466bf.

## Decision

Redis is an acceleration and asynchronous-work layer for LinkNodes Energy. It is **not** an application database. Supabase PostgreSQL remains the authoritative source of customer, tenant, vehicle, billing, provider and transaction state.

## Redis responsibilities

1. Short-lived cache for expensive, safely cacheable provider/reference reads.
2. BullMQ queue state for asynchronous provider work.
3. Idempotency/deduplication support for provider events and background jobs where appropriate.

Keys use lowercase colon-separated namespaces. Tenant-specific cache entries always include an explicit `tenant:<id>` segment. PII and credentials must never appear in Redis key names.

## BullMQ queues

- `provider-sync`: station catalogs, charger/fuel status, tariffs and transaction imports.
- `webhook-reconciliation`: provider webhook verification/reconciliation outside the synchronous response path.
- `billing-reconciliation`: non-interactive billing reconciliation.

Default jobs use bounded retention, five attempts and exponential backoff. Logical operations use deterministic opaque job IDs to prevent accidental duplicate enqueueing.

## Runtime boundary

Vercel request functions may enqueue work, but a BullMQ worker is a long-lived process and is not started as an ordinary request handler. The dedicated worker runtime must run the worker factory from `lib/jobs/worker.ts`, receive the same Redis TLS/ACL credential, and shut down gracefully.

Until a production Redis runtime is provisioned and `REDIS_URL` is configured, Redis and queues remain disabled and the existing Web application behavior is unchanged.

## Security

- Production requires a `rediss://` URL.
- Use a dedicated least-privilege Redis ACL user for the LinkNodes worker/application.
- Keep Redis off public unauthenticated access.
- Never commit Redis URLs, passwords, provider credentials or job payload secrets.
- Avoid `KEYS`; application cache keys are always addressable directly.
- Supabase RLS remains the tenant authorization boundary. Redis cache usage must happen only after authorization and must preserve tenant scope.

## Observability

Grafana Cloud remains the official DigitalOps monitoring platform. Export Redis/worker metrics there when the runtime connection exists. Durabull is the queue/Redis operations console for queue backlog, worker status, failed jobs, schedules and Redis health.

Current connection status at implementation time: the Durabull MCP transport is connected, but `list_connections` returns no visible Redis connections. Runtime operations therefore cannot be certified until that connection appears.

## Railway production runtime

The production Redis instance is hosted inside the Railway project `LinkNodes Energy Infrastructure`.
The Redis service stays on Railway private networking for worker traffic. The dedicated Railway BullMQ worker runs `workers/railway-bullmq-worker.mjs` and starts only the `system-smoke` queue until real provider processors are implemented.

A production `redis://` URL is accepted only when the hostname ends in `.railway.internal`; all other production Redis URLs must use `rediss://`.

The smoke worker creates one deployment-scoped job at boot, waits for completion, exposes `GET /health`, and proves Redis/BullMQ/worker connectivity without consuming business queues.
