Architecture

Stategraph is composed of four components that cooperate on every plan and apply. The CLI is what you run locally, the Server stores state and coordinates work, and the Actuator executes Terraform/OpenTofu against your cloud.

Component Flow

UserCLIServerActuator1. Run a plan or apply2. Submit the change3. Deliver a runnable bundle4. Run changes5. Return the outcome6. Show the result

Components

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

CLI — stategraph is the command-line entrypoint. It packages the Terraform configuration, talks to the Server over HTTPS, and renders results back to the user. The CLI is stateless; everything authoritative lives on the Server.

Server — The central coordinator. Stores state in PostgreSQL, manages resource-level locks, records the transaction timeline, and decides what work needs to run. The Server never executes Terraform directly — it hands work off to an Actuator. See Deployment for installation options.

Actuator — The execution worker. Receives a runnable bundle from the Server, executes Terraform/OpenTofu against your cloud providers, and reports the outcome back to the Server. Actuators are horizontally scalable and run wherever they have network access to your providers.

Flow

  1. Run a plan or apply — The user invokes stategraph tf plan or stategraph tf apply from the CLI.
  2. Submit the change — The CLI uploads the configuration and request to the Server.
  3. Deliver a runnable bundle — The Server resolves dependencies, acquires resource locks, and dispatches a self-contained bundle to an available Actuator.
  4. Run changes — The Actuator executes Terraform/OpenTofu and streams the result back to the Server, which records it in the timeline.
  5. Return the outcome — The Server returns the plan or apply result to the CLI.
  6. Show the result — The CLI renders the outcome — diff, errors, or summary — back to the user.
  • Deployment — Run the Server and Actuator on Docker Compose, Kubernetes, or ECS
  • 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