Documentation

Everything below is a file in the repository, rendered here so it can be read and linked without a checkout. Each page links to its source, and a correction is a pull request against that file.

Tutorials: the Terraform provider

• Your first flow with the Terraform provider

  Deploy a contact flow written as HCL action blocks with the flow-as-code/flowascode provider, and see what it does at plan time: lint that stops a missing branch or a pasted ARN, and a console edit shown as a diff to one action.

• Promote a flow from dev to prod

  One flow in a Terraform module, one root module per environment, and a pipeline that plans every environment, applies dev, and refuses to apply prod unless prod's plan carries the document dev ran. Also: looking resources up by name, and releasing shared modules through aliases.

• Bring existing flows under Terraform

  Take over flows built in the console or managed by hashicorp/aws without recreating them: import blocks with generated configuration, flow-cli export for a whole instance, and moved blocks from aws_connect_contact_flow.

• Edit a .flow.tf in the studio

  Keep a flow's HCL and the visual editor in step in both directions, keep refs bindings and @keep comments across canvas edits, and switch a flow's companion between HCL and TypeScript.

• The flow cookbook

  Complete flows for the Terraform provider, one pattern each and each applied to a live instance: business hours, a keypad menu, collected input, Lambda routing, a callback when the queue is full, a percentage split, a shared module released through an alias, and a generic block.

• Agent skills for AI coding agents

  The Agent Skills this repository ships for authoring, promoting and adopting flows and for flow-cli, how to install them in Claude Code as a plugin, and where any other agent can read them.

Format and design

• FlowDoc, the interchange format

  The JSON document every tool in the set reads and writes: its structure, the ${cdref:type:name} reference tokens, the invariants synth and codegen preserve, and how the format is versioned.

• Studio design

  How the visual editor is put together: the canvas over FlowDoc, the bidirectional sync between canvas and typed TypeScript, the local bridge that flow-cli studio serves, and the in-app export targets.

• Terraform emitter design

  What the emitter writes for a set of flows, the rules it holds to (no literal ARNs, no provider or backend blocks), and the corrections that running it against OpenTofu produced.

• The hosted read-only studio demo

  How the browser demo is built, what the demo build swaps out, how it is deployed, and the static and runtime checks that prove it makes no network request after its own assets load.

• Terraform provider and the HCL view

  The flow-as-code/flowascode provider and the .flow.tf companion: what the resources take, how a companion pairs with a document, which versions work together, and when to pick it over the emitter.

• Simulate: the live run and the dry run

  How a scenario suite is checked offline against the FlowDocs it will run through, and how it is executed on a live instance through the TestCase operations, with what each run can and cannot tell you.

Worked example

• Promote one flow across two environments

  A walkthrough you can run: one FlowDoc reaching a dev and a prod environment down both the Terraform and the CDK path, with no per-environment ARN table, and what the example does not claim.

• The Terraform provider example

  The files behind the provider tutorials: a flows module, dev and prod root modules that differ only in one module call, a platform configuration prod reads, the cookbook, and a GitHub Actions promotion pipeline.

Package references

• flow-cli command reference

  Every flow-cli command with its flags, input and output conventions, and exit codes: lint, render, codegen, synth, emit, diff, export, simulate, and studio.

• @flow-as-code/core, the engine

  The package the others build on: typed builder and synthesizer, codegen, lint, FlowDoc interchange, export from a live Amazon Connect instance, and the simulate scenario runner and its limits.

• @flow-as-code/cdk, the CDK binding

  The TokenBinder interface that maps reference names to construct attributes, the FlowSet construct that turns a directory of FlowDocs into Connect resources, and the peer dependencies both need.

• @flow-as-code/tf, the HCL emitter

  Calling the emitter, the .tf and .tftpl files it writes, how references become template variables, how escaping works, and what an incomplete address map does to the output.

• @flow-as-code/hcl, HCL as a third view

  The lossless HCL parser, the formatter that writes exactly what terraform fmt writes, literal evaluation and string quoting, and the flowascode companion format the studio and the CLI read and write.

• @flow-as-code/studio, the visual editor

  The save gate every write path runs through, the demotion invariant that stops a canvas gesture from quietly losing typed authoring, the export targets, and the read-only stores.

Contract and process

• The conformance suite

  The cross-language contract a second implementation has to reproduce: the fixture families for schema, flow language, lint, roundtrip, materialize, emit, export and simulate.

• Contributing

  How work is done in this repository: getting set up, the rules that are not negotiable, why every test has to be able to fail, and the commit, docs and licensing conventions.

Decisions

• ADR-0001: Defer jsii

  The decision not to publish the CDK package through jsii until the builder API stabilizes, and the type-system features the builder would have to give up to adopt it early.

• ADR-0002: Error branches are required config properties

  Why an unwired error branch is caught as a type error through required config properties rather than a state-threaded fluent builder, and what that keeps codegen output readable.

• ADR-0003: Synth preserves declaration order

  Why synth emits actions in the order the author declared them rather than in graph reachability order, and what that buys the codegen round trip.

• ADR-0004: Prior art, and why this is not Amazon's L2 CDK library

  The technical difference against the L2 CDK construct library the AWS Contact Center blog described: references that stay ${cdref:type:name} tokens through to deploy time rather than ARNs written in by a centralized mapping table, and a Terraform path alongside the CDK one.

• ADR-0005: An owned auto-layout replaces dagre

  Why the positions synth assigns to unplaced actions are computed by a small algorithm specified under conformance/ rather than by a layout library: a Terraform companion omits a position exactly when it equals auto-layout, so a second implementation has to reach the same integers.

• ADR-0006: A Terraform provider of managed resources that take action blocks

  Why the provider owns the flow's lifecycle through the Connect API rather than feeding hashicorp/aws, why a flow is written as repeated action blocks against the framework's advice, and how its schema is generated from the shared action catalog.

• ADR-0007: HCL is a third view over FlowDoc, paired by file

  Why a .flow.tf is a companion with the same standing as a .flow.ts rather than a rendering target, what a regeneration carries from the previous file, and what does not round-trip.

• ADR-0008: Cases field ids are casefield references, usable as map keys

  Why a Cases field id, a per-domain UUID that CaseRequestFields uses as a map key, is a reference type with tokens standing as keys and a path form that names them, rather than a literal id or an alias table.

• ADR-0009: UpdateRoutingCriteria's expression is a json value inside typed steps

  Why the recursive routing expression, which no Terraform schema can hold, is a json value inside typed steps rather than all of RoutingCriteria as json, a depth-limited shape or a new number kind.