Architecture

plnt is the orchestration runtime for micro-agent workflows — the third layer of a four-layer stack.

The stack

┌────────────────────────────────────┐
│  maps-micro-saas   (end-user SaaS)   │  reviews · posts · bookings
└───────────────────┬────────────────┘
                    │  invokes /invoke
                    ▼
┌────────────────────────────────────┐
│  microagents  (workflow registry)  │  pluggable recipes on S3 or OCI
│  review-responder · post-generator │
│  booking-triage  · trend-monitor   │
└───────────────────┬────────────────┘
                    │  plnt pulls spec on WorkflowRun apply
                    ▼
┌────────────────────────────────────┐
│  plnt  (this repo — runtime)       │  WorkflowRun CRD · Temporal saga
│  operator · orchestrate workflow   │  Helm install · canary · rollback
└───────────────────┬────────────────┘
                    │  helm install
                    ▼
┌────────────────────────────────────┐
│  Kubernetes GPU backends           │  kind · GKE · EKS · on-prem
│  scheduler · nvidia.com/gpu        │
└────────────────────────────────────┘

What plnt owns

Layer	Component	Owns
CLI + Python API	plnt/cli.py	plnt run, plnt list, plnt logs, plnt bench
Playground gateway	plnt/playground/	HTTP surface for interactive invocations
Helm charts	plnt/charts/{plnt, workflow-runner, playground-api}	Operator + per-workflow runner template
Temporal workflows	plnt/workflows/orchestrate.py	Orchestration saga · canary · rollback
Registry client	plnt/registry/	microagents pull path (S3 + OCI, integrity check)
Runtime adapters	plnt/runtime/	RuntimeAdapter Protocol + reference impls
CRD + operator	plnt/operators/	WorkflowRun CRD, kopf controller
Benchmarks	plnt/bench/	latency · throughput · GPU utilization

The runtime path

1. kubectl apply -f examples/review-responder.yaml — a WorkflowRun resource lands in the cluster.
2. The kopf operator sees the create event and starts a Temporal OrchestrateWorkflow.
3. The saga runs its five steps — pull spec, resolve backend, helm install canary, smoke test, promote or rollback.
4. Once promoted, the workflow is reachable at <name>.<ns>.svc.cluster.local:8000/invoke.
5. The playground gateway routes external requests to it based on the workflow ref.

Backends

A backend is a named Kubernetes cluster (or namespace within a cluster) with GPU nodes. Backends are declared once as PlntBackend resources and referenced by name from every WorkflowRun.

• kind-local — CPU stub for local development, no GPUs.
• gpu-cluster-01, gpu-cluster-02, … — real backends. Node selectors + taints/tolerations manage placement onto GPU pools.

The workflow spec

The thing plnt pulls from microagents. A workflow is:

• A workflow.yaml — steps, tool bindings, GPU requirements, budgets.
• A runnable module (Python today) that implements each step.
• Optional golden tests.

Runtimes are free to reject specs they can’t satisfy (e.g. gpuClass: nvidia.com/h100 on a backend with only A100s).

Design invariants

• The saga is a Temporal workflow, not a bash pipeline. State is durable, resumable, inspectable.
• Helm + K8s + Temporal are portable. Runs on kind, GKE, EKS, AKS, on-prem — same WorkflowRun YAML.
• The operator is small enough to read in one sitting. Every state transition emits a Kubernetes event.
• Workflow specs are pull, not push. Runtimes fetch from a registry; registries never push into runtimes.

See Runtime adapter for the code shape shared across backends, and API contract for the exact invocation wire format.