How RLPv2 works and why

01

System context

One host composes two kinds of content: iframe apps (full screen, from the sidebar) and federated widgets (Home cards). The host owns identity, store context, language, navigation and telemetry. Partner code never talks to those systems directly; it gets what it needs from the host. Hover any box for its relationship to the host.

02

Runtime composition

The host serves the shell surface to partner modules but does not consume it through federation. Its own code imports the shell by source path. Host and partners still share exactly one instance of the auth context, translations context and New Relic agent, because they end up loading the same JavaScript file.

How host and partners share one instance (click a path)

03

Federated contract

The host publishes under the federation name host. Partners alias it as retailUXShell. Only paths with a real downstream consumer are exposed, and nothing exposed lets a partner drive the session.

// retailUXShell/core: useAuth() for partner modules
interface RemoteSafeAuth {
  accessToken: string | null;
  isLoggedIn: boolean;
  userInfo: UserInfo | null;   // athlete_id, operator_id, nike_store, roles, locale, timezone…
}
// No login, logout, sessionExpiresIn, providers or token refresh.
// The host's internal useAuth (src/shell/auth/useAuth.tsx) keeps those.

Who uses it (audited)

Contract rules

• A symbol is added to remoteSafeSelectors.ts only when a real downstream module needs it, as an explicit named export (never export *), and only as read-only session state. Changes require approval because this is the public contract.
• Host-only helpers (initHost, getWidgetHost, trackWidgetDismiss) stay out of the surface.
• Partner modules wrap their widgets in <Shell> to receive the host contexts. They are built against React 16 or 18, with react and react-dom shared. The contract for mismatched React versions is an open follow-up.

04

Registries & gating

Everything the host can render is declared in files that ship with the host. That keeps it simple and reviewable. The tradeoff is that adding or removing an entry needs a host deploy (see section 12).

Sidebar app visibility gates

Source: src/Components/SidebarNavigaton/index.tsx (store flags via UserPermissionsProvider). Widgets have only the environment and native gates. There is no per-store or role targeting and no kill switch.

05

Iframe integration contract

Unchanged by the restructure. Transport is window.postMessage, handled in src/retail-launch-pad/utilities/windowMessageHandling/index.js (message names in constants.ts beside it). The host replies only to origins on the allowlist (every URL in apps.json). Anything else is dropped and recorded as IframeOriginRejected. The message names are identical to RLPv1, which is why v1 apps run in v2 unmodified.

Iframe element

sandbox="allow-same-origin allow-scripts allow-top-navigation allow-modals allow-downloads" and, since PR #131, allow="local-network-access". Chrome's Local Network Access denies cross-origin iframes access to private-network APIs unless the embedder delegates it. SIMWeb needs this to reach sim-bff.

Iframe router: navigation that crosses the boundary

src/hooks/useIframeRouter.tsx: the app signals readiness and publishes its routes. The host renders them as sidebar sub-items (SOR → KPI, Variance Report, Till Totals…) and navigates the iframe on click. Requests are queued until the app is ready. A 10 s ready SLA emits IframeReadyTimeout (1 occurrence in 34,002 loads last week).

06

Identity & session

The host is the only owner of the session. Partner widgets read it through the read-only useAuth(). Iframe apps receive tokens over the allowlisted channel. Neither can log in, log out or schedule refreshes.

Translations come from Bodega. Keys Bodega hasn't published yet (currently the certificate guidance copy) resolve from a bundled catalog, src/shell/contexts/localTranslations.ts, then from the English fallback at the call site.

07

Widget platform

Widgets are federated components rendered inside the host's React tree. The host is deliberately generic. It loads, tracks and renders widgets, but the widget decides when it should be visible.

// window.rweWidgetHost, reached by partners via useWidgetHost() (src/widgets/widgetTypes.ts)
registerWidget(entry: WidgetRegistration): void
notifyReady(id: string, payload?: unknown): void                     // "show me"
notifyHide(id: string, options?: { userDismissed?: boolean }): void  // "hide me"
getLastHiddenByUser(id: string): string | null                       // ISO timestamp
trackEvent(eventName: string, attrs?: Record<string, string | number | boolean>): void

