Solver Onboarding

After a solver application is approved and the applicant creates their account, they enter the onboarding phase. The onboarding checklist ensures new solvers understand the platform, complete required training, and set up their profile before going live.

Onboarding Flow

New solvers with status: "onboarding" are redirected to /onboarding where they see a checklist of required steps. Only after completing all steps can they activate their account and start accepting tickets.

Required Steps

The onboarding checklist includes these steps:

1. Complete Your Profile

Solvers must add their display name and phone number. This information is visible to customers during sessions.

Completion Criteria: Profile has name and phone number set.

2. Watch Training Video

An introductory video covering platform basics, customer interaction guidelines, and tool usage.

Completion Criteria: Solver marks video as watched.

3. Read Solver Handbook

The handbook contains policies, best practices, and support scenarios. Available at /docs/guides/solver-getting-started.

Completion Criteria: Solver confirms they've read the handbook.

4. Complete Practice Session

A simulated support interaction to familiarize solvers with the session interface, chat, and screen sharing tools.

Completion Criteria: Solver completes the practice scenario.

5. Background Check (Employed Solvers Only)

For solvers with employment: "employed", HR must verify their background check. This step is controlled by admins, not the solver.

Completion Criteria: Admin marks background check as passed.

Onboarding Progress Schema

Progress is stored as a JSONB column on the solver record:

export interface OnboardingProgress {
  profileCompleted: boolean;
  trainingVideoWatched: boolean;
  handbookRead: boolean;
  practiceSessionCompleted: boolean;
  backgroundCheckPassed: boolean | null; // null = not required (contract)
}

// Default progress for new solvers
const defaultOnboardingProgress: OnboardingProgress = {
  profileCompleted: false,
  trainingVideoWatched: false,
  handbookRead: false,
  practiceSessionCompleted: false,
  backgroundCheckPassed: null,
};

The backgroundCheckPassed field is null for contract solvers (not applicable) and false/true for employed solvers.

API Reference

solvers.getOnboardingStatus

Returns the current onboarding state for the authenticated solver.

// Returns
{
  status: "onboarding" | "available" | "busy" | "offline",
  isComplete: boolean,
  completionPercent: number,
  progress: OnboardingProgress,
  isEmployed: boolean,
  user: {
    name: string | null,
    email: string,
    phone: string | null,
  }
}

The completionPercent is calculated based on required steps only—employed solvers have 5 required steps, contract solvers have 4.

solvers.updateOnboardingStep

Updates a single onboarding step. Used when solver completes a self-service step.

// Input
z.object({
  step: z.enum([
    "profileCompleted",
    "trainingVideoWatched",
    "handbookRead",
    "practiceSessionCompleted",
  ]),
  completed: z.boolean(),
})

// Returns
{ success: true, progress: OnboardingProgress }

solvers.completeOnboarding

Validates all required steps are complete and activates the solver account.

// Validation logic
const requiredSteps = [
  progress.profileCompleted,
  progress.trainingVideoWatched,
  progress.handbookRead,
  progress.practiceSessionCompleted,
];

if (isEmployed) {
  requiredSteps.push(progress.backgroundCheckPassed === true);
}

// If all complete, set status to "available"

On success, the solver's status changes from "onboarding" to "available" and they can access the main dashboard.

Onboarding UI

The onboarding page at /onboarding displays:

• Progress Bar - Visual indicator of completion percentage
• Step Cards - Each step with icon, description, and action button
• Completion State - Green checkmarks for completed steps
• Activation Button - Appears when all steps are complete

// Step card structure
interface OnboardingStep {
  id: string;
  key: keyof OnboardingProgress;
  title: string;
  description: string;
  icon: React.ComponentType;
  action: string;
  href?: string; // Link for navigation steps
}

Steps with an href (like Profile and Handbook) navigate to external pages. Steps without href (like Video and Practice) show inline content.

Status Restrictions

While in status: "onboarding", solvers cannot:

• Change their availability status
• Access the ticket queue
• Claim or work on sessions

The hasCompletedOnboarding helper function checks solver status:

export function hasCompletedOnboarding(status: string): boolean {
  return status !== "onboarding";
}

This is used in the updateStatus procedure and other protected routes.

Admin Controls

Admins can view solver onboarding progress and manually update steps if needed (e.g., marking background check complete). This is accessible through the admin dashboard's solver management section.

Completion Flow

When a solver clicks "Start Solving" after completing all steps:

1. completeOnboarding mutation is called
2. Server validates all required steps
3. If valid, solver status is set to "available"
4. Solver is redirected to /dashboard
5. They can now toggle availability and accept tickets

Related Documentation

• Solver Applications - Application and approval process
• Dashboard - Main solver interface
• Getting Started Guide - End-user guide for new solvers