ADR-024: Sync UX — Backstage Signals and Unified Pattern¶
Audience: host — see ADR index.
- Status: Accepted
- Date: 2026-07-31
- Deciders: Portal team
Context¶
Multi-org support compounds sync complexity — more orgs mean longer syncs and higher risk of concurrent triggers from multiple admins. The portal has inconsistent sync patterns across views: templates use a "Sync now" header link, collections and git repos use a SyncDialog with tree selection. No view prevents concurrent syncs or shows real-time sync state across admin sessions.
Decision¶
Crawl-Walk-Run Strategy¶
Crawl (current scope): All-or-nothing sync. All configured organizations sync simultaneously. No granular per-org selection. Consistent UI pattern across templates, collections, and git repos.
Future Phases (Out of Scope)¶
Walk: Per-org sync selection in a tree dialog. Admin chooses which orgs/content types to sync.
Run: Event-based sync via AAP webhooks. No manual trigger needed — catalog updates automatically on AAP resource changes.
Unified Sync UI Pattern¶
All content views (templates, collections, git repos) adopt the same sync pattern:
- Sync button as secondary action, same line as primary action (e.g. "Add Template")
- Hover tooltip on sync button shows last sync timestamp
- Sync button disabled with spinning icon and "Syncing..." text during active sync
- Disabled state shared across all admin sessions in real-time
Backstage Signals for Sync State¶
Use Backstage's native Signals plugin (WebSocket push) instead of REST polling for sync state management:
- Backend:
SyncStateTrackerpublishes to signal channel on sync start/complete/fail - Frontend:
useSignal()hook subscribes to channel, updates UI state immediately - Initial state and reconnect: Fetch authoritative status (
fetchSyncStatus) on page load and after every signal reconnection. Signals update the UI between these snapshots; they do not replace reconciliation. - Ordering: Establish the subscription before reading the initial snapshot, and reconcile buffered events with that snapshot using a server revision or another documented ordering mechanism. An older response must not overwrite newer sync state. The implementation must define and test the chosen mechanism.
- Concurrency admission: The backend remains authoritative for accepting a sync trigger. UI disabled state and signal delivery do not prevent two clients from submitting concurrently. Define the admission/locking scope for the deployed scheduler, including multiple pods where supported.
Why Signals over polling:
- Prompt state updates while connected, with authoritative reconciliation after reconnect
- Cross-session — all admins see sync state simultaneously
- No polling infrastructure — eliminates
syncPollingService.ts(615 lines) - Native Backstage — supported in RHDH as dynamic plugin
RHDH NFS deployment contract:
Install compatible Signals backend and native frontend artifacts for the supported RHDH baseline. The frontend artifact must expose its native feature through ./alpha; operators use app.extensions only for overrides of extensions actually provided by that artifact. Do not register Signals through pluginConfig.dynamicPlugins.frontend: that is legacy Scalprum wiring and conflicts with ADR-010/011's NFS contract.
Exact artifact paths and extension IDs depend on the selected RHDH bundle and export version. Verify them against that bundle before publishing deployment YAML; this ADR does not define a portable artifact-path or extension-ID snippet. The source app's native composition and the NFS composition guide describe the current Portal integration baseline.
Signal Channel Design¶
| Channel | Publisher | Payload | Consumer |
|---|---|---|---|
catalog:aap-sync-status |
SyncStateTracker |
{ provider, syncInProgress, lastSyncTime, lastSyncStatus, lastFailedSyncTime } |
Home.tsx sync button |
Future channels follow the same pattern for content sync, job status, and user resolution.
Consequences¶
Positive¶
- Consistent sync UX across all portal views
- Real-time sync state without polling overhead
- Communicates active sync state across sessions; authoritative backend admission prevents concurrent manual sync triggers
- Extensible — same pattern applies to job status, content sync, first-login resolution
- Native Backstage feature — no custom infrastructure
Negative¶
- WebSocket connection requires authenticated session — initial connection fails before login (auto-recovers)
- Signals are ephemeral — no replay on reconnect; initial load and reconnection require authoritative status reconciliation
- Native frontend and backend Signals artifacts must match the supported RHDH bundle; verify actual exports and overrides instead of copying legacy wiring
Neutral¶
- Backend sync mechanism unchanged — same scheduler, same AAP API calls
- Helm chart needs signals plugins enabled in dynamic-plugins config
Verification requirements¶
- Disconnect during an active sync, complete it while disconnected, then reconnect: the authoritative refresh must clear the stale
Syncing...state without a page reload. - Deliver a signal while the initial status request is in flight: the older response must not replace newer state.
- Submit concurrent sync requests from two sessions, and from separate pods where supported: backend admission must enforce the documented concurrency scope regardless of UI signal timing.
Related¶
- ADR-020 — Multi-org namespace isolation
- ADR-021 — Template type taxonomy
- Research: Backstage Signals adoption notes (not published in this repository)
- PoC validated on a development cluster