Flow Design

Design Flows around clear outcomes and the data dependencies that produce them.

Start with Outcomes

Choose the most downstream outcomes as Goals. Argyll walks their required Attributes backward to build an Execution Plan containing every producer they need.

Goal: send-confirmation
  needs transaction_id → process-payment
  needs customer_email → initial Flow state

Execution Plan: process-payment → send-confirmation

Choose Goals that represent the outcomes callers care about. Shared producers run once and contribute their results to every Goal that consumes them.

Model Failure Through Dependencies

A failed Goal makes its Goal set unreachable. The Flow moves to its next Goal set and fails when none remain. A failed non-Goal Step affects the Flow when its output is required to reach a Goal.

validate-customer → process-payment → send-confirmation (Goal)
                                      ↘ audit-log

If process-payment fails, the Goal becomes unreachable. A result connected through an optional input can enrich the outcome while allowing the Goal to complete independently. Required and optional roles express which results define success and which add context.

Plan Fallbacks

Chain Goal sets in order of preference. The set in else describes the outcome to settle for when the steps before it cannot be reached, such as a script Step that records a graceful degradation:

"goals": {
  "steps": ["ship-order", "send-invoice"],
  "else": {"steps": ["queue-for-review"]}
}

The fallback reuses everything the first attempt completed. Enable Rollback on Failure to undo the work that only the abandoned set used.

Design Guidelines

Design choice	Prefer
Goals	The most downstream business outcomes
Alternatives	Later Goal sets, ordered by preference
Conditions	Small predicates; a dedicated decision Step for richer logic
Large arrays	`for_each` with an intentional parallelism limit
Reusable orchestration	A Flow Step with well-defined child Goals
External side effects	Idempotent handlers keyed by the receipt token