13 - E2E Workflows & Navigation Scenes

Purpose

This document maps every user workflow, navigation path, and testable scene in the WAVIC app. Use it to:

Run manual or automated E2E testing covering all scenarios
Verify no flow is broken after code changes
Onboard new developers to the full user journey
Plan QA sprints with clear test case coverage

Route Map

Protected Routes (require authentication)

Route	Short URL	Page	Layout
`/`	—	Home / Artist Spaces Dashboard	hydrogen
`/onboarding`	—	4-step onboarding wizard	hydrogen
`/new-artist`	—	Create new artist space	hydrogen
`/artist/[artistId]`	`/a/[id]`	Artist space detail	hydrogen
`/project/[projectId]`	`/p/[id]`	Project detail (with WaveContext)	hydrogen
`/wave/[trackId]`	`/t/[id]`	Track / waveform editor	hydrogen
`/profile`	—	User public profile	hydrogen
`/search`	—	Global search	hydrogen
`/library`	—	Audio file library	hydrogen
`/transfers`	—	Shared content inbox	hydrogen
`/storage`	—	Storage usage	hydrogen
`/trash`	—	Deleted items	hydrogen
`/user/profile-settings`	—	Personal info	hydrogen/user
`/user/profile-settings/profile`	—	Edit profile	hydrogen/user
`/user/profile-settings/password`	—	Change password	hydrogen/user
`/user/profile-settings/notification`	—	Notification prefs	hydrogen/user
`/user/profile-settings/integration`	—	Integrations	hydrogen/user
`/user/profile-settings/team`	—	Team management	hydrogen/user
`/user/subscription`	—	Subscription & billing	hydrogen/user
`/user/subscription/payment`	—	Stripe checkout	hydrogen/user
`/user/subscription/checkout`	—	Post-payment confirmation	hydrogen/user
`/user/subscription/manage`	—	Manage subscription	hydrogen/user
`/user/usage`	—	Usage stats	hydrogen/user

Public Routes (no authentication required)

Route	Page	Layout
`/signin`	Sign in (legacy)	—
`/auth/sign-in`	Sign in (branded)	auth
`/auth/sign-up`	Sign up	auth
`/auth/forgot-password`	Forgot password	auth
`/auth/otp`	OTP verification	auth
`/reset-password`	Reset password	—
`/flash?linkId=`	Shared audio player (public link)	other-pages
`/welcome`	Welcome/landing	other-pages
`/coming-soon`	Coming soon	other-pages
`/maintenance`	Maintenance	other-pages
`/access-denied`	Access denied	other-pages
`/link-expired`	Link expired	other-pages
`/not-found`	404	other-pages
`/request-access`	Beta waitlist	other-pages

Workflow 1: Authentication

/auth/sign-up
  ├─ Fill: full name, email, password
  ├─ Submit → POST /user/signup
  ├─ Success → auto sign-in → /onboarding (step 1)
  └─ Error: email taken → toast "Email already in use"

Test cases:

[ ] Sign up with valid credentials → lands on onboarding step 1
[ ] Sign up with existing email → shows error toast
[ ] Sign up with weak password → validation message
[ ] Sign up with Google OAuth → redirects to Google → returns to app
[ ] Empty fields → validation prevents submit

/auth/sign-in
  ├─ Credentials (email + password)
  │   ├─ Success + no username → /onboarding (step 1)
  │   ├─ Success + username + !onboardingCompleted → /onboarding (step 2+)
  │   ├─ Success + onboardingCompleted → / (home)
  │   └─ Error → toast "Invalid credentials"
  ├─ Google OAuth
  │   └─ Same routing logic as credentials
  └─ "Forgot password?" → /auth/forgot-password

Test cases:

[ ] Sign in with valid credentials → correct redirect based on onboarding status
[ ] Sign in with wrong password → error feedback
[ ] Sign in with non-existent email → error feedback
[ ] Google OAuth → success → correct redirect
[ ] Forgot password link → navigates to forgot-password page
[ ] After sign-in, session contains token, user._id, username, image

W1.3 — Password Recovery

