Skip to content

UX information architecture

Decided

Source: doc/product/UX_Journeys.md · doc/product/Product_Surface_IA_and_Role_Model_v1.md · doc/product/Navigation_Redesign_App_Platform_v1.md

The information architecture follows the V3 redesign page-family model: top nav by domain family, side nav by domain page, content by intent.

Primary navigation

flowchart LR
    classDef sec fill:#e3f2fd,stroke:#1565c0
    classDef adm fill:#ede7f6,stroke:#5e35b1

    OV[Overview]:::sec
    OV --> OV1[Home]
    OV --> OV2[Billing & Usage]

    WL[Workloads]:::sec
    WL --> WL1[Active]
    WL --> WL2[Needs attention]

    IN[Infrastructure]:::sec
    IN --> IN1[Catalog]
    IN --> IN2[Allocations]
    IN --> IN3[Storage]

    AP[Apps]:::sec
    AP --> AP1[Browse & Deploy]
    AP --> AP2[Artifacts]

    AC[Access]:::sec
    AC --> AC1[Projects]
    AC --> AC2[Team]
    AC --> AC3[SSH Keys]
    AC --> AC4[API Keys]
    AC --> AC5[Policies]

    DV[Developer]:::sec
    DV --> DV1[Docs]
    DV --> DV2[Downloads]
    DV --> DV3[API Docs]

    OPS[Ops]:::adm
    OPS --> OPS1[Attention]
    OPS --> OPS2[Telemetry]

    AD[Admin]:::adm
    AD --> AD1[Dashboard]
    AD --> AD2[Nodes]
    AD --> AD3[SKUs]
    AD --> AD4[OS Images]
    AD --> AD5[Allocations]
    AD --> AD6[Quotas]
    AD --> AD7[Users]
    AD --> AD8[Audit Logs]
    AD --> AD9[MAAS]
    AD --> AD10[Payment Sessions]

V3 route model

Route Purpose
/ Home (overview)
/workloads Active workloads + attention items
/workloads/:id Workload detail (allocation + apps)
/infra/catalog SKU catalog
/infra/allocations All allocations
/infra/allocations/:id Allocation detail with timeline
/launch Launch wizard
/tasks/:id Provisioning task progress
/billing Balance + usage + payments
/access/* IAM surfaces
/developer/* Docs, SDKs, API explorer
/ops/* Operator surfaces
/admin/* Admin workbench

Page-family taxonomy

Three page families standardize layout across the app:

flowchart LR
    classDef fam fill:#fff3e0,stroke:#e65100

    F1[Page Family A:<br/>List + filter]:::fam
    F2[Page Family B:<br/>Detail + drawer]:::fam
    F3[Page Family C:<br/>Workbench]:::fam

    F1 --> P1["/workloads<br/>/infra/allocations<br/>/admin/users"]
    F2 --> P2["/workloads/:id<br/>/infra/allocations/:id<br/>/admin/nodes/:id"]
    F3 --> P3["/admin/ops<br/>/admin/dashboard<br/>/admin/audit-logs"]

Source: Product_Surface_IA_and_Role_Model_v1.md and V3_Admin_Workbench_Model_v1.md.

Async state matrix

Every page handles six states:

State When Rendering
loading Initial data fetch in progress Skeleton placeholder
empty Successful fetch, no results Empty state with first-action CTA
error Fetch failed Inline error + retry, correlation id
success Data rendered Normal content
restricted 401/403 Redirect or fallback page
rate_limited 429 Wait-and-retry banner with Retry-After

Enforced by UX_Implementation_Spec.md.

Selector contract (testability)

Pages expose stable selectors so E2E tests don't rely on text content.

Source: E2E_Selector_Contract.md.

Inline-dependencies rule

Launch wizard handles SSH key creation, storage attach, etc. inline — users don't bounce to a different page mid-flow.

Source: Launch_Wizard_Inline_Dependencies_v1.md.

Mock vs production boundary

  • /v3 route serves the design mock (HTML in ux-mocks/product-redesign-v3/).
  • /v3-prod (and the active production routes) serves the shipped implementation built from it.
  • Parity is a useful UX lens but the mock is not the behavioral source of truth — the redesign plan + this IA win.

Source: V3_Mock_To_Production_Data_Parity_v1.md.

Where to look next