orbit

Orbit

The pluggable admin product for the Nucleus framework.

Orbit is a self-contained admin panel — Data Studio, a live request/SQL feed, a session viewer, RBAC management, and system metrics — that mounts in-process into any Nucleus application through the framework's extension/module API. It is a separate Go module with its own release cadence, extracted from the framework core per nucleus ADR-019 so the core stays lean and the admin can evolve as its own product.

You add one dependency and one Mount(...) call; orbit reads everything it needs from the running app's Runtime and serves its embedded React SPA — no separate asset deployment, no out-of-process sidecar, no database of its own.

Framework floor. Orbit builds against Nucleus and moves in lockstep with the certified suite set. The exact version it requires is in go.mod — that file is the source of truth, so this note cannot go stale.

Features

The UI ships embedded in the binary (go:embed), version-pinned to the orbit module — a consumer who mounts orbit gets the full admin offline, in a single binary.

Install

go get github.com/jcsvwinston/orbit@latest

The current tagged release is v1.9.5; pin that tag for reproducible builds.

v1.0 promise: the public surfaces (the root module and datasource) are frozen for the life of v1.x — enforced by contracts/freeze_test.go (see docs/V1_GATE.md).

Requires Go 1.26+ and a Nucleus application to mount into.

Quick start

Mount orbit on the application builder:

import (
    "os"

    "github.com/jcsvwinston/nucleus/pkg/nucleus"
    "github.com/jcsvwinston/orbit"
)

func main() {
    app, err := nucleus.New().
        FromConfigFile("nucleus.yml").
        Mount(orbit.Module(orbit.Config{
            Prefix:            "/admin",
            Title:             "Acme Admin",
            BootstrapUsername: "admin",
            BootstrapEmail:    "admin@acme.test",
            // When BootstrapPassword is empty, bootstrapping is skipped —
            // provision the admin user another way (e.g. nucleus createuser).
            BootstrapPassword: os.Getenv("ADMIN_BOOTSTRAP_PASSWORD"),
        })).
        Build()
    if err != nil {
        panic(err)
    }
    _ = nucleus.Run(app)
}

Start the app, open /admin, and sign in with the bootstrap user. Orbit self-registers its prefix with the framework's default-deny RBAC and enforces its own session-based auth below that prefix.

The zero value is valid too — orbit.Module(orbit.Config{}) mounts under /admin with sensible defaults.

Examples

Two runnable examples, both built by CI:

• examples/minimal — the in-process admin panel on a Nucleus app (this Quick start, as a program you can go run).
• agent/examples/fleet-app — the cluster leg: a host app wired with the Orbit agent, shipping observability to a standalone admin server you run alongside it.

Signing in against your directory

If the host application declares an authentication chain, the admin panel uses it:

auth_backends: [ldap, local]

Orbit ships no LDAP client. It asks the framework's chain, so whatever the operator configured for the application applies to the panel too.

Authentication is delegated; authorization is not. The chain answers who the credentials belong to; this panel's own admin table still decides whether that person may enter. A directory account that is not an administrator here is refused — otherwise connecting a corporate directory would quietly make every employee in the company an administrator of your admin panel.

That also means a local admin row is not a bypass: with a chain configured, the chain still has to accept the password, so a revoked directory account cannot get in through a stale row.

Without auth_backends, nothing changes: the panel validates against its own table exactly as before.

Configuration

orbit.Config is bound from the modules.orbit.* subtree of your nucleus.yml (or set it directly in Go). All fields are optional.

Precedence: the YAML subtree is overlaid on whatever you passed to orbit.Module(...), key by key — so Go supplies the base and nucleus.yml wins for the keys it sets. The one exception is prefix: the framework mounts the module before it binds the subtree, so modules.orbit.prefix cannot move the panel. Setting it to something other than the mount point fails at startup, naming both values, rather than serving a panel whose own links point elsewhere.

# nucleus.yml
modules:
  orbit:
    prefix: /admin
    title: Acme Admin
    environment: production
    bootstrap_username: admin
    bootstrap_email: admin@acme.test

How it works

Orbit is a nucleus.ModuleSpec. On startup it captures the app's Runtime and builds its panel from the framework's public accessors — the model registry, all managed database handles, the session manager, the RBAC enforcer, the live event bus, and storage. It never reaches into framework internals:

• In-process — it sees live runtime state (sessions, SQL, model registry, metrics) that an out-of-process sidecar could not, without any IPC surface.
• Self-contained auth — it owns a session-based login (DatabaseAdminAuth) against the nucleus_admin_users table and self-registers its prefix with the framework's default-deny RBAC, so the framework middleware never double-gates it.
• Embedded SPA — the React UI is built into the module and served under the mount prefix.

Cluster observability (optional)

For fleet-wide live telemetry, orbit ships sibling modules that are releasable independently:

Most applications only need the root orbit module for the in-process panel.

Relationship to Nucleus

Orbit is a "dogfooding" consumer of Nucleus: mounting a real, deep admin exercises and hardens the framework's extension/Runtime surface. The admin used to live in the framework core as pkg/admin; ADR-019 extracted it here as a clean break. Nucleus itself no longer ships any admin code.

Requirements

• Go 1.26+
• A Nucleus application to mount into.
• (Optional) Redis — only for the cross-node live-telemetry relay.

Development

go work sync          # Go workspace: ./ ./agent ./proto ./quarkbridge ./quarkdatasource ./server
make build            # go build ./... in every module
make test             # go test ./... in every module

That is the quick inner loop. CI additionally builds and tests each of the six modules standalone (GOWORK=off, the way a consumer's toolchain resolves them), verifies the protobuf stubs and the two web UIs, and runs the repository guards. CONTRIBUTING.md walks through all of it — read it before opening a PR. Security reports go through SECURITY.md, never a public issue.