Onboarding System Technical Reference

User Signup
    ↓
OTP Verification
    ↓
ProfileOrchestrationService (auto-creates Practitioner/Tenant)
    ↓
Redirect to /connect
    ↓
OnboardingModal (Dialog overlay)
    ↓
Role-based step wizard
    ↓
POST /identity/users/:id/onboarding
    ↓
Connect Dashboard (with CTA banners)

frontend/apps/shell/src/
├── components/identity/
│   └── OnboardingModal.tsx          # Main orchestrator
└── pages/identity/
    ├── OnboardingPage.tsx          # Redirect only
    └── onboarding/
        ├── ProfileBasicsStep.tsx   # Step 1
        ├── ProfessionalIdentityStep.tsx  # Step 2
        └── ProfileImportStep.tsx  # Step 3

frontend/apps/connect/src/
├── components/identity/
│   ├── FacilitySetupCTA.tsx       # Facility owner CTA
│   └── IdentityProfileCompletionBanner.tsx  # Profile prompts
└── pages/
    └── FacilitySetupPage.tsx      # Placeholder

def show
  practitioner = current_user.practitioner
  if practitioner
    authorize practitioner, policy_class: MyPractitionerPolicy
    render_blueprint(practitioner, PractitionerBlueprint, view: :detailed)
  else
    render_success(data: nil)
  end
end

def update
  authorize @practitioner, policy_class: MyPractitionerPolicy
  if @practitioner.update(practitioner_params)
    render_blueprint(@practitioner, PractitionerBlueprint, view: :detailed)
  else
    render_validation_errors(@practitioner.errors.full_messages)
  end
end

def practitioner_params
  params.require(:practitioner).permit(
    :first_name, :last_name, :display_name, :gender, :birth_date,
    :avatar_url, :bio, :experience_years, :external_profile_url,
    languages: [],
    qualifications: [:code, :issuer, :year, :specialty],
    identifiers: [:system, :value, :state]
    # `specialties` is intentionally NOT permitted (see #2005). The column was
    # retired by #1853; specialties are facility-scoped (practitioner_role_specialties)
    # and set via the role, not this self-serve update.
  )
end

# Triggers SaveOnboardingService which:
# 1. Validates input (64KB limit)
# 2. Saves onboarding_data to user record
# 3. If current_step == total_steps, calls user.complete_onboarding!

class MyPractitionerPolicy < Shared::BasePolicy
  def show?
    own_practitioner?
  end

  def update?
    own_practitioner?
  end

  private

  def own_practitioner?
    record.user_id == user.id
  end
end

scope :my do
  resources :invites, only: %i[index], controller: 'my_invites' do
    member do
      post :accept
      post :decline
    end
  end

  resource :practitioner, only: %i[show update], controller: 'my_practitioner'
end

class SaveOnboardingService < BaseService
  MAX_ONBOARDING_DATA_SIZE = 64.kilobytes

  def call
    validation_result = validate_input
    return validation_result if validation_result&.failure?

    save_onboarding_data
    check_completion_status
    success(user.reload)
  end

  private

  def validate_input
    return failure('Onboarding data is required') if params.blank?
    return failure('User is required') if user.blank?
    return failure('Onboarding data is too large') if params.to_json.bytesize > MAX_ONBOARDING_DATA_SIZE
  end

  def check_completion_status
    current_step = params[:current_step]&.to_i || 0
    total_steps = params[:total_steps]&.to_i || 0
    return unless current_step == total_steps && total_steps.positive?
    user.complete_onboarding!
  end
end

add_column 'identity.practitioners', :external_profile_url, :string, limit: 500

view :detailed do
  include_view :normal
  fields :avatar_url, :bio, :languages, :qualifications, :identifiers,
         :birth_date, :user_id, :experience_years, :external_profile_url

  field :specialties do |practitioner|
    practitioner.specialty_names.presence || practitioner.specialties_from_qualifications
  end
end

validates :avatar_url, format: {
  with: URI::DEFAULT_PARSER.make_regexp(%w[http https]),
  message: 'must be a valid HTTP(S) URL'
}, allow_blank: true

