> ## Documentation Index
> Fetch the complete documentation index at: https://synthetiq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows Framework overview

> Durable background workflows for async processing, scheduled jobs, multi-step pipelines, and data aggregation

The Synthetiq Workflows Framework provides durable background execution for anything that shouldn't block a user request. Workflows are defined as directed acyclic graphs (DAGs) of steps where each step runs independently with built-in idempotency, retries, and error handling.

## 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:

```mermaid theme={null}
graph LR
    subgraph Workflow
        A[Fetch from APIs] --> B[Transform with SQL] --> C[(DB)]
    end
    subgraph App
        C --> D[Dashboard]
    end
```

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 via `schedules.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](/docs/platform-docs/workflows-framework/defining-workflows) — workflow structure and step configuration
* [Step types](/docs/platform-docs/workflows-framework/steps/import-from-db) — importFromDatabase, serviceCall, sql, persistToDatabase, conditional, waitFor
* [Step modifiers](/docs/platform-docs/workflows-framework/pagination) — pagination, forEach, fieldMapping, dataPath, variables
* [Scheduling](/docs/platform-docs/workflows-framework/scheduling) — cron-based recurring workflows
* [Error handling](/docs/platform-docs/workflows-framework/error-handling) — retries, checkpointing, and idempotency
* [Execution](/docs/platform-docs/workflows-framework/execution) — worker architecture, concurrency, and data storage