Proposal for Embeddable UI

[sauraww]

Embeddable Admin UI Proposal

Summary

We should keep the current Leptos admin UI as the standalone Superposition admin app.

For embedding Superposition screens inside another frontend, we should ship a React package.

This does not mean Leptos is wrong. It means the standalone admin app and the embeddable UI solve different problems.

The standalone app owns the full page.
The embeddable package lives inside someone else’s product.

Why React For Embedding

The current Leptos UI is built like a full application. It owns the app shell, routes, styling, layout, and navigation.

An embeddable UI needs to behave differently:

• mount inside another frontend
• work inside the host’s layout
• avoid taking over the host’s router
• accept host-provided theme values
• talk to Superposition through a host-controlled API path
• allow the host to decide which features are visible

React is the safer choice here because most host dashboards can consume React packages easily. It also lets us expose individual screens like config, overrides, experiments, resolve, and audit as normal package exports.

The Core Abstraction

The host app should only need to provide a config object.

The SDK should hide the internal details.

The host says:

{
  "apiBaseUrl": "/superposition-api",
  "orgId": "localorg",
  "workspace": "production",
  "scope": {
    "context": {
      "region": "us-east-1",
      "tenant": "acme"
    },
    "locked": true
  },
  "features": ["config", "overrides", "resolve"],
  "readOnly": false,
  "theme": {
    "mode": "light",
    "colorPrimary": "#0f766e",
    "colorDanger": "#dc2626",
    "colorBg": "#f8fafc",
    "colorPanel": "#ffffff",
    "colorText": "#111827",
    "colorMuted": "#6b7280",
    "colorBorder": "#d1d5db",
    "radiusMd": "8px",
    "radiusLg": "12px"
  }
}

That should be enough for most integrations.

The host does not need to know about transport modes or theme token wrappers. The SDK can normalize those internally.

How API Calls Work
The SDK calls apiBaseUrl.

For example:

GET /superposition-api/default-config
GET /superposition-api/context
GET /superposition-api/config/resolve

In local development, /superposition-api can be a webpack proxy.

In production, /superposition-api can be a real Hyperswitch backend route that forwards requests to Superposition.

So the production flow can be:

Control Center
  -> Hyperswitch backend
    -> Superposition backend

This keeps Superposition private and lets Hyperswitch own auth, permissions, and deployment routing.

REACT USAGE

import "superposition-embeddable-ui/styles.css";

import {
  AlertProvider,
  SuperpositionAdmin,
  SuperpositionProvider,
} from "superposition-embeddable-ui";

const config = {
  apiBaseUrl: "/superposition-api",
  orgId: "localorg",
  workspace: "production",
  scope: {
    context: {
      region: "us-east-1",
      tenant: "acme",
    },
    locked: true,
  },
  features: ["config", "overrides", "resolve"],
  readOnly: false,
  theme: {
    mode: "light",
    colorPrimary: "#0f766e",
    colorDanger: "#dc2626",
    colorBg: "#f8fafc",
    colorPanel: "#ffffff",
    colorText: "#111827",
    colorMuted: "#6b7280",
    colorBorder: "#d1d5db",
    radiusMd: "8px",
    radiusLg: "12px",
  },
};

export function SuperpositionEmbed() {
  return (
    <SuperpositionProvider config={config}>
      <AlertProvider>
        <SuperpositionAdmin />
      </AlertProvider>
    </SuperpositionProvider>
  );
}

What The Host Owns

The host app owns:

• where the embedded UI appears
• the outer page layout
• the backend/proxy route
• production auth and permission checks
• which Superposition features are enabled
• theme values like colors and radius
• whether the UI is read-only
• scoped context like tenant, region, or environment