Skip to content
UI

Architecture

Owner: LEMN UI maintainers Decision date: 2026-07-17

Decision

Section titled “Decision”

LEMN exposes one provider-neutral UI surface assembled from individually selected, battle-tested open-source capabilities. Functional behavior remains with the provider of record. LEMN owns public APIs, semantic branding adapters, curated catalogs/blocks, provenance, conformance, and releases.

Branding source is BrandingDefinition v1. Publication keeps the complete immutable compiled object in private R2 and signs one minimal projection per allowed mode. A runtime response contains only the selected verified mode projection. Components never parse source JSON.

Responsibility map

Section titled “Responsibility map”
Boundary Owns Must not own
@lemn-ltd/brand-contract Schema, validation, deterministic compiler, diagnostics, private artifact and signed mode-projection contracts, tokens, provider themes Persistence, authorization, publication, active selection
@lemn-ltd/brand-runtime Server resolution adapters, verification, selected-mode projection, SSR helpers, embedded fallback Browser resolution, cookies, routing, source authoring, credentials
@lemn-ltd/ui Controlled public components, visualizations, styles, blocks, catalogs Product APIs, auth, routes, global state, source branding JSON
@lemn-ltd/brand-studio Controlled wizard, real preview, JSON review, typed host intents Fetching, credentials, persistence, publication authority
Provider registry One provider of record per capability, exact origin, license, adapter, conformance Runtime state or automatic upgrades
Lemn UI Portal Public catalog evidence plus Access-protected experiments and proposals in one deploy Durable Workspace state, activation, or browser-driven deploys
AgentOps Workspaces, Branding, BrandingVersions, authorization, Postgres, R2, publication, activation, previews, MCP, audit Forked UI behavior or branding contracts
Product host Product data/platform, Workspace identity, SSR resolution, controlled props/actions Shared component forks or direct provider imports

Dependency direction

Section titled “Dependency direction”
provider registry + selected upstream packages
                    │
                    ▼
              @lemn-ltd/ui


@lemn-ltd/brand-contract ─► private full object ─► AgentOps private R2
            │                         │
            │                         └─► signed per-mode projections
            └─► @lemn-ltd/brand-studio                   │
                                                        ▼
                                              AgentOps private runtime
                                                        │
                                                        ▼
                                      one selected mode in product SSR host

The UI repository contains no mutable control-plane authority. Postgres is authoritative for Workspace/version state; private R2 stores content-addressed full compiled objects and their signed minimal mode projections; runtime caches are hash-keyed accelerators only. Consumers pin exact published versions and never connect repositories with workspace links in production.

Runtime transport and workload identity

Section titled “Runtime transport and workload identity”

Same-account Cloudflare consumers use an RPC Service Binding to a dedicated Branding Runtime WorkerEntrypoint. Deployment configures immutable ctx.props with the exact workspaceId, consumerId, and branding:resolve permission. The binding exposes only resolveBranding, exchangeBrandingPreview, and resolveBrandingPreview; it is not an anonymous HTTP Fetcher, and RPC inputs cannot choose tenant identity or carry a reusable runtime credential.

External servers use authenticated HTTPS and keep a least-privilege WorkspaceRuntimeCredential in server-only secret/configuration storage. The HTTPS adapter sends it to the private runtime API; it is never serialized to HTML, bootstrap data, URLs, logs, or browser storage. Network location and a Service Binding alone are not authorization: the runtime validates the static workload grant on every RPC call.

Consequences

Section titled “Consequences”
  • Upstream fixes arrive through reviewed provider updates without behavioral rewrites.
  • One Workspace has one Branding and many independently named draft/published BrandingVersions; only a human activation pointer selects the active version.
  • A definition may contain complete light/dark modes, but it is not a family of runtime-switchable brand identities.
  • First-byte branding and hydration identity are verifiable.
  • Frontend-platform concerns remain separable from the visual contract.

This decision implements PAT-UI-PROVIDER-FIRST-001, PAT-UI-BRAND-CONTRACT-001, PAT-UI-SSR-BRANDING-001, PAT-UI-BLOCKS-001, and PAT-UI-FRONTEND-PLATFORM-BOUNDARY-001.