Skip to content

Internal parity audits

Decided Designed

Source docs: Prototype_UX_Parity_Report.md · V3_V1_Workflow_Parity_Audit_v1.md · V3_Mock_To_Production_Data_Parity_v1.md · Gap_Analysis.md

Three parity audits document how the product has evolved internally: prototype → production, V1 → V3, and V3 mock → V3 production. They are not bugs lists — they are workflow-level audits that decided what survives the transition.

Evolution timeline

flowchart LR
    classDef hist fill:#e3f2fd,stroke:#1565c0
    classDef v1   fill:#fff3e0,stroke:#e65100
    classDef v3p  fill:#e8f5e9,stroke:#2e7d32
    classDef v3   fill:#fff3cd,stroke:#332701

    P[Prototype<br/>~/Downloads/GPUaaS<br/>gpuaasv3-main]:::hist
    P -->|"Gap Analysis<br/>(historical)"| V1[V1 production<br/>frozen demo + internal continuity]:::v1
    P -->|Prototype UX Parity| V3M[V3 mocks<br/>ux-mocks/product-redesign-v3]:::v3
    V1 -->|V3-V1 Workflow Parity| V3P[V3 production<br/>shipped from mocks]:::v3p
    V3M -->|V3 Mock-to-Production Parity| V3P

1. Prototype → Current UX parity (2026-02-24)

flowchart LR
    A["Prototype<br/>gpuaasv3-main/src/App.jsx<br/>+ admin<br/>+ TerminalModal.jsx"] --> B[Current app<br/>packages/web/app/*]
    B --> C[UX Journeys.md<br/>UX Implementation Spec.md<br/>contract baseline]
    C -.feeds back into.-> A

What this audit did

  • Cross-walked every prototype screen against the current app surface.
  • Marked screens as: shipped / partial / not yet / deliberately dropped.
  • Identified prototype behaviors that should remain mockup/reference only and not become behavioral source-of-truth.

What came out as requirements

  • Prototype is reference only. UX Journeys + UX Implementation Spec are the behavioral source of truth.
  • Selective fidelity — visual elements adopted; some prototype behaviors deliberately dropped (e.g. raw VNC console, predictable port derivation).
  • Terminal modal behavior locked to the gateway-mediated WS pattern (no raw VNC).

Source: Prototype_UX_Parity_Report.md.

2. V3 → V1 workflow parity audit

flowchart LR
    classDef v1 fill:#fff3e0,stroke:#e65100
    classDef v3 fill:#e8f5e9,stroke:#2e7d32

    V1[V1 pages<br/>entity dumps<br/>'show all the rows']:::v1 -.workflow shape changes.-> V3[V3 pages<br/>workflow-first<br/>'what does the user do here']:::v3
    V1 --> V1A[List of allocations]:::v1
    V1 --> V1B[List of nodes]:::v1
    V1 --> V1C[List of users]:::v1

    V3 --> V3A[Workloads with attention items]:::v3
    V3 --> V3B[Infrastructure → catalog +<br/>allocations + storage]:::v3
    V3 --> V3C[Access → projects + team +<br/>keys + policies]:::v3

Audit philosophy

V1 was useful as an entity dump; V3 should preserve the operator/user capability while changing the shape to workflow-first pages.

What came out as requirements

  • Capability parity, not page-shape parity — every V1 capability must have an equivalent V3 reach path, not necessarily an identical page.
  • V1 retirement guardrails — V3_V1_Retirement_Guardrails_v1.md defines which v1 routes stay (frozen demo / internal continuity) and which retire.
  • Domain route files — new production routes go to routes_provisioning_*.go, routes_platform_*.go, routes_access_*.go, not into routes_v1_frozen.go.
  • /api/v1/v3/* read-model isolation until each target domain route is clear.
  • Migration execution tracker — V3_Migration_Execution_Tracker_v1.md keeps the audit live as routes migrate.

Source: V3_V1_Workflow_Parity_Audit_v1.md, V3_V1_Retirement_Guardrails_v1.md.

3. V3 mock → V3 production data parity

flowchart LR
    classDef mock fill:#fff3cd,stroke:#332701
    classDef prod fill:#e8f5e9,stroke:#2e7d32

    M["/v3 mocks<br/>HTML in ux-mocks/product-redesign-v3/"]:::mock --> P["/v3-prod production routes<br/>shipped from mocks"]:::prod
    M -.visual + IA reference.-> P
    P -.parity audit ensures.-> M

Audit philosophy

Parity is a useful UX lens but the mock is not the behavioral source of truth. Where this spec and the redesign plan disagree, the redesign plan wins.

What came out as requirements

  • Mock-to-production copy boundary is explicit:
    • Descriptions in production pages serve the user's task, not the reviewer's understanding of the mock.
    • Remove permanent copy that restates the title or explains design rationale.
    • Put non-obvious context behind an info/help affordance.
    • Put first-time guidance in empty states, decision prose in confirmations, longer procedures in runbooks.
  • Permanent section subtitles are a warning sign that the page is still talking to design reviewers instead of acting like an operator tool.
  • Page-family taxonomy standardizes layout across the app (list + filter, detail + drawer, workbench).
  • Selector contract — pages expose stable selectors so E2E tests don't rely on text.
  • E2E testing contract — mocks and production share the same selector vocabulary so tests run against either.

Source: V3_Mock_To_Production_Data_Parity_v1.md, E2E_Selector_Contract.md, V3_E2E_Testing_Contract_v1.md.

4. Prototype → Production gap analysis (historical baseline)

flowchart LR
    classDef hist  fill:#eceff1,stroke:#455a64
    classDef done  fill:#d1e7dd,stroke:#0a3622
    classDef open  fill:#fff3cd,stroke:#332701

    P[Prototype]:::hist --> G["Gap Analysis.md<br/>(historical artifact)"]:::hist
    G --> D1[Many gaps now closed]:::done
    G --> D2[Some still open]:::open

Status

Per the doc's own header:

Historical comparison artifact retained for context. Many gaps listed here have been closed by the current implementation. Use this file as a prototype-to-target delta reference, not as the live implementation status source.

Why kept

A baseline of where the project started lets reviewers calibrate progress. It's also a reference for the kinds of issues to watch for during future prototype-to-production conversions.

Source: Gap_Analysis.md.

Cross-cutting takeaways

mindmap
  root((Parity audit themes))
    Source-of-truth rules
      Spec wins over mock
      Spec wins over prototype
      Spec wins over v1
    Capability parity not page parity
      V3 preserves v1 capability
      V3 changes the shape
      Operators reach the same outcomes
    Test stability
      Selector contract
      Same selectors mock and prod
      E2E runs against either
    Copy discipline
      Page copy serves the user
      Mocks talk to design reviewers
      Info affordances, not permanent subtitles

Where to look next