Architecture

Stategraph has two parts you run — the CLI (local) and the Server (a coordinator backed by PostgreSQL). On every plan and apply, the CLI sends your change to the Server, the Server computes the minimal set of configuration the change needs, and the CLI runs Terraform/OpenTofu locally against your cloud. Your state lives on the Server; your cloud credentials never leave the machine where you run the CLI.

Component Flow

UserCLI (local)ServerYour Cloud1. Run plan / apply5. Show result2. Send change3. Return minimal bundle4. Run Terraform / OpenTofu locally

Components

User — The engineer or service account initiating the change. Drives the workflow through the CLI.

CLI (local) — stategraph is the command-line entrypoint you run on your machine or CI runner. It sends your configuration and the requested change to the Server, then executes Terraform/OpenTofu locally — pulling the minimal bundle the Server prepared, running it against your cloud with your local credentials, and reporting the outcome back. Authoritative state lives on the Server; execution and cloud credentials stay with the CLI.

Server — The central coordinator. Stores state in PostgreSQL, records the transaction timeline, coordinates concurrent changes at the resource level (conflict detection at commit time), and computes the minimal, self-contained bundle of configuration each change needs. The Server never runs Terraform and never sees your cloud credentials. See Deployment for installation options.

Your Cloud — Where Terraform/OpenTofu actually creates, updates, and destroys resources. It is reached by the CLI during execution, not by the Server.

Flow

  1. Run a plan or apply — The user invokes stategraph tf plan or stategraph tf apply from the CLI.
  2. Send the change — The CLI sends the current configuration and the requested change to the Server.
  3. Return a minimal bundle — The Server records the change as a transaction and computes the minimal, self-contained subset of configuration it needs (its dependencies and everything the change affects), then returns that bundle to the CLI.
  4. Run locally — The CLI writes the bundle to a temporary directory and runs Terraform/OpenTofu locally against your cloud, then reports the outcome back to the Server, which records it in the transaction timeline.
  5. Show the result — The CLI renders the outcome — diff, errors, or summary — back to the user.
  • Deployment — Run the Server on Docker Compose, Kubernetes, or ECS (the CLI runs wherever you invoke it)
  • Velocity — How the Server uses the dependency graph for parallel execution
  • Transactions — The transaction lifecycle that drives the flow above
  • CLI Reference — Full command-line interface