# 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:
   - `Work account` -> enterprise SSO flow.
   - `Personal account` -> direct sign-in or account creation flow.
3. Work path:
   - clicks "Continue with SSO" and is redirected to provider.
   - returns to app and completes exchange flow.
4. Personal path:
   - sign in or create account using same username/password form.
   - signup auto-bootstraps personal tenant + default project.
5. On success, app stores session tokens and loads profile/nodes/allocations.
6. First-run behavior:
   - If balance is zero and user has no allocations, show "Add funds to get started"
     onboarding CTA and route user to Billing.
   - 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:
   - Metrics: in-page overlay using platform metrics base URL config (no per-node `metrics_url` API field)
   - Console: terminal modal (xterm), mint short-lived terminal token first
   - Key: manage user public keys / copy SSH command
   - 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.
- Small tenants create projects without choosing a department. The API assigns
  the tenant's default department when `department_id` is omitted.
- Department selectors, filters, and department-required project creation appear
  only after multiple departments exist or department context capabilities are
  enabled.
- Department visibility does not imply department admins, budgets, policy
  inheritance, or approval workflows. Each of those capabilities requires its
  own shipped surface and authorization model.
- 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).