V3 Mock To Production Data Parity v1

Date: 2026-04-27

Tracking token: V3_Mock_To_Production_Data_Parity

Purpose

The /v3 mock set the product expectation. The /v3-prod surfaces should match that interaction model as closely as possible before internal cutover. Visual parity is not just CSS parity: the production read models must carry enough normalized, user-safe data for the pages to feel as rich as the mock.

Current Assessment

The shell and page-family structure are aligned:

• /v3-prod uses the promoted product primitives from the mock.
• All seven shell groups exist: Workloads, Compute, Apps, Storage, Access, Account, Platform.
• Utility surfaces that do not fit the seven-group rail are handled outside the left navigation: notifications use a top-bar inbox route, and developer downloads/API references use session/help entry points.
• The major production read-model endpoints exist under /api/v1/v3/*.

The largest remaining parity gaps are in read-model data depth and platform detail-route decomposition.

2026-04-28 Kind Cutover Parity Pass

Tracking token: visual/data parity

Evidence:

• make kind-parity-validate passed against local kind after the latest v3 web/API image rollout.
• E2E_SPEC=e2e/v3-shell.spec.ts bash scripts/ci/frontend_e2e.sh full passed against the full frontend E2E harness.
• Scoped web-only V3 specs passed before kind promotion: v3-shell, v3-personas, v3-compute-apps, v3-storage-access-account, and v3-admin-platform.

Routes reviewed for mock-to-production parity:

Route family	Parity outcome	Classification
/v3-prod/workloads and /v3-prod/workloads/{id}	Production uses the v3 shell, promoted primitives, rich kind-aware workload rows, action-band recovery, resource header, context strip, and tabbed detail model. Remaining differences are real-data depth for app-kind-specific tabs and richer balance/runway modeling.	read-model gap, accepted for first internal cutover
/v3-prod/compute	Visual SKU card treatment now matches the approved mock direction closely enough for cutover.	no blocking gap
/v3-prod/apps and /v3-prod/apps/{slug}	Featured app cards and compact catalog rows now restore the remembered colored app identity from the mock.	no blocking gap
/v3-prod/launch/compute, /v3-prod/launch/app/{slug}, /v3-prod/launch/storage	Wizard foundation is in production with persistent drafts, backward step navigation, staged submit paths, and inline SSH key, bucket, and service-account dependency creation. Network/firewall dependencies remain future-product scope until contracts exist.	future-product gap
/v3-prod/storage and /v3-prod/storage/{id}	Storage workbench/detail match the provider-neutral model. Bucket creation works through the v3 mutation. Grant APIs exist for sharing; credential issuance remains fail-closed until WEKA/VAST behavior is validated.	read-model gap + future-product gap
/v3-prod/access and sub-surfaces	Access overview, memberships, service accounts, credentials, entitlements, connectivity, identity, and audit routes exist. Connectivity/identity/audit are production-safe scope pages until their backend read models land.	future-product gap
/v3-prod/account and sub-surfaces	Account overview/profile/security/billing/sessions exist and preserve the Access vs Account split. Billing remains lightweight until the billing epic.	future-product gap
/v3-prod/evidence	User/project/tenant-scoped audit evidence now shares the same v3 table and detail-drawer model as platform evidence while preserving scoped audit APIs.	no blocking gap
/v3-prod/tenant/overview and /v3-prod/project/overview	Persona landing routes now exist and aggregate existing shell, access, account, and workload read models.	read-model gap, accepted for first internal cutover
/v3-prod/platform/*	Platform overview, ops, lifecycle, config, evidence, finance, IAM, node detail, MAAS hub/site detail, onboarding detail, and decommission detail exist using the v3 family model rather than V1 admin dumps. Remaining risk is live read-model depth and final visual hierarchy on dense admin/operator pages.	rendering gap for dense admin drill-downs, not blocking first cutover
/v3-prod/notifications, /v3-prod/developer/downloads, and /v3-prod/schedulers	Utility routes exist outside the seven-group left rail, preserving shell simplicity. Scheduler guidance now routes users to Apps, Workloads, and Access rather than reviving a scheduler shell group.	no blocking gap

Cutover decision from this pass:

• No blocker remains for internal/demo V3 route cutover in kind.
• Do not remove /v3 mock routes; keep them as a visual reference while reviewers compare /v3-prod and production data behavior.
• Do not treat the current parity pass as approval for provider credential issuance. Storage direct credentials still depend on real WEKA capability validation.
• Do not treat this as approval to migrate V1 admin pages page-for-page. Future admin work must continue decomposing into Platform families and detail routes.

Gaps Before Cutover

Area	Mock expectation	Current production risk	Owner
Workload detail	Kind-aware tabs for compute, Jupyter, vLLM, and training; lifecycle timeline; recent activity; metrics; storage mounts; config; primary action per kind.	Frontend now renders the full tab payload. Remaining risk is sparse backend data for real allocations and missing app-kind-specific richness where the read model does not provide it.	A
Workload workbench	Rich rows with kind icon, node, age, hourly/accrued cost, suggested next steps, balance/runway.	Frontend now renders kind-aware rows, action reasons, primary actions, node/age/cost facts, and suggested next steps. Remaining risk is balance/runway read-model depth beyond hourly/accrued cost.	A
Storage detail	Full bucket tabs: overview, objects, mounts, access, lifecycle, events, with usage/sidebar/action affordances.	Frontend now renders all tab groups. Remaining risk is placeholder backend arrays and provider-backed object/access/lifecycle data once WEKA is connected.	A
Storage launch	Standalone /v3/launch/storage wizard validates the bucket creation model.	/v3-prod/launch/storage now calls the provider-neutral bucket-create mutation. Remaining risk is provider-specific quota/capability reconciliation once WEKA is connected.	A
Storage sharing	Datasets, checkpoints, and artifacts must be shareable across projects without making users global provider users.	Provider-neutral grant records and list/create/revoke endpoints are being added. Remaining risk is UI affordance parity plus provider-backed policy/credential issuance after WEKA capability validation. See doc/architecture/Storage_Sharing_and_IAM_Model_v1.md.	A + B
Tenant/project landings	Mock has persona-specific overview pages with governance, spend, access, recent changes, and action bands.	Production routes now exist and backend shell mode defaults point to them. Remaining risk is dedicated tenant/project read models for richer governance and spend data.	A
Access identity/connectivity/audit	Mock has these as visible sub-surfaces, with some intentionally future-facing copy.	Production routes now exist and link to current source-of-record surfaces. Remaining risk is backend read-model depth for SSO integrations, network/security inventory, and filtered access audit.	A
Account overview and billing	Mock has profile/security/billing/session cards with personal attention items.	Production routes exist; verify copy/data density after route cutover. Billing remains intentionally lightweight until the billing epic.	B
Platform node/provisioning details	Mock includes node detail and lifecycle pivots.	Node detail, MAAS site detail, onboarding, and decommission details now exist with lifecycle operations, activity, and evidence pivots. Remaining risk is visual density plus live provider data completeness.	A + B
Notifications	Top-bar notification entry should open an inbox/panel model, not dump users into an unrelated surface.	/v3-prod/notifications now exists and /notifications cuts over to it. Remaining risk is live WS behavior and historical notification retention.	A
Developer resources	Developer downloads should survive cutover without becoming an eighth primary rail group.	/v3-prod/developer/downloads now exists and /developer + /developer/downloads cut over to it. Swagger/Redoc remain proxied utility pages until the docs portal is redesigned.	B

Read-Model Enrichment Principles

• Add richness to read models, not ad-hoc frontend fixture logic.
• Keep provider-specific details behind capability objects, especially storage because WEKA is first and VAST may follow.
• Keep sensitive data out of read models: no raw tokens, private keys, provider endpoints, mount secrets, or cluster credentials.
• Prefer normalized tab payloads over frontend inference when the data comes from multiple domains.
• If a field cannot be backed by real data yet, render a deliberate empty state instead of mock-looking static copy.

Detail Read-Model Contract

The workload and storage detail endpoints are the first production parity contracts that must carry mock-level page structure.

• Workload detail uses typed V3WorkloadDetailTabs: overview, connect, metrics, events, storage, and config. The backend owns lifecycle ordering, primary_action, metric source links, storage mount normalization, and safe effective config.
• Storage detail uses typed tabs for objects, mounted_workloads, access audiences, lifecycle, and events. Provider-specific details stay behind the provider capability object so WEKA-first and VAST-later do not fork the UI.
• Missing data is explicit through empty arrays and stable links, not static mock copy. Frontend pages should render those empty states instead of inventing fixtures.

External Architecture Review Cross-Checks

Keep doc/governance/External_Architectural_Review_2026-04.md in scope while closing parity gaps. The v3 cutover should not deepen known architecture issues.

Relevant review items for this work:

• cmd/api/routes.go is already too large. New v3 routes should continue using the domain registration split in routes_v3_readmodels_domains.go and avoid adding more unrelated handlers to the legacy route file.
• Idempotency is a top control-plane gap. New v3 mutating endpoints, including launch and future storage/access mutations, must use the v3 idempotent wrapper or the shared middleware pattern, not hand-rolled header checks.
• App platform is the strongest product differentiator. Workload detail parity must preserve app-backed workload types as first-class workload subtypes rather than splitting app instances into a separate competing surface.
• Tenant/project admin pages should not become generic admin dumps. If we add persona landings, they should answer governance, spend, access, and recent change questions directly.
• Existing V1 admin pages must decompose into Platform families, not migrate page-for-page. Use Ops, Lifecycle, Config, Evidence, Finance, and IAM routes; add detail routes only when a workflow needs stable drill-down. MAAS/provisioning and image/profile configuration belong under Config plus lifecycle task drill-downs, not a flat admin entity list.
• Storage/network/provider surfaces must stay provider-neutral. WEKA can be the first backend, but v3 data contracts should describe capabilities and lifecycle state rather than vendor-specific UI fields.
• E2E and queue consistency are called out as enforcement gaps. The v3 cutover should keep fail-closed Playwright mocks and queue-git-check in the acceptance path.

Cutover Recommendation

Do not use /v3 visual approval as proof that /v3-prod is ready. Before platform-control cutover, run a visual/data parity pass on:

1. /v3-prod/workloads
2. /v3-prod/workloads/{id} for compute plus one app-backed workload if seeded
3. /v3-prod/storage
4. /v3-prod/storage/{id}
5. /v3-prod/access
6. /v3-prod/access/connectivity, /v3-prod/access/identity, /v3-prod/access/audit
7. /v3-prod/evidence, /v3-prod/platform/evidence
8. /v3-prod/tenant/overview, /v3-prod/project/overview
9. /v3-prod/account
10. /v3-prod/platform/overview
11. /v3-prod/platform/lifecycle
12. /v3-prod/notifications
13. /v3-prod/developer/downloads
14. /v3-prod/schedulers

Any missing data should be classified as:

• read-model gap: add/extend /api/v1/v3/* contract and backend.
• rendering gap: frontend already receives the data but does not display it.
• seed gap: local/kind lacks persona or resource data needed to exercise the page.
• future-product gap: explicitly accepted and documented for post-cutover.