/auth/forgot-password → enter email → POST /user/forgot-password
  └─ /auth/otp → enter code → verify
      └─ /reset-password → new password → POST /user/reset-password
          └─ /auth/sign-in

Test cases:

[ ] Request reset for valid email → OTP sent
[ ] Request reset for non-existent email → appropriate feedback
[ ] Valid OTP → advances to reset page
[ ] Invalid OTP → error message
[ ] Reset with new password → success → redirect to sign-in

W1.4 — Sign Out

Profile menu → "Logout" → next-auth signOut()
  └─ /signin

Test cases:

[ ] Sign out clears session
[ ] Protected routes redirect to /signin after sign-out
[ ] Session token is invalidated

Workflow 2: Onboarding

W2.1 — Full Onboarding (New User)

Step 1: Username
  ├─ Type username → Enter/Click "Enter"
  ├─ → PUT /user { username } + POST /track/onboarding { defaultName }
  ├─ Username taken → toast "Username not Available"
  └─ Success → step 2

Step 2: Profile Photo
  ├─ Click upload circle or drag-and-drop image
  ├─ Preview shows in circular avatar
  ├─ Enter/Click "Enter" → PUT /user/picture (FormData)
  ├─ "Skip" → step 3 (no upload)
  └─ Success → step 3

Step 3: Features Overview
  ├─ Shows feature cards
  ├─ Click "Finish" → PATCH marks onboardingCompleted = true
  └─ Success → step 4

Step 4: Upload Audio
  ├─ 3D CD animation + drag-and-drop area
  ├─ Upload audio file → POST /track/onboarding/:trackId (progress bar)
  ├─ 100% → redirect to /wave/:trackId
  ├─ "Skip" → / (home)
  └─ Enter → / (home)

Test cases:

[ ] Complete all 4 steps → user has username, photo, track with audio
[ ] Skip step 2 → no photo uploaded, advances to step 3
[ ] Skip step 4 → goes to home, track exists but no audio
[ ] Enter key works at every step (including step 2 after uploading photo)
[ ] Drag-and-drop image in step 2 → preview shows → can advance
[ ] Upload image via click in step 2 → preview shows → can advance
[ ] Username taken → error toast, stays on step 1
[ ] Refresh on step 2 → eligibility check finds track, skips to step 2
[ ] Refresh on step 3+ → eligibility check does NOT reset back to step 2

W2.2 — Returning User (Incomplete Onboarding)

Sign in → GET /track/onboarding
  ├─ Track exists + onboardingCompleted = false → /onboarding step 2
  ├─ Track exists + onboardingCompleted = true → / (home)
  └─ No track + no username → /onboarding step 1

Test cases:

[ ] User with username but no onboardingCompleted → resumes at step 2
[ ] User with onboardingCompleted = true → goes to home

W2.3 — Replay Onboarding

Profile menu → "Replay Onboarding"
  ├─ PUT /user { onboardingCompleted: false }
  ├─ Updates session
  └─ → /onboarding

Test cases:

[ ] Replay button resets flag and navigates to onboarding
[ ] Onboarding flow completes normally after replay
[ ] After replay completion, onboardingCompleted is true again

Workflow 3: Artist Space Management

W3.1 — Create Artist Space

/ (home) → "+ New Artist" or /new-artist
  ├─ Enter artist name + optional image
  ├─ POST /artistspace
  └─ Success → /artist/:artistId

Test cases:

[ ] Create with name only → artist space created
[ ] Create with name + image → image uploaded to Azure
[ ] Duplicate name handling
[ ] Empty name → validation error

W3.2 — View/Edit Artist Space

/artist/:artistId  (or /a/:shortId)
  ├─ View artist info, projects, team members
  ├─ Edit artist name/image (owner/admin only)
  ├─ Delete artist space (owner only)
  └─ Share → generate shareable link

Test cases:

[ ] Owner sees edit/delete controls
[ ] Viewer does NOT see edit/delete controls
[ ] Short URL /a/xxx resolves to same content as /artist/fullId
[ ] Non-existent ID → 404 handling
[ ] Edit name → updates in real-time
[ ] Upload new image → replaces old image

W3.3 — Invite Collaborator

