Skip to content

UX Journeys v0.4 (Target-State Baseline, Prototype-Informed)

Status: - Target-state baseline for implementation planning. - Prototype remains a mockup/reference input, not behavioral source of truth.

Sources: - product/PRD.md - api/openapi.draft.yaml - api/asyncapi.draft.yaml - product/UX_Redesign_Implementation_Plan.md - product/ux-mocks/product-redesign-v3/README.md - operations/prototype_current_behavior_spec.md (reference only)

1. Navigation / Information Architecture

Primary nav follows the redesign page-family model: - Overview: Home, Billing & Usage - Workloads: Active, Needs attention - Infrastructure: Catalog, Allocations, Storage - Apps: Browse & Deploy, Artifacts - Access: Projects, Team, SSH Keys, API Keys, Policies - Developer: Docs, Downloads, API Docs - Ops: Attention, Telemetry - Admin: Dashboard, Nodes, SKUs, OS Images, Allocations, Quotas, Users, Audit Logs, MAAS, Payment Sessions

Target UX uses the adopted v3 route model: - / - /workloads - /workloads/:id - /infra/catalog - /infra/allocations - /infra/allocations/:id - /launch - /tasks/:id - /billing - /access/* - /developer/* - /ops/* - /admin/*

2. Personas

  • End User: provision and operate GPUs.
  • Admin: monitor and manage users/nodes.
  • Billing Operator: inspect usage and payment outcomes.

3. Journey: Authentication

  1. User opens login screen.
  2. Selects account path:
  3. Work account -> enterprise SSO flow.
  4. Personal account -> direct sign-in or account creation flow.
  5. Work path:
  6. clicks "Continue with SSO" and is redirected to provider.
  7. returns to app and completes exchange flow.
  8. Personal path:
  9. sign in or create account using same username/password form.
  10. signup auto-bootstraps personal tenant + default project.
  11. On success, app stores session tokens and loads profile/nodes/allocations.
  12. First-run behavior:
  13. If balance is zero and user has no allocations, show "Add funds to get started" onboarding CTA and route user to Billing.
  14. Marketplace still renders read-only availability context.

UX requirements: - Inline auth error on failed login. - Session persistence with clear logout behavior. - Work and personal paths are visually separated (tab-style selection). - Enterprise hints are optional and advisory (work email or tenant slug).

Contract mapping: - GET /api/v1/auth/oidc/authorize - POST /api/v1/auth/oidc/exchange - POST /api/v1/auth/token/refresh - POST /api/v1/auth/logout - POST /api/v1/auth/personal/login - POST /api/v1/auth/personal/signup

4. Journey: Launch Workload

  1. Open /infra/catalog or click Launch from the top bar or workloads page.
  2. Review SKU cards with free GPU capacity and pricing context.
  3. Click Launch and enter /launch.
  4. Step through Hardware, Capacity, Image, Network, Access, and Review.
  5. Confirm once; the frontend creates one launch request with one idempotent submission path, not a client-side loop of per-node calls.
  6. App navigates to the provisioning task view and keeps the in-flight workload visible in operational lists.

UX requirements: - Clear precheck failures (sold out, insufficient balance, node offline). - Sold-out SKU cards must render as Unavailable (disabled provision action). - Launch must show estimated hourly cost before confirmation. - Launch is a full-page wizard, not a modal. - Slice GPU counts must be validated against same-node topology before submit where possible. - Pricing mode and idle-suspend controls may be visible but disabled until the backend supports them.

5. Journey: Operate Active Allocation

  1. Open /workloads.
  2. Use action buttons:
  3. Metrics: in-page overlay using platform metrics base URL config (no per-node metrics_url API field)
  4. Console: terminal modal (xterm), mint short-lived terminal token first
  5. Key: manage user public keys / copy SSH command
  6. Release: destructive confirmation modal

UX requirements: - Active/released states visually distinct. - Release confirmation explicit and cancellable. - Failed allocation state must show machine-readable failure_reason. - release_failed state must render release_failed_reason, confirm billing has stopped, and expose retry release action. - Metrics URL source is platform-level frontend configuration (or backend-proxied route), not node host metadata. - Active allocation views should show copy-ready SSH command built from allocation connection details. - Runtime key management uses user public keys; no persistent server-side private-key download endpoint. - Returning from detail to list should restore the prior list filters, search, and pagination state. - If an action changes allocation state, the UI must make the destination state discoverable immediately. Rows may move between status views, but they should not appear to disappear without a visible status-switch path.

Contract mapping: - POST /api/v1/allocations/{allocation_id}/terminal-token - WS /ws/terminal/{allocation_id} - POST /api/v1/allocations/{allocation_id}/release - GET /api/v1/allocations/{allocation_id} - GET /api/v1/ssh-keys - POST /api/v1/ssh-keys - DELETE /api/v1/ssh-keys/{key_id}

6. Journey: Track Provisioning / Async Work

  1. Submit a launch or open a resource with an active lifecycle task.
  2. Land on /tasks/:id.
  3. Follow step progression with explicit pending/active/completed/failed states.
  4. Open the related workload detail once handoff completes.

UX requirements: - The task view is the primary async surface, not an embedded status region only. - Task progress must survive refresh and reopen. - Long timelines load the newest events first and page older events from the backend. - In-flight slice allocations must appear in relevant list views as provisioning as soon as placement has reserved or provisioning state.

7. Journey: Billing and Payments

  1. Open Billing page.
  2. View current balance card.
  3. Enter deposit amount and trigger Stripe checkout.
  4. Return from Stripe with success/cancel indicators.
  5. Optionally open Stripe customer portal.
  6. Inspect usage history and export CSV.

UX requirements: - Balance warning visible when low. - Payment status feedback after redirect return. - Low-balance signaling must be persistent: top-page banner + billing card warning/depleted variants. - Billing page (or /billing/return) must handle Stripe return params and show success/cancel/error message. - Show estimated runtime hint derived from balance and active burn rate when available.

Contract mapping: - GET /api/v1/billing/balance - GET /api/v1/billing/usage (+ optional allocation_id, from, to, sort) - GET /api/v1/billing/usage/csv (+ optional allocation_id, from, to, sort) - POST /api/v1/payments/checkout-session - POST /api/v1/payments/customer-portal-session

8. Journey: Project Lifecycle

  1. Open /access/projects.
  2. Review projects visible to the current user in the current workspace/tenant.
  3. Create a project when the user has the required role.
  4. Open a project detail view to review core metadata, membership/access context, and related workload/app surfaces.
  5. Rename/update project metadata where allowed.
  6. Set a project as the default context for the current user.
  7. Delete a project only through an explicit destructive flow with impact explanation and backend policy enforcement.

UX requirements: - Project lifecycle must be a first-class page, not hidden only inside the top-bar project selector. - The project selector is for switching context; the projects page is for management. - Create project should be visible but secondary to the directory/list. - Delete project must clearly communicate impact, preconditions, and failure reasons when the backend rejects deletion. - Default project actions should be lightweight and available from both the directory row and project detail.

Contract mapping: - GET /api/v1/projects - POST /api/v1/projects - PATCH /api/v1/projects/{project_id} - DELETE /api/v1/projects/{project_id} - POST /api/v1/projects/{project_id}/set-default

9. Journey: Storage

Tabs: - Marketplace-driven storage purchase/plan UX (future work) - My Storage (real backend CRUD)

My Storage flow: 1. Navigate folders with breadcrumbs. 2. Upload/download files. 3. Create folder, rename, delete selected item.

UX requirements: - Prevent accidental deletes via confirmation (currently browser confirm). - Show file operation errors in modal/toast.

10. Journey: Developer Docs And App Builder Flow

  1. Open /developer/docs.
  2. Browse getting-started guidance, API references, downloads, and app-platform integration docs inside the product shell.
  3. Move between conceptual docs, API docs, and downloadable artifacts without losing product context.
  4. Follow linked app-platform guidance for service accounts, access credentials, project scope, and app UI extension behavior.

UX requirements: - The docs landing page must be a real developer center, not placeholder copy. - Swagger/Redoc should render in-shell or inside a shell-consistent embedded frame by default, not by spawning a separate browser window. - Downloads, API docs, examples, and app-platform guidance should feel like one connected experience. - App teams should be able to understand where platform shell behavior ends and app extension behavior begins without reverse-engineering page routes.

11. Journey: Admin Operations

Role boundary: - These /admin/* routes are Platform Admin operations (users.role=admin). - Tenant-admin operations are tenant-scoped and must be separated from platform admin surfaces.

Admin Overview

  • Aggregated cards: total GPUs, free nodes, active allocations, user count.
  • Auto-refresh every 5 seconds with visible last-updated indicator and pause toggle.

Admin Users

  • Create users, display role and balance, quick add funds (+$1000).
  • View single user profile + balance.
  • Request refunds with explicit policy outcome.

Admin Nodes

  • Add node with SSH credentials and probe option.
  • Probe connectivity.
  • Delete node.
  • In-use rows should surface active allocation/user reference for operator drilldown.

Admin Allocations

  • Cross-user allocation list with filters (user, node, status).
  • Force-release with explicit reason for emergency operations.

UX requirements: - Show action results for probe/delete/create. - Add safeguards for deleting in-use nodes. - Admin force-release requires explicit reason and confirmation. - Admin operational lists should default to newest-first sorting where recency is the primary operator need. - Fresh provisioning slice allocations must surface as provisioning in admin lists once placement has progressed, even if the allocation record is still requested. - Audit/investigation tables must provide a drilldown path to full event details; truncated IDs and targets are acceptable only if the full values and metadata are available in a row detail surface.

Contract mapping: - GET /api/v1/admin/overview - GET /api/v1/admin/users - GET /api/v1/admin/users/{user_id} - POST /api/v1/admin/users - POST /api/v1/admin/users/{user_id}/balance - POST /api/v1/admin/users/{user_id}/refunds - GET /api/v1/admin/nodes - POST /api/v1/admin/nodes - POST /api/v1/admin/nodes/{node_id}/probe - DELETE /api/v1/admin/nodes/{node_id} - GET /api/v1/admin/allocations - POST /api/v1/admin/allocations/{allocation_id}/force-release - GET /api/v1/admin/audit-logs - GET /api/v1/admin/audit-logs/export - GET /api/v1/admin/payments/sessions

12. Journey: Operate App Workloads

  1. Open /workloads.
  2. Review grouped workload states such as attention-needed, active, and other lifecycle buckets.
  3. Open a workload detail page for app-specific controls and runtime context.
  4. Take actions such as stop, start, restart, or investigate failures.

UX requirements: - Workload pages for apps and allocations must follow the same status/filter contract. - If an app leaves the active state because of a stop/fail/release action, the UI must make the new destination grouping visible rather than silently removing the row from the current page. - Grouped status sections should still coexist with a stable filter/view model so users can inspect history and non-active items.

13. Cross-Cutting UI States

Required per page: - Loading - Empty - Error - Success/confirmation - Restricted (role-gated)

Current implementation coverage: - Strong: empty/success basics - Partial: structured error and retry UX consistency

14. Accessibility and Responsive Requirements

  • Sidebar collapses on smaller screens.
  • Need formal keyboard/focus/aria requirements for modals and menus in final PRD.
  • Need contrast/accessibility validation across dark/light themes.

15. UX Gaps to Resolve

  • Batch provisioning UX should be asynchronous and cancellable.
  • Placeholder pages should be labeled with maturity level to avoid user confusion.
  • Define notification text and UX for refund outcomes (internal credit vs provider refund).
  • Shared table and list behavior should be codified in reusable components so sort, filter, pagination, row actions, and back-navigation stay consistent.
  • Project lifecycle currently exists in API but is missing as a routed UI product surface; that gap should be closed before the top-bar project context model is considered complete.
  • Developer/docs surfaces still need a coherent in-shell docs center and API reference experience instead of placeholder pages and awkward context breaks.
  • Workbench pages still need consistent empty-result behavior and predictable status transitions after mutations.
  • Evidence/audit pages still need a standard drilldown pattern for full row details.

16. Pre-Coding UX Deliverables (Required)

  • Screen inventory with route names and ownership.
  • Low-fidelity wireframes for core journeys (Auth, Provision, Operate, Billing, Admin).
  • State matrix per screen (loading/empty/error/success/restricted/rate-limited).
  • Accessibility checklist: keyboard traversal, focus trap, aria labels, contrast.
  • Contract-to-UI traceability table (every action maps to OpenAPI/AsyncAPI operation).