Search, Cache and Background Jobs

Cache, search, queues and scheduled jobs do different work. Choose their configuration from the features you need, then test how the application behaves when each service stops responding.

On this page

Search and cache

SearchService coordinates the registered search strategies and excludes those unavailable in the current configuration. Check the requirements of the strategy you choose. CacheService stores reusable results through a selected strategy. Include tenant and organization context in cache keys where the result depends on them.

Architecture in practiceA web request and a background job use separate processes

Application processHandles browser requests

queues a job

QueueAsync strategy

takes a job

Worker processExecutes background work

PostgreSQLBoth processes may use scoped records

External APICalled by an integration job

Cache and search are separate services selected for the enabled features. A running web process does not prove that the worker is running.

Code and documentation

src/service.ts · src/service.ts

Jobs that run in the background

The queue configuration selects local or asynchronous execution. Asynchronous work needs a running worker and a retry policy. A scheduler starts recurring work; it does not remove the need to inspect failed runs or prevent repeated business effects.

Code and documentation

src/factory.ts · services/schedulerService.ts

The same symptom can have different causes

What you see	What to inspect
An edited record still shows its old value	Compare the database with the cached response. Check the cache key, expiry and invalidation after a write.
The record opens by ID but is missing from search	Check the enabled search strategy, index update and access filters used by the search.
The form succeeds but an export stays pending	Check queue selection, worker process, job age and the last failure. The web server can remain healthy while the worker is stopped.

Code and documentation

src/service.ts · src/service.ts · src/factory.ts

What a background job needs

A worker does not have the browser’s session. Pass the record identifier and the tenant and organization needed to retrieve it safely. Decide whether the job should read current data when it starts or use a saved snapshot from the moment it was queued. Those choices matter if an order changes while waiting.

Keep provider credentials on the server. Include an operation identifier in logs so a queued job, its retry and the external response can be traced together. Redact secrets and avoid copying the full customer payload into logs.

Code and documentation

src/factory.ts · api/scoped.ts

Example: a nightly product sync

Choose which system supplies the current product data and how records are matched.
Save progress so an interrupted run can resume without duplicating records.
Record failures without logging credentials or unnecessary customer data.
Compare source and destination after the run, including missing and rejected records.

Code and documentation

src/factory.ts · services/schedulerService.ts

An operating checklist

Stop a worker, interrupt a provider request and restore a backup in a test environment. Confirm how failures are detected, who receives the alert and which data is needed to resume. List application, database, file and key backups separately.

Code and documentation

src/factory.ts

Sources

Open Mercato source used in these explanations