Artist page → Share → Generate link with role
  ├─ Copy link → recipient opens link
  ├─ /artist/:id?artistId=xxx → invite modal appears
  ├─ Accept → collaborator added
  └─ Decline → no change

Test cases:

[ ] Generate share link with Viewer role → link works
[ ] Generate share link with Editor role → link works
[ ] Accept invite → artist appears in recipient's transfers
[ ] Invite link for non-authenticated user → redirect to sign-in → then back
[ ] Owner cannot invite themselves

Workflow 4: Project Management

W4.1 — Create Project

/artist/:artistId → "+ New Project"
  ├─ Enter project name, type (Album/EP/Single)
  ├─ POST /project
  └─ Success → /project/:projectId

W4.2 — View/Edit Project

/project/:projectId  (or /p/:shortId)
  ├─ View tracks list (6 layout modes)
  ├─ Drag-and-drop reorder tracks
  ├─ Edit project name/metadata
  └─ Delete project (owner only)

Test cases:

[ ] Create project in each type → correct metadata
[ ] 6 layout modes render correctly (list, grid, board, etc.)
[ ] Drag-and-drop reorder → order persists after refresh
[ ] Short URL resolves correctly
[ ] Edit project name → updates

Workflow 5: Track Management

W5.1 — Create Track

/project/:projectId → "+ New Track" or drag-and-drop audio file
  ├─ POST /track { projectId, name }
  └─ Success → track appears in project

W5.2 — Track Detail / Waveform Editor

/wave/:trackId  (or /t/:shortId)
  ├─ Waveform visualization (WaveSurfer.js)
  ├─ Play/Pause/Seek/Volume controls
  ├─ Switch between audio versions
  ├─ Add timestamped comments
  ├─ Edit track metadata
  ├─ Upload new audio version
  ├─ Upload attachments (PDFs, images)
  └─ Change track status (7-stage workflow)

Test cases:

[ ] Waveform renders for uploaded audio
[ ] Play/pause works
[ ] Seek on waveform → playback jumps
[ ] Volume control works
[ ] Switch audio version → waveform updates
[ ] Add comment at timestamp → appears on waveform
[ ] Upload new audio version → version list updates
[ ] Upload attachment → appears in attachments list
[ ] Change status → status badge updates
[ ] Track status workflow: Not Started → In Progress → Review → Revision → Approved → Mix/Master → Completed

W5.3 — Track Status Workflow

Not Started ──► In Progress ──► Review ──► Revision ──► Approved ──► Mix/Master ──► Completed
     │              │             │           │            │              │
     └──────────────┴─────────────┴───────────┴────────────┴──────────────┘
     (can move forward/backward between any status)

W5.4 — Audio Upload (Global Drag & Drop)

Any page in (hydrogen) layout → drag audio file over page
  ├─ MainComponent dropzone activates
  ├─ Drop → upload to current context (project/track)
  └─ Toast notification on success/error

Test cases:

[ ] Drag audio file onto project page → creates track + uploads
[ ] Drag audio file onto track page → adds new version
[ ] Drag non-audio file → rejection/error handling
[ ] Multiple files dropped → handles appropriately

Artist/Project/Track → Share button
  ├─ Generate link with role (Viewer/Editor/Admin)
  ├─ Copy link
  └─ Recipient opens link → accepts invite

W6.2 — Public Flash Player

/flash?linkId=xxx  (NO auth required)
  ├─ Fetches track via GET /link/:linkId
  ├─ Renders audio player with waveform
  ├─ Link expired → "Link expired" message
  └─ Invalid link → error state

Test cases:

[ ] Valid flash link → audio plays
[ ] Expired link → expiry message
[ ] Non-existent linkId → error
[ ] Flash player works without sign-in

W6.3 — Transfers View

/transfers
  ├─ Lists all content shared with user
  ├─ Click item → navigate to artist/project/track
  └─ Accept/decline pending invites

Workflow 7: Account Settings

W7.1 — Personal Info

/user/profile-settings
  ├─ View/edit full name, email, username
  ├─ Upload/change profile picture
  └─ Save → PUT /user

W7.2 — Password Change

/user/profile-settings/password
  ├─ Current password + new password + confirm
  └─ Save → PUT /user/password

