README
¶
A control plane for your services — typed configuration, hooks and events, workflows, API discovery, telemetry and one console for the whole installation.
Documentation · Quickstart · Deployment · Go SDK · Frontend SDK · API reference · Releases
Backplane connects services that use its Go SDK and gives operators a live view of their contracts, instances and configuration. Services own their APIs and UI modules; the platform supplies routing, a shared component kit and the console. It does not deploy services or replace your orchestrator.
Quickstart
Requirements: Go 1.26, Node.js 24, Yarn 1.22.22 and Docker Compose. Gopherex frontend dependencies come from GitHub Packages; configure a token with package read access in your user package-manager configuration.
git clone https://github.com/backplane-labs/backplane.git
cd backplane
make configure
make dev
Open http://127.0.0.1:8081/backplane/ and sign in with the local operator
token dev-admin-token-change-me. The installation includes backplane, hello
and formatter, with a working hook binding and event rule. Infrastructure,
including Temporal, runs in containers.
For the console with only PostgreSQL and Consul:
make dev-minimal
Open http://127.0.0.1:8081/backplane/. NATS, Temporal and observability capabilities stay disabled until their endpoints are configured.
The Compose defaults are for local development. For shared deployments, set your own credentials and secrets and expose the console through HTTPS. See development and deployment.
What it gives you
| Capability | What operators and module authors get |
|---|---|
| Service catalog | Live instances, readiness, versions, routes and service-owned UI pages |
| Configuration | Schema forms, validation, defaults, secret masking and live overrides |
| API discovery | HTTP/OpenAPI, protobuf RPC and GraphQL documents; bundled schemas and examples |
| Hooks and events | Typed bindings, CEL expressions, execution history and event rules |
| Workflows and schedules | Workflow runs and server-side administrative schedule management |
| Audit | Durable PostgreSQL records and API queries; optional delivery as OTel logs |
| Observability | OTLP admission/proxy and Victoria queries for metrics, logs, traces and errors |
| Infrastructure | Component availability in the console, including disabled and failed dependencies |
| Frontend kit | React, shared light/dark tokens, themed shadcn primitives and Grafana adaptations |
Use it in a service
go get github.com/backplane-labs/backplane
The Go SDK manages identity, manifests, listeners, probes, configuration and lifecycle. Optional drivers supply events and workflow execution. A service can run without the platform; deployments opt into Consul registration, NATS, Temporal and OTel. Start with the hello example, its formatter counterpart, and the example guide.
Module authors develop and serve their UI locally with yarn dev or a
container. They do not need to start the platform. The platform embeds the
module at deployment time through the shared routing and SDK contract.
See the author template,
package contract and UI kit.
Install a release
Tagged releases publish Linux amd64 and arm64 images to
ghcr.io/backplane-labs/backplane, plus archives containing the server and the ready
console. The release page carries checksums, the image digest and all 13
frontend package tarballs. Frontend packages publish to GitHub Packages.
docker pull ghcr.io/backplane-labs/backplane:0.1.1
The image runs as a non-root user. Supply PostgreSQL, Consul and an
operator token through deployment configuration; optional infrastructure is
enabled by its configured endpoints. See release packaging
and configuration. The publishing workflow runs on
vX.Y.Z tags; a manual run rehearses builds without publishing.
Layout
| Path | Purpose |
|---|---|
pkg/backplane |
Go service SDK and driver interfaces |
cmd/backplane |
Platform server |
backplanepb |
Protobuf contracts and generated Go API |
internal |
Catalog, console, configuration, wiring, audit and telemetry |
web/packages |
Coordinated TypeScript API, SDK and UI packages |
web/apps/console |
Production console host |
web/apps/catalog |
Storybook component catalog |
web/tests/fixtures/embedding |
Isolated module compatibility host |
web/build |
Shared internal library build settings |
examples |
Hello and formatter services with real contracts |
deployments |
Container builds, deployment and OTel configuration |
docs |
Canonical API, frontend and development references |
website/docs |
English architecture, usage and deployment handbook |
Develop
make help # available targets
make gen # generated Go/TS APIs and store code
make dev # complete local installation
make dev-ui # component catalog fixture
make dev-module # module template without the platform
make test # Go tests
make check # explicit full verification
make release # create and push a tag; no local builds or tests
Ordinary CI selects checks from changed paths. Full stack verification is an explicit manual run. See verification.
License
MIT. UI integrations retain their upstream notices in the packages.
Directories
¶
| Path | Synopsis |
|---|---|
|
backplanepb
|
|
|
cmd
|
|
|
backplane
command
backplane is the platform server: a service on its own SDK.
|
backplane is the platform server: a service on its own SDK. |
|
examples
|
|
|
demo
Package demo installs the example's cross-service binding and event rule through the public console API.
|
Package demo installs the example's cross-service binding and event rule through the public console API. |
|
demo/cmd/setup
command
setup connects hello and formatter using the console API.
|
setup connects hello and formatter using the console API. |
|
formatter/cmd/formatter
command
formatter is hello's independently compiled companion service.
|
formatter is hello's independently compiled companion service. |
|
formatter/internal/formatter
Package formatter is an independent service capability.
|
Package formatter is an independent service capability. |
|
hello/cmd/hello
command
hello is the reference service: every part of the SDK's author API, each where a real service would put it.
|
hello is the reference service: every part of the SDK's author API, each where a real service would put it. |
|
hello/internal/admin
Package admin is hello's internal API, for its console plugin only: gRPC on the platform port behind the internal secret.
|
Package admin is hello's internal API, for its console plugin only: gRPC on the platform port behind the internal secret. |
|
hello/internal/audit
Package audit reacts to the service's own Greeted event: a reactor is a durable consumer, so it sees every greeting of every instance, once each (it is idempotent under redelivery).
|
Package audit reacts to the service's own Greeted event: a reactor is a durable consumer, so it sees every greeting of every instance, once each (it is idempotent under redelivery). |
|
hello/internal/flows
Package flows is hello's side of Temporal: the hook it raises (Greet), the activities it offers to bindings (Echo, and Welcome backed by a workflow), its own workflows (GreetMany, declared for the console; Report, available for an administrative schedule) and the activities those run.
|
Package flows is hello's side of Temporal: the hook it raises (Greet), the activities it offers to bindings (Echo, and Welcome backed by a workflow), its own workflows (GreetMany, declared for the console; Report, available for an administrative schedule) and the activities those run. |
|
hello/internal/greeter
Package greeter is the service's domain component: it serves HelloService over every public protocol with one implementation and raises Greeted after every greeting.
|
Package greeter is the service's domain component: it serves HelloService over every public protocol with one implementation and raises Greeted after every greeting. |
|
hello/internal/hellotest
Package hellotest builds hello's components under a backplanetest harness, as NewState wires them, for the component tests.
|
Package hellotest builds hello's components under a backplanetest harness, as NewState wires them, for the component tests. |
|
hello/internal/legacy
Package legacy is a listener hello serves itself, outside the SDK's public port: the service announces it with a declarative route (svc.API(api.HTTP(...))) so its API appears in the catalog.
|
Package legacy is a listener hello serves itself, outside the SDK's public port: the service announces it with a declarative route (svc.API(api.HTTP(...))) so its API appears in the catalog. |
|
hello/internal/store
Package store stands in for an infra package (pkg/backplane/infra/postgres, infra/valkey): a config section plus a deps.Provider built from it.
|
Package store stands in for an infra package (pkg/backplane/infra/postgres, infra/valkey): a config section plus a deps.Provider built from it. |
|
hello/internal/web
Package web holds hello's HTTP-facing pieces: the /hello/ handler, a tiny GraphQL endpoint, the middleware and the gRPC interceptors its routes are declared with.
|
Package web holds hello's HTTP-facing pieces: the /hello/ handler, a tiny GraphQL endpoint, the middleware and the gRPC interceptors its routes are declared with. |
|
internal
|
|
|
audit
Package audit exposes durable control history and optionally exports its outbox over OTLP.
|
Package audit exposes durable control history and optionally exports its outbox over OTLP. |
|
bindings
Package bindings is backplane's side of bindings (§7.1) and rules (§8.1): the model, validation against the manifests, versions in PostgreSQL and the console's BindingService, RuleService and WiringService.
|
Package bindings is backplane's side of bindings (§7.1) and rules (§8.1): the model, validation against the manifests, versions in PostgreSQL and the console's BindingService, RuleService and WiringService. |
|
config
Package config is backplane's side of Live configuration (§5.2, §5.3): overrides of the Live fields of a service kept as revisions in PostgreSQL — the source of truth — and delivered to Consul KV config/<service>/, which is only the channel the SDK reads.
|
Package config is backplane's side of Live configuration (§5.2, §5.3): overrides of the Live fields of a service kept as revisions in PostgreSQL — the source of truth — and delivered to Consul KV config/<service>/, which is only the channel the SDK reads. |
|
console
Package console is backplane's console server (§11): the HTTP the shell talks to directly or through a deployment-owned reverse proxy.
|
Package console is backplane's console server (§11): the HTTP the shell talks to directly or through a deployment-owned reverse proxy. |
|
errors/envelope
Package envelope checks the browser SDK's error envelope (app-debug v1): the JSON body of the log record @backplane-labs/backplane-errors writes.
|
Package envelope checks the browser SDK's error envelope (app-debug v1): the JSON body of the log record @backplane-labs/backplane-errors writes. |
|
executor
Package executor is backplane's side of hook calls (design §7.2): it answers every hook of the installation over Temporal Nexus and runs bindings — and the rules engine's rules — as the workflow wire.BindingWorkflow ("backplane.Binding.v1") on backplane's own task queue.
|
Package executor is backplane's side of hook calls (design §7.2): it answers every hook of the installation over Temporal Nexus and runs bindings — and the rules engine's rules — as the workflow wire.BindingWorkflow ("backplane.Binding.v1") on backplane's own task queue. |
|
obs
Package obs provides bounded, read-only queries of independent Victoria stores.
|
Package obs provides bounded, read-only queries of independent Victoria stores. |
|
obs/logsql
Package logsql builds VictoriaLogs LogsQL queries.
|
Package logsql builds VictoriaLogs LogsQL queries. |
|
ops
Package ops is the console's operations on the stack behind the services (§8, §9, §11): events and their streams, consumers and dead letters in NATS JetStream; workflows, runs and schedules in Temporal; calling a hook or an activity by hand.
|
Package ops is the console's operations on the stack behind the services (§8, §9, §11): events and their streams, consumers and dead letters in NATS JetStream; workflows, runs and schedules in Temporal; calling a hook or an activity by hand. |
|
otlp
Package otlp admits public OTLP/HTTP into a deployment-owned Collector.
|
Package otlp admits public OTLP/HTTP into a deployment-owned Collector. |
|
platform
Package platform exposes deployment capabilities and bounded, cached probes.
|
Package platform exposes deployment capabilities and bounded, cached probes. |
|
registry
Package registry is backplane's view of the installation, built from Consul: the catalog (live instances and their health), the manifests the SDK writes per version, and the instance states under their sessions.
|
Package registry is backplane's view of the installation, built from Consul: the catalog (live instances and their health), the manifests the SDK writes per version, and the instance states under their sessions. |
|
rules
Package rules is the rules engine (§8.1): every active rule — a binding whose source is an event — gets a durable consumer on its event's stream, and every event its `when` matches starts one run of the executor's binding workflow, rule/<id>/<ce-id>.
|
Package rules is the rules engine (§8.1): every active rule — a binding whose source is an event — gets a durable consumer on its event's stream, and every event its `when` matches starts one run of the executor's binding workflow, rule/<id>/<ce-id>. |
|
server
Package server assembles the backplane server: its configuration and the State the SDK builds from it.
|
Package server assembles the backplane server: its configuration and the State the SDK builds from it. |
|
store
Package store is backplane's PostgreSQL: schema `backplane` (§12.1), migrations applied at start, typed queries generated by sqld.
|
Package store is backplane's PostgreSQL: schema `backplane` (§12.1), migrations applied at start, typed queries generated by sqld. |
|
wire
Package wire is the platform's wire contract as names (design §8, §9, §17): the NATS objects, headers and metadata of events, and the Temporal names of hooks, activities and schedules.
|
Package wire is the platform's wire contract as names (design §8, §9, §17): the NATS objects, headers and metadata of events, and the Temporal names of hooks, activities and schedules. |
|
pkg
|
|
|
backplane
Package backplane is the Go SDK.
|
Package backplane is the Go SDK. |
|
backplane/activity
Package activity declares operations a service implements ("умею"): the targets of bindings and rules.
|
Package activity declares operations a service implements ("умею"): the targets of bindings and rules. |
|
backplane/api
Package api describes the APIs a service serves, independently of deployment.
|
Package api describes the APIs a service serves, independently of deployment. |
|
backplane/backplanetest
Package backplanetest runs components without Open, Run, ports or Consul: build them under Root, Start, and inspect what they published, answer their hooks, invoke their activities and reactors, and check their readiness.
|
Package backplanetest runs components without Open, Run, ports or Consul: build them under Root, Start, and inspect what they published, answer their hooks, invoke their activities and reactors, and check their readiness. |
|
backplane/build
Package build carries what the deployment stamps into the binary at link time.
|
Package build carries what the deployment stamps into the binary at link time. |
|
backplane/config
Package config loads a service's configuration: one struct, schema from the Go type (schemapb), layers merged by xconf:
|
Package config loads a service's configuration: one struct, schema from the Go type (schemapb), layers merged by xconf: |
|
backplane/deps
Package deps is how a service is composed: a tree of components, dependencies and singletons built explicitly by the author's constructor.
|
Package deps is how a service is composed: a tree of components, dependencies and singletons built explicitly by the author's constructor. |
|
backplane/drivers/consul
Package consul installs optional discovery and live configuration.
|
Package consul installs optional discovery and live configuration. |
|
backplane/drivers/nats
Package nats installs the optional nats transport.
|
Package nats installs the optional nats transport. |
|
backplane/drivers/standard
Package standard composes the standard platform drivers.
|
Package standard composes the standard platform drivers. |
|
backplane/drivers/temporal
Package temporal installs the optional temporal transport.
|
Package temporal installs the optional temporal transport. |
|
backplane/event
Package event declares the events a service publishes and the reactors it runs.
|
Package event declares the events a service publishes and the reactors it runs. |
|
backplane/hook
Package hook declares operations a service calls without implementing them ("нужно").
|
Package hook declares operations a service calls without implementing them ("нужно"). |
|
backplane/infra/nats
Package nats is a NATS connection as a dependency: a configuration section, a connection that never gives up (reconnecting with jitter, no buffering while disconnected, transitions logged), a status probe.
|
Package nats is a NATS connection as a dependency: a configuration section, a connection that never gives up (reconnecting with jitter, no buffering while disconnected, transitions logged), a status probe. |
|
backplane/infra/postgres
Package postgres is a PostgreSQL connection as a dependency: a configuration section, a pgx pool traced and measured through the service's OpenTelemetry providers, a query log, pgtx transactions, an optional schema and sqld migrations applied at start, a ping probe.
|
Package postgres is a PostgreSQL connection as a dependency: a configuration section, a pgx pool traced and measured through the service's OpenTelemetry providers, a query log, pgtx transactions, an optional schema and sqld migrations applied at start, a ping probe. |
|
backplane/infra/temporal
Package temporal is a Temporal client as a dependency: a configuration section, a client traced and measured through the service's OpenTelemetry providers and logging through its logger, a health probe.
|
Package temporal is a Temporal client as a dependency: a configuration section, a client traced and measured through the service's OpenTelemetry providers and logging through its logger, a health probe. |
|
backplane/infra/valkey
Package valkey is a Valkey (Redis protocol) connection as a dependency: a configuration section, a client instrumented with the service's OpenTelemetry providers, a PING probe and a close.
|
Package valkey is a Valkey (Redis protocol) connection as a dependency: a configuration section, a client instrumented with the service's OpenTelemetry providers, a PING probe and a close. |
|
backplane/internal/apifiles
Package apifiles snapshots API files for content-addressed delivery.
|
Package apifiles snapshots API files for content-addressed delivery. |
|
backplane/internal/backoff
Package backoff is the SDK's retry policy as a value: bounds the author can set, run by github.com/cenkalti/backoff (exponential, jittered, so instances recovering from one outage do not retry in lockstep).
|
Package backoff is the SDK's retry policy as a value: bounds the author can set, run by github.com/cenkalti/backoff (exponential, jittered, so instances recovering from one outage do not retry in lockstep). |
|
backplane/internal/broker
Package broker carries events over NATS JetStream (design §8).
|
Package broker carries events over NATS JetStream (design §8). |
|
backplane/internal/configrt
Package configrt is what the SDK core needs from a live configuration and authors do not: the effective values for instance state, schema walks for the manifest and provenance.
|
Package configrt is what the SDK core needs from a live configuration and authors do not: the effective values for instance state, schema walks for the manifest and provenance. |
|
backplane/internal/consul
Package consul keeps a service present in Consul: manifest per version, instance state under a TTL session (it disappears with the instance) and the catalog registration.
|
Package consul keeps a service present in Consul: manifest per version, instance state under a TTL session (it disappears with the instance) and the catalog registration. |
|
backplane/internal/decl
Package decl is shared by the hook, activity and event packages: it resolves the service a Scope belongs to, derives payload schemas and encodes payloads.
|
Package decl is shared by the hook, activity and event packages: it resolves the service a Scope belongs to, derives payload schemas and encodes payloads. |
|
backplane/internal/env
Package env is what every node of one service shares: the manifest being declared into and the wiring of events, hooks and activities to a transport.
|
Package env is what every node of one service shares: the manifest being declared into and the wiring of events, hooks and activities to a transport. |
|
backplane/internal/exception
Package exception writes errors and panics as OpenTelemetry exception log records: exception.type, exception.message, exception.stacktrace and event.name=exception.
|
Package exception writes errors and panics as OpenTelemetry exception log records: exception.type, exception.message, exception.stacktrace and event.name=exception. |
|
backplane/internal/gate
Package gate admits internal API calls only while the author's tree is up: before it started they get Unavailable, and stopping waits for the calls in flight before the tree (and its dependencies) stops.
|
Package gate admits internal API calls only while the author's tree is up: before it started they get Unavailable, and stopping waits for the calls in flight before the tree (and its dependencies) stops. |
|
backplane/internal/guard
Package guard protects the platform port with the installation's internal secret: the console relay presents it, the SDK checks it.
|
Package guard protects the platform port with the installation's internal secret: the console relay presents it, the SDK checks it. |
|
backplane/internal/health
Package health is the single source of a service's health: probes are registered by kind, their composite status is cached in xprobe states, and grpc.health.v1, the HTTP probe endpoints and the Consul check all read the same states.
|
Package health is the single source of a service's health: probes are registered by kind, their composite status is cached in xprobe states, and grpc.health.v1, the HTTP probe endpoints and the Consul check all read the same states. |
|
backplane/internal/link
Package link lets SDK packages reach what public types keep private: the node behind a deps.Scope.
|
Package link lets SDK packages reach what public types keep private: the node behind a deps.Scope. |
|
backplane/internal/listener
Package listener serves gRPC and HTTP on one address through cmux.
|
Package listener serves gRPC and HTTP on one address through cmux. |
|
backplane/internal/manifest
Package manifest collects a service's declarations into a backplanev1.Manifest.
|
Package manifest collects a service's declarations into a backplanev1.Manifest. |
|
backplane/internal/metrics
Package metrics is the SDK's own instrumentation, on meter github.com/backplane-labs/backplane.
|
Package metrics is the SDK's own instrumentation, on meter github.com/backplane-labs/backplane. |
|
backplane/internal/node
Package node is the service's one lifecycle model: a tree of nodes, each with a name, a logger, an instrumentation scope, start and stop hooks, its own goroutines and an optional readiness probe.
|
Package node is the service's one lifecycle model: a tree of nodes, each with a name, a logger, an instrumentation scope, start and stop hooks, its own goroutines and an optional readiness probe. |
|
backplane/internal/recovery
Package recovery turns a panic in a request handler into an error for that request instead of a crashed process: gRPC and ws-proto calls get codes.Internal, HTTP requests 500.
|
Package recovery turns a panic in a request handler into an error for that request instead of a crashed process: gRPC and ws-proto calls get codes.Internal, HTTP requests 500. |
|
backplane/internal/routes
Package routes holds what route options configure, for the SDK core.
|
Package routes holds what route options configure, for the SDK core. |
|
backplane/internal/telemetry
Package telemetry installs OpenTelemetry through xtrace's SDK bootstrap: resource from the build identity, exporters from the standard OTEL_* environment.
|
Package telemetry installs OpenTelemetry through xtrace's SDK bootstrap: resource from the build identity, exporters from the standard OTEL_* environment. |
|
backplane/internal/temporal
Package temporal runs the service's activities and hook calls on Temporal (design §7.2, §9).
|
Package temporal runs the service's activities and hook calls on Temporal (design §7.2, §9). |
|
backplane/internal/temporal/temporaltest
Package temporaltest runs the SDK's Temporal tests against a dev server (BACKPLANE_TEST_TEMPORAL, e.g.
|
Package temporaltest runs the SDK's Temporal tests against a dev server (BACKPLANE_TEST_TEMPORAL, e.g. |
|
backplane/internal/testlog
Package testlog provides loggers for tests.
|
Package testlog provides loggers for tests. |
|
backplane/workflows
Package workflows gives a service its own Temporal workflows (design §9): the SDK owns the connection and the worker on the service's task queue (= its name); the author registers on it and uses the client.
|
Package workflows gives a service its own Temporal workflows (design §9): the SDK owns the connection and the worker on the service's task queue (= its name); the author registers on it and uses the client. |
|
backplane/wsproto
Package wsproto serves gRPC services over ws-proto (protobuf RPC over WebSocket) as a managed public api.
|
Package wsproto serves gRPC services over ws-proto (protobuf RPC over WebSocket) as a managed public api. |
Click to show internal directories.
Click to hide internal directories.