Most applications should spend their time at the workflow layer. The sections below explain how that layer works and where the lower-level escape hatches fit.

Workflow shape stays visible

This example is more representative of the kinds of multi-step workflows ProviderPlane is meant to model. The important point is that the shape stays explicit instead of disappearing into provider calls and helper functions.

Representative workflow shape

See corresponding example

The main pieces

• Use the workflow layer by default. It is the clearest way to keep the graph, dependencies, and output shape visible in application code.

Dependencies and outputs

Dependencies and outputs are explicit. That is what keeps a workflow understandable once it grows beyond a few isolated provider calls.

• Use source when one step actually consumes the output of another. Use after when a step only needs ordering.
• Typed step handles keep those references readable, and output(...) turns intermediate step results into the final application-facing shape.

Execution and persistence

Provider chain behavior and persistence are part of the workflow system too. ProviderPlane keeps them configurable and predictable instead of burying them in application code.

• The configured provider chain controls which provider connections ProviderPlane tries by default, and in what order.
• Persistence and resume are explicit. ProviderPlane supports them through hooks rather than assuming a hidden runtime or storage layer.
• Built-in workflow capabilities such as approvalGate and saveFile exist to model application flow, not just provider-backed model calls.

See corresponding persistence example

• Jobs give you explicit control over the lifecycle of an individual capability call.
• Use this layer when scheduling, retries, or execution control around individual operations matters more than describing the full flow as a workflow.
• Unlike the workflow example, the job example is intentionally smaller and only shows one capability call, because jobs are about execution control, not graph structure.
• As an application grows across many dependent steps, this layer usually becomes more verbose than the workflow layer because more orchestration has to be expressed manually.
• If the dependencies between steps matter, move back up to the workflow layer instead of rebuilding that logic around jobs.

See corresponding job example

• The configured provider chain still applies, so ProviderPlane still handles provider selection and fallback.
• The direct-client example is intentionally a single call, because chaining several calls together at this layer usually becomes the most boilerplate-heavy option.
• At this layer, sequencing and higher-level behavior live in your application code rather than in jobs or the workflow system.
• If you want explicit execution control, move up to jobs. If dependencies between steps matter, move up to the workflow layer.

See corresponding direct-client example