W7.3 — Subscription & Billing

/user/subscription
  ├─ View current plan
  ├─ "Upgrade" → /user/subscription/payment?priceId=xxx
  │     └─ Stripe embedded checkout → /user/subscription/checkout?session_id=xxx
  └─ "Manage" → /user/subscription/manage

Test cases:

[ ] View current subscription status
[ ] Upgrade triggers Stripe checkout
[ ] Post-payment redirect shows confirmation
[ ] Cancel subscription works

W8.1 — Global Search

/search  or  Cmd+K / sidebar search
  ├─ Search across artists, projects, tracks
  ├─ Click result → navigate to item
  └─ Recent searches shown

Sidebar (always visible in hydrogen layout)
  ├─ Home → /
  ├─ Search → /search
  ├─ Library → /library
  ├─ Transfers → /transfers
  ├─ Storage → /storage
  ├─ Trash → /trash
  └─ Artist spaces (expandable tree)
       ├─ Artist → /artist/:id
       │   └─ Projects → /project/:id
       │       └─ Tracks → /wave/:id

W8.3 — Short URLs

/a/:shortId  →  resolves to  /artist/:fullId
/p/:shortId  →  resolves to  /project/:fullId
/t/:shortId  →  resolves to  /wave/:fullId

Test cases:

[ ] Each short URL resolves to the correct resource
[ ] Non-existent short ID → 404 or access-denied
[ ] Short URLs work for shared content (respecting role)

Workflow 9: Error & Edge Cases

W9.1 — Authentication Errors

[ ] Access protected route while signed out → redirect to /signin
[ ] Expired JWT token → redirect to sign-in
[ ] Invalid token → redirect to sign-in

W9.2 — Authorization Errors

[ ] Access another user's artist space → /access-denied
[ ] Viewer tries to edit → read-only UI enforced
[ ] Editor tries to delete → no delete button shown

W9.3 — Network Errors

[ ] API unreachable → graceful error state
[ ] File upload fails mid-way → error toast + retry option
[ ] Slow connection → loading states visible

W9.4 — Data Edge Cases

[ ] Empty dashboard (no artists) → empty state with CTA
[ ] Project with 0 tracks → empty state
[ ] Track with no audio versions → upload prompt
[ ] Very long artist/project/track names → truncation
[ ] Special characters in names → proper encoding

Console Log Reference

All onboarding logs are prefixed with 📋 Onboarding: for easy filtering:

Log	When
`📋 Onboarding: Step N → handleClick`	User clicks Enter/Next at step N
`📋 Onboarding: Username saved`	Step 1 username PUT succeeded
`📋 Onboarding: Photo uploaded, advancing to step 3`	Step 2 photo PUT succeeded
`📋 Onboarding: Marked complete, advancing to step 4`	Step 3 marked onboardingCompleted
`📋 Onboarding: Advancing N → N+1`	Step transition confirmed
`📋 Onboarding: Existing track found, skipping to step 2`	Returning user, track already created
`📋 Onboarding: handleClick error: ...`	Any error in handleClick
`📋 Onboarding: Eligibility check error: ...`	Eligibility check failed

Backend logs use emojis for quick scanning:

📤 File upload started
📁 File processing
✅ Success
📎 SAS URL generated
🌐 CDN URL
🔐 Auth/interceptor events
🔙 Route handler entry

Test Execution Checklist

Smoke Test (5 min)

[ ] Sign up with new email → onboarding completes → home page loads
[ ] Sign in with existing user → correct page loads
[ ] Create artist → create project → create track → upload audio → waveform plays
[ ] Sign out → protected route redirects to sign-in

Core Flow Test (15 min)

