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.

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.

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.

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/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.