upstash-workflow

This skill is an internal implementation guide for building Upstash Workflow and QStash asynchronous workflows inside the LobeHub codebase. It codifies the three constraints the platform imposes on background processing — rate limits that make blind fan-out dangerous, per-workflow step limits, and idempotency requirements so retries never double-process — into a repeatable pattern so engineers do not rediscover them for every new job.

The guide describes a consistent three-layer architecture: a Layer 1 entry point (process-*) that validates prerequisites, counts eligible items, filters already-processed ones, and supports a dry-run mode that returns statistics without side effects; a Layer 2 pagination layer (paginate-*) that walks cursor-based pages and fans oversized batches into smaller chunks by recursively re-triggering itself; and a Layer 3 executor (execute-*/generate-*) that processes exactly one item per invocation with flowControl for parallelism and rate limiting. It supplies full TypeScript templates for the Workflow class and each route, plus reference files for implementation, cloud setup, best practices, and two real end-to-end examples (welcome-placeholder, agent-welcome).

The intended users are LobeHub contributors and TypeScript/Next.js engineers implementing durable background jobs on Upstash. Typical use cases include batch content generation, backfills, and any fan-out job that must respect step limits and stay idempotent. It is codebase-specific guidance rather than a general-purpose library, so its value is highest for people working directly in or closely mirroring the LobeHub server structure.