[ ] Full onboarding: all 4 steps with uploads
[ ] Onboarding: skip photo + skip audio → still works
[ ] Onboarding: refresh mid-flow → resumes correctly (doesn't reset)
[ ] Replay onboarding from profile menu
[ ] Create artist with image → edit name → delete
[ ] Create project → add track → change status through all 7 stages
[ ] Upload audio → play → seek → volume → version switch
[ ] Add timestamped comment on track
[ ] Share artist via link → open in incognito → accept invite
[ ] Flash player with valid link (no auth)

Regression Test (30 min)

All of the above, plus:

[ ] Every short URL (/a/, /p/, /t/) resolves correctly
[ ] Profile settings: change name, photo, password
[ ] Subscription flow (if Stripe configured)
[ ] Search returns results for artists, projects, tracks
[ ] Trash: delete item → appears in trash → restore
[ ] Transfers: shared items appear correctly
[ ] Mobile responsive: onboarding, home, track page
[ ] Dark mode toggle: all pages render correctly
[ ] Enter key works on every onboarding step
[ ] Drag-and-drop upload on project and track pages

13 - E2E Workflows & Navigation Scenes ​

Purpose ​

Route Map ​

Protected Routes (require authentication) ​

Public Routes (no authentication required) ​

Workflow 1: Authentication ​

W1.1 — Sign Up (New User) ​

W1.2 — Sign In (Existing User) ​

W1.3 — Password Recovery ​

W1.4 — Sign Out ​

Workflow 2: Onboarding ​

W2.1 — Full Onboarding (New User) ​

W2.2 — Returning User (Incomplete Onboarding) ​

W2.3 — Replay Onboarding ​

Workflow 3: Artist Space Management ​

W3.1 — Create Artist Space ​

W3.2 — View/Edit Artist Space ​

W3.3 — Invite Collaborator ​

Workflow 4: Project Management ​

W4.1 — Create Project ​

W4.2 — View/Edit Project ​

Workflow 5: Track Management ​

W5.1 — Create Track ​

W5.2 — Track Detail / Waveform Editor ​

W5.3 — Track Status Workflow ​

W5.4 — Audio Upload (Global Drag & Drop) ​

Workflow 6: Collaboration & Sharing ​

W6.1 — Share via Link ​

W6.2 — Public Flash Player ​

W6.3 — Transfers View ​

Workflow 7: Account Settings ​

W7.1 — Personal Info ​

W7.2 — Password Change ​

W7.3 — Subscription & Billing ​

Workflow 8: Search & Navigation ​

W8.1 — Global Search ​

W8.2 — Sidebar Navigation ​

W8.3 — Short URLs ​

Workflow 9: Error & Edge Cases ​

W9.1 — Authentication Errors ​

W9.2 — Authorization Errors ​

W9.3 — Network Errors ​

W9.4 — Data Edge Cases ​

Console Log Reference ​

Test Execution Checklist ​

Smoke Test (5 min) ​

Core Flow Test (15 min) ​

Regression Test (30 min) ​

13 - E2E Workflows & Navigation Scenes

Purpose

Route Map

Protected Routes (require authentication)

Public Routes (no authentication required)

Workflow 1: Authentication

W1.1 — Sign Up (New User)

W1.2 — Sign In (Existing User)

W1.3 — Password Recovery

W1.4 — Sign Out

Workflow 2: Onboarding

W2.1 — Full Onboarding (New User)

W2.2 — Returning User (Incomplete Onboarding)

W2.3 — Replay Onboarding

Workflow 3: Artist Space Management

W3.1 — Create Artist Space

W3.2 — View/Edit Artist Space

W3.3 — Invite Collaborator

Workflow 4: Project Management

W4.1 — Create Project

W4.2 — View/Edit Project

Workflow 5: Track Management

W5.1 — Create Track

W5.2 — Track Detail / Waveform Editor

W5.3 — Track Status Workflow

W5.4 — Audio Upload (Global Drag & Drop)

Workflow 6: Collaboration & Sharing

W6.1 — Share via Link

W6.2 — Public Flash Player

W6.3 — Transfers View

Workflow 7: Account Settings

W7.1 — Personal Info

W7.2 — Password Change

W7.3 — Subscription & Billing

Workflow 8: Search & Navigation

W8.1 — Global Search

W8.2 — Sidebar Navigation

W8.3 — Short URLs

Workflow 9: Error & Edge Cases

W9.1 — Authentication Errors

W9.2 — Authorization Errors

W9.3 — Network Errors

W9.4 — Data Edge Cases

Console Log Reference

Test Execution Checklist

Smoke Test (5 min)

Core Flow Test (15 min)

Regression Test (30 min)