Lifecycle (click a transition)

What the host provides to widgets

• SuggestionWidget: shared container, close button and dismiss interaction.
• hostNavigate(route): deep-link from a widget into any app route (e.g. Variance → SOR Variance Report with date, till and athlete pre-selected).
• trackWidgetEvent / trackWidgetCtaClick: widget-scoped telemetry without importing the full SDK.
• WidgetErrorBoundary around every widget, plus WidgetLoadError / WidgetRenderError telemetry.
• Dismissal memory: localStorage.widgetsLastHiddenByUser[operatorId][widgetId], written only for user dismissals and only when userInfo.operator_id is present.

Live widgets

Both suggestion widgets are disabledInNative, so today they appear only on store computers. SOR KPI appears on web and iOS.

08

Observability & alerting

• One SDK and one New Relic Browser Agent. The host imports it from @/shell/observability: track (PageAction), notice (JS error), timing (durationMs), withContext, setUserContext. Widgets emit through trackWidgetEvent / trackWidgetCtaClick.
• 38 named events under a <Domain><Action><Outcome?> taxonomy enforced by a branded TS type: App, Auth (10), Iframe (10), Nav, Store, Widget, Federated.
• PII: user.givenName / user.familyName are stripped at runtime from every emitted event. Use user.athleteId. On iOS, use sessionTraceId rather than NR session.
• Session Replay is forbidden by org policy, enforced by a pretest grep guard.

Alerts as code

newrelic/ holds Terraform for policies, conditions, the Slack channel and workflow, with one runbook per condition. Jenkins runs terraform plan on PRs and apply on develop (TEST) and main (PROD). State lives in S3 + DynamoDB with Retain policies. Everything is named APEX - RLPv2 - ….

Single tier (critical only), routed to Slack only. Promotion to PagerDuty is per condition, after 2+ clean weeks and a dedicated PR. Dashboards live in the NR UI under APEX - RLPv2/Companion/RWE. Doctrine: src/shell/observability/README.md.

09

Build, quality & deploy

10

Decision records

The "why", in a consistent format. Expand any record for context, alternatives, consequences and the trigger to revisit it.

11

Polling cost model

The original worst-case model assumed 1,500 stores × 3 devices × 50 widgets, each polling every 20 minutes for 12 hours a day: 243 M requests a month ≈ $731 on a modeled API Gateway + Lambda + DynamoDB stack (≈ $3.01 per million). That model assumes every device sits on Home all day. It doesn't. Widgets are rendered inside Home.tsx, so they fetch only while an associate has the Home page open. The real cost driver is how often and how long associates are on Home, so we measured it.

What production shows

12

Known constraints & tech debt

13

Open questions

1. Home direction: notifications feed, to-do list, or a hybrid? This blocks the backend design.
2. Dismissal scope: per athlete, per role group in a store, or the whole store?
3. Should polling-driven notifications (SOD/EOD) be centralized, or stay in the widget with an SDK polling wrapper?
4. Widget registration: self-service for partner teams, or approved by the platform team?
5. Should the kill switch also cover iframe apps, beyond today's per-store disable keys?
6. What does shared guarantee for widgets built on a different React version, and do we require React 18?
7. Once partners stop self-wrapping in <Shell>, does Shell leave the surface? Does observability stay?
8. Is there a path for iframe apps to become federated modules, and which app would go first?
9. What latency is acceptable per notification type? (Current guidance: 5–30 minutes.)
10. Corporate view: what does a non-store user see, and how much should RLPv2 share with whisker-host?

Sources: rwe-core (AGENTS.md, README.md, vite.config.ts, src/, newrelic/, openspec/changes/align-rwe-core-with-whisker-host), rbh-retail-launchpad-ui, Confluence space COM (Architecture – Current vs Future State; Future State: Requirements; Future State Dependencies; SOR Variance Widget; Nike Cash Widget), New Relic production (rwe-core-host), Oct 21–27, 2026 unless noted.