C.1: Client Onboarding

Summary

Client onboarding starts when an authenticated user has not yet selected a role. The user chooses the Client role on /onboarding, is routed to the dashboard, then completes a client profile modal with first name, last name, and recording consent.

Role

• Primary: Client
• Secondary: System, Supabase Auth

Entry Point

• URL: /onboarding
• Redirect: / or /dashboard routes the user to onboarding when account_type is unassigned
• Follow-up: /dashboard opens the client profile modal when onboarding_completed is false

Preconditions

• Authenticated: yes
• Required role: unassigned before role selection, client after role selection
• The current user profile must load from useCurrentUser / useOnboardingStatus

Steps

1. User signs in and reaches the app entry route.
2. System loads the current user profile.
3. If the profile is unassigned, system redirects the user to /onboarding.
4. User selects the Client role.
5. System calls the onboarding role endpoint through useSetOnboardingRole.
6. On success, system refetches the current profile and navigates to /dashboard.
7. Client dashboard renders and opens ClientProfileModal if onboarding is not complete.
8. User enters first name and last name.
9. User accepts recording consent linked to terms and privacy policy.
10. User submits the modal.
11. System submits onboarding steps for profile data, recording consent, and final completion.
12. System invalidates/refetches the current user profile and leaves the client on the dashboard.

Diagram

Edge Cases

• Profile loading: The app shows a spinner while user/profile data is loading.
• Profile load failure: Dashboard shows a retry state when the profile request fails.
• Already assigned role: /onboarding redirects to /dashboard if onboarding is already complete or the user is no longer unassigned.
• Incomplete modal: The Complete button is disabled until first name, last name, and recording consent are present.
• Submit failure: The modal shows the generic onboarding submit error and stays open.
• Development preview: /dev/onboarding can preview the client modal without writing onboarding data.

Screenshot Status

• Captured with Playwright on 2026-04-17 using dev-only onboarding preview data:
  • Role selection:
  • Client profile empty state:
  • Client profile ready-to-submit state:

Related Flows

• C.2 Client Dashboard
• C.10 Profile