const STEPS_BY_ROLE: Record<string, OnboardingStep[]> = {
  practitioner: ['profile-basics', 'professional-identity', 'profile-import'],
  facility: ['profile-basics'],
}

const shouldShow = !isDismissed
  && !user?.onboarding_completed
  && (signedUpAs === 'practitioner' || signedUpAs === 'facility')

// 1. Get presigned URL
const urls = await generateUrls.mutateAsync([
  { bucket, file_path: `users/${user.id}/avatar.${ext}` },
])

// 2. Upload directly to S3
const uploadResponse = await fetch(urls[0], {
  method: 'PUT',
  body: file,
  headers: { 'Content-Type': file.type },
})

if (!uploadResponse.ok) {
  throw new Error(`Upload failed with status ${uploadResponse.status}`)
}

// 3. Store clean URL
setAvatarUrl(urls[0].split('?')[0])

const promises: Promise<unknown>[] = []

// Update user (photo + email)
if (avatarUrl || data.email) {
  promises.push(apiClient.patch(`/identity/users/${user.id}`, {
    user: { avatar_url: avatarUrl, email: data.email }
  }))
}

// Update practitioner (bio - practitioners only)
if (data.bio && user?.is_practitioner) {
  promises.push(apiClient.patch('/identity/my/practitioner', {
    practitioner: { bio: data.bio }
  }))
}

await Promise.all(promises)

const profileBasicsSchema = z.object({
  bio: z.string().max(500).optional(),
  email: z.string().email().optional().or(z.literal('')),
})

await apiClient.patch('/identity/my/practitioner', {
  practitioner: {
    experience_years: experienceYears,
    identifiers: data.registration_number
      ? [{ system: 'registration', value: data.registration_number }]
      : undefined,
  }
})

await apiClient.patch('/identity/my/practitioner', {
  practitioner: { external_profile_url: data.external_profile_url }
})

export function useMyPractitioner(enabled = true) {
  return useQuery({
    queryKey: identityKeys.myPractitioner.detail(),
    queryFn: () => getMyPractitioner(),
    enabled,
  })
}

const draftProfile = availableProfiles.find(
  (p) => p.tenant?.status === 'draft'
)
if (!draftProfile) return null

useAuthStore.setState((state) => ({
  user: state.user
    ? { ...state.user, onboarding_completed: true }
    : state.user
}))

GET /identity/my/practitioner
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "John",
    "last_name": "Doe",
    "display_name": "Dr. John Doe",
    "bio": "Experienced cardiologist...",
    "experience_years": 15,
    "external_profile_url": "https://www.practo.com/dr-john-doe",
    "specialties": [
      { "id": "uuid", "name": "Cardiology", "is_primary": true }
    ],
    "identifiers": [
      { "system": "registration", "value": "MCI-12345" }
    ]
  }
}

PATCH /identity/my/practitioner
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "practitioner": {
    "experience_years": 15,
    "identifiers": [{ "system": "registration", "value": "MCI-12345" }]
  }
}

POST /identity/users/550e8400-e29b-41d4-a716-446655440000/onboarding
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "onboarding": {
    "current_step": 3,
    "total_steps": 3,
    "completed_steps": ["profile-basics", "professional-identity", "profile-import"],
    "user_type": "practitioner"
  }
}

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "onboarding_completed": true,
    "onboarding_completed_at": "2026-03-23T12:00:00Z"
  }
}

// Photo upload
catch {
  setPreviewUrl(user?.avatar_url || null)
  toast.error('Failed to upload photo')
}

// Step submission
catch {
  toast.error('Failed to save. Please try again.')
}

// Onboarding completion
catch {
  toast.error('Something went wrong. Please try again.')
}

{import.meta.env.DEV && (
  <Button
    onClick={() => {
      const store = useAuthStore.getState()
      if (store.user) {
        store.setState({
          user: { ...store.user, onboarding_completed: false }
        })
      }
    }}
  >
    Reset Onboarding
  </Button>
)}