When to use workflows
| Use case | Example |
|---|---|
| Async / background processing | File uploads, image transformations, email sends |
| Scheduled jobs | Daily report generation, hourly metrics collection |
| Long-running multi-step processes | Order fulfillment, onboarding sequences |
| Data pipelines (ETL) | Extract from external APIs, transform, and load into the app database |
| Cross-service data aggregation | Combining Shopify orders with Mixpanel events, enriching CRM contacts |
| Durable workflows | Processes that handle pagination, rate limiting, and conditional branching |
| AI-driven data processing | Agent-generated workflows for large-scale analysis that exceeds LLM context limits |
When not to use workflows
- Simple queries returning fewer than 1,000 rows — use a direct backend procedure
- Single-service operations that complete in seconds
- Real-time data that must be fresh on every request
The precompute pattern
The most common workflow pattern fetches data from external services, transforms it, and persists the results to the app’s database. The app then serves data directly from its database instead of calling services on every request: This eliminates API latency from user-facing requests and enables complex aggregations that would be impossible in a single HTTP request.How workflows fit into the platform
- Apps define workflows in
src/server/workflows/and schedule them viaschedules.json - Services provide the API integrations that workflow steps call
- The Workflows Framework provides a query engine for data transformation
- The worker service executes steps that call services, transform data, and read and write data to and from app databases
Next steps
- Defining workflows — workflow structure and step configuration
- Step types — importFromDatabase, serviceCall, sql, persistToDatabase, conditional, waitFor
- Step modifiers — pagination, forEach, fieldMapping, dataPath, variables
- Scheduling — cron-based recurring workflows
- Error handling — retries, checkpointing, and idempotency
- Execution — worker architecture, concurrency, and data storage