The Problem

Engineering teams need a deterministic engine that can coordinate multi‑step workflows across Git, CI/CD, cloud infra, and incident tools while preserving auditability and allowing human‑in‑the‑loop approvals. Existing script‑based glue is fragile, hard to version, and offers no unified UI for operators or AI agents.

What This Does

SuperPlane provides an open‑source control plane that models each workflow as a canvas (graph of nodes) stored in git (canvas.yaml). The runtime executes canvases, persisting state in a Postgres DB and exposing a web UI built with React (web_src/). Core server code lives in pkg/server/server.go and pkg/public/server.go, while the CLI (cmd/cli/main.go) offers administrative commands (e.g., superplane run, superplane app create). The Go backend (pkg/…) implements the orchestration engine, and the TypeScript/React front‑end (web_src/) renders dashboards and console panels defined in canvas.yaml and console.yaml.

How It Is Wired

Entry → Server – Execution starts in cmd/server/main.go, which creates a pkg/server.Server instance, reads configuration from .env.example, and calls Server.Start(). Start() registers HTTP routes (pkg/public/server.go) and launches background workers that poll the DB for pending runs.

Entry → CLI – cmd/cli/main.go builds a cobra.Command tree; each sub‑command ultimately calls functions in pkg/cli/ (e.g., RunCommand), which invoke the same server‑side services (pkg/server) via the Go client library, ensuring CLI and HTTP paths share business logic.

Run Lifecycle – A new run is created by pkg/run/create.go (called from an HTTP trigger or CLI). It inserts a row in runs (SQL defined in db/migrations/*.sql), then enqueues a job in the internal worker queue (pkg/worker/queue.go). Workers pick up the job, resolve the canvas graph (pkg/canvas/graph.go), and execute each node by calling the component dispatcher (pkg/component/dispatch.go). Dispatch routes to concrete implementations in pkg/component/<integration>/ (e.g., GitHub, AWS, Slack). Each component writes its output back to the run_items table and may emit events that trigger downstream nodes.

UI Path – The React app built from web_src/ is compiled into pkg/public/pkg/web/assets/dist/. pkg/public/server.go serves index.html and static assets, while API endpoints (/api/v1/runs, /api/v1/canvases) are handled by pkg/server/handlers/*.go. The UI reads the same JSON payloads stored in the DB, displaying live run status, console panels, and allowing manual approvals.

Key Ownership

  • cmd/server/main.go – process bootstrap, config, server start.
  • pkg/server/server.go – HTTP router, middleware, DB connection.
  • pkg/public/server.go – static file server, SPA entry point.
  • pkg/run/* – run creation, state persistence.
  • pkg/component/* – integration implementations (largest blast radius; a bug here can affect external systems).
  • web_src/* – React components, dashboard rendering.

No circular imports were observed; the call graph is a shallow hierarchy (CLI → server → run → component). The widest blast radius is the component dispatcher because it contacts external services.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/superplane
cd superplane

# Build the Go binaries (Makefile defines `make build`)
make build          # produces ./bin/superplane-cli and ./bin/superplane-server

# Start a dev database (Docker Compose file provided)
docker-compose -f docker-compose.dev.yml up -d db

# Run the server (environment vars from .env.example)
cp .env.example .env
make run-server     # equivalent to: ./bin/superplane-server

# In another terminal, start the UI build
cd web_src && npm ci && npm run dev   # serves React SPA on localhost:3000

The server listens on :8080 by default; the UI proxies to this endpoint. CLI commands are documented in cmd/cli/main.go (run ./bin/superplane-cli --help).

Real‑World Use

A team can wire a PR‑preview app by defining a canvas (apps/preview/canvas.yaml) that triggers on a GitHub webhook, calls the aws-ec2-create-instance component, runs integration tests, and posts the preview URL back to the PR via the slack-post-message component. The UI automatically shows the run status and provides an “Approve” button for manual gating.

Code Health & Issues

  • Medium – No CI/CD pipeline – No .github/workflows or other CI config; automated testing is not gated.
  • Low – Secret‑related migrations – Migration files under db/migrations/ reference “secrets” tables (20250602182837_add-secrets.*). Ensure no production secrets are hard‑coded.
  • Low – Test coverage – 1917 test files exist, but no coverage reports are generated in the repo; consider adding go test -cover integration.
  • Low – Documentation density – 102 markdown files present, but the top‑level README lacks explicit build/run instructions; the Makefile provides the missing commands.

The Bottom Line

SuperPlane supplies a cohesive Go‑backed orchestration engine with a React UI, suitable for teams that want deterministic, version‑controlled workflow automation and are comfortable managing a Postgres DB and Docker environment. It lacks an out‑of‑the‑box CI pipeline and could improve its onboarding docs, but the core architecture is clear and extensible for custom integrations. Target users are engineering ops groups building complex, multi‑system pipelines that require auditability and human approval steps.