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 the Flow fail. 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.

Design Guidelines

Design choice	Prefer
Goals	The most downstream business outcomes
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