Skip to content

ADR-003: Admin Experience — Wizard and Settings Pages

Audience: host — see ADR index.

Status: Proposed Date: 2026-04-09 Deciders: Portal team

Context

The portal needs a first-run wizard and Day 2 admin pages. Two wizard scopes were debated (broad 5-step vs narrow 4-step). The team also debated how many settings to surface in the GUI (~15 total cap vs progressive disclosure across pages).

Alternatives Considered

Alternative Source Why rejected
Broad 5-step wizard (AAP + registries + SCM) — ~15-20 fields — completion rates drop beyond 5; registries/SCM not in login chain
Hard ~15 total GUI cap, CLI as primary — Team clarified ~15 is per-page, not total; EE Builder and SCM must be in GUI
Full inventory (~99; originally counted as ~84) across 3 UI patterns — High complexity; users change 4-5 settings regardless; cost not justified
Bidirectional form/YAML sync — Significant engineering cost; no usage data to justify; partial edits corrupt state

Decision

1. Wizard scope — minimal path to first login. 4-step wizard with ~5 fields: (1) AAP Connection, (2) Confirm Base URL (pre-filled from Route on OCP, host IP on VM, platform metadata on managed; admin confirms or edits), (3) Select AAP Org(s), (4) Apply and Test. Registries and SCM are Day 2.

2. Progressive disclosure for Day 2. Settings per page should remain scannable and manageable. ~15 fields is a starting point, but collapsible sections, dropdowns, and progressive disclosure patterns can accommodate more without increasing page count. Settings distributed across dedicated admin pages: Connections, Sync Settings, EE Builder, SCM Integration, Advanced. CLI is a superset covering all ~99 application settings (ADR-002). YAML download/upload for headless workflows.

flowchart TD
    S1["Wizard Step 1: AAP Connection"] --> S2["Step 2: Confirm Base URL (pre-filled)"]
    S2 --> S3["Step 3: Select Org(s)"]
    S3 --> S4["Step 4: Apply and Test"]
    S4 --> LOGIN["First AAP OAuth Login"]
    LOGIN --> HOME["Portal Home"]
    HOME --> DAY2["Day 2 Admin Pages"]

    DAY2 --> CONN["Connections ~10 fields"]
    DAY2 --> SYNC["Sync Settings ~12 fields"]
    DAY2 --> EEB["EE Builder ~8 fields"]
    DAY2 --> SCM["SCM Integration ~8 fields"]
    DAY2 --> ADV["Advanced ~10 fields"]

Consequences

Positive:

  • ~70% fewer wizard fields — higher completion rate
  • Essential integrations in GUI; scannable pages via progressive disclosure patterns

Negative:

  • Content sync (registries, SCM) unavailable until Day 2 config
  • More admin pages to build; CLI docs critical for niche settings
  • Research: 002 (research not published in this repository), 003 (research not published in this repository), 006 (research not published in this repository), 007 (research not published in this repository)
  • ADR-002 (base URL in wizard Step 2)
  • workspaces/self-service/plugins/portal-scaffolder/ — wizard and admin page UI