ATLAS
Contractor Onboarding Flow

14-screen onboarding journey — intro, hub, profile, services, portfolio, documents, AI call, voice onboarding, schedule call, billing & complete

1 Intro Slides
2 Onboarding Hub
3 5-Step Hub
4 Profile Setup
5 Services
6 Portfolio
7 Documents
8 AI Call
9 Voice Onboarding
10 Schedule Call
11 Billing
12 Complete
1 Welcome & Hub
2 Profile & Services
3 Docs & AI Call
4 Portfolio & Scheduling
5 Billing & Complete
1 Onboarding Workspace
2 Voice & AI Call
3 Plan Selection & Launch
Section 1: Welcome & Intro
Intro Slides (Slide 2 of 3)
9:41
3bids
All-In-One
Get Paid
AI Tools

Get Paid, Guaranteed

Stop chasing payments. Start growing.

Homeowners find you in our marketplace
All jobs fully funded upfront
Low fees — as low as 3.5% on your leads
Verified homeowners with real projects
Next

Skip

IntroSlidesScreen -- Horizontal ScrollView paging. 3 slides: All-In-One, Get Paid, AI Tools. Tab indicator at top. useState(currentSlide)
Onboarding Hub
9:41
3bids

Almost there

Complete these steps to start bidding on jobs.

Profile & Office

Business name, phone, and office address

Portfolio

Showcase your best work

Documents

Service agreement and licenses

Onboarding Call

Schedule your verification call

Billing & Subscription

Pro Plan, Stripe Connect, payment

Continue

Complete your profile to continue

ContractorOnboardingHub -- StepCard list with progress dots. useQuery(api.contractor.onboarding.getProgress). Steps: profile, portfolio, documents, call, billing.
5-Step Hub (In Progress)
9:41
3bids

Almost there

Complete these steps to start bidding on jobs.

Profile & Office

Business name, phone, and office address

Portfolio

Showcase your best work

Documents

Service agreement and licenses

Onboarding Call

Schedule your verification call

Billing & Subscription

Subscription, Stripe Connect, payment

Continue
ContractorOnboardingSteps -- 5-step StepCard list: profile, portfolio, documents, call, billing. useQuery(api.users.contractors.me) + useQuery(api.contractor.portfolio.list). ProgressDots variant="contractor". allComplete triggers success TipCard + "Go to Dashboard" CTA.
Section 2: Business Profile
Profile Setup
9:41

Profile Setup

Tell us about yourself and your business

Generate AI Avatar

Personal Information
Optional
Business Information
If applicable to your trade
Office Location
Main Office
1234 Main St, Akron, OH 44301
25 mile service radius
Save & Continue
ContractorOnboardingProfile -- Combined personal + business. OfficeLocationManager for offices with radius. useMutation(api.contractor.profile.update). AvatarGeneratorModalV2 for AI avatar.
Services Selection
9:41

Select Your Services

Choose the services you offer. You can update these anytime.

3 services selected

Popular Services
Plumbing
Repairs, installations, water heaters
Popular
Electrical
Outlets, lighting, panels
Popular
HVAC
AC, heating, duct cleaning
Popular
Handyman
General repairs, drywall
Popular
More Services
Roofing
Repairs, replacement
Painting
Interior, exterior
Continue

You can add more services later from your profile

ContractorOnboardingServices -- Multi-select grid with Popular/More sections. useMutation(api.contractor.auth.completeOnboarding). SERVICE_CATEGORIES array with icons + descriptions. ServiceCard toggles.
Portfolio
9:41

Build Your Portfolio

Show homeowners your best work

No Projects Yet

Organize your work into projects. Each project can have multiple photos showing your craftsmanship.

Why add projects?
Showcase Your Best Work
Contractors with portfolios get 3x more bids accepted
Attract Quality Clients
Homeowners want to see your previous work
Stand Out from Competition
Before & after photos show transformations
Show Your Transformation
The most powerful way to win jobs
Before
After
+47% more job requests with before/after photos
Add Your First Project

Skip for now

ContractorOnboardingPortfolio -- 3-step state machine: welcome, add-project, portfolio. BeforeAfterSlots + MediaUpload for photos. useMutation(api.contractor.portfolio.add). Category select, before/after feature card.
Section 2B: Documents & AI Onboarding
Documents (Redirect)
9:41

Loading Documents...

Redirecting to your branded documents page for service agreements and licenses.

ContractorOnboardingDocuments -- Redirect shell. Immediately routes to /(contractor)/(tabs)/(home)/documents via useEffect. Loading spinner while redirect fires. Single documents component reused across flows.
AI Call (Step 4)
9:41
Step 4: AI Call

Talk to our AI assistant

Optional but powerful. A quick call lets our AI capture what documents can't -- how you really run your business.

5-minute call · No human on the other end · 100% private
Fill the gaps
AI found questions about your pricing or team structure? Answer them in a quick 5-minute call.
Capture tribal knowledge
Things your team "just knows" -- service areas, customer handling rules, scheduling quirks.
Owner stays in control
You set the commissions, you approve the roles. Your team uploads docs but can't change what they earn.
What the AI will ask about
Services you offer and how you price them
Your team structure and who does what
Commission rules and pay structure
Service area boundaries and scheduling
Business jargon your team uses
Start AI Call

Skip for now -- I'll do this later

AiCallScreen -- Post-doc-extraction clarification call. Hero + AI badge + 3 benefit cards + topics checklist. useQuery(api.intake.voiceCall.getCallEligibility). Calls startIntakeCall then navigates to voice screen. Skip option marks step complete with skipped flag.
Voice Onboarding (Intro)
9:41
AI-Powered

Voice Onboarding

Complete your contractor profile by having a conversation with our AI assistant. Just talk naturally about your business.

Takes 5-10 minutes
Natural conversation
Review before applying
Get Started

Prefer a scheduled call instead?

VoiceOnboardingScreen (screenState="intro") -- Deepgram + Gemini AI voice flow. HeroIcon mic + AI-Powered badge. 3 feature rows with success-light circles. CTA "Get Started" advances to mode_select. Link to schedule call as fallback.
Voice: Mode Select
9:41

Choose Your Experience

How would you like to complete your onboarding?

Quick Setup
~5 minutes

Fast form-filling style conversation. We'll collect the essential info to get you started.

Basic business info
Services & service area
Team & pricing basics
Recommended
Discovery Conversation
10-30 minutes

A real conversation where we learn about your business, past software experiences, and what success looks like.

Deep understanding of your business model
Learn from your past software experiences
Customized setup based on your needs
AI answers your questions about 3Bids
Start Quick Setup
VoiceOnboardingScreen (screenState="mode_select") -- Two mode cards: Quick (~5 min) and Discovery (10-30 min, recommended). Selected mode highlighted with terracotta border. useMutation(api.onboarding.voiceOnboardingIndex.startSession). Discovery mode tagged "Recommended".
Voice: Conversation
9:41
Voice Onboarding
Business Info · 2 of 6 topics
Hi! I'm here to help you set up your contractor profile quickly. Let's start with the basics -- what's the name of your company?
Carter Plumbing LLC. We've been around for about 12 years now.
Great, Carter Plumbing LLC -- 12 years is solid experience! What services do you primarily offer?
Mainly plumbing and HVAC. We also do some handyman work on the side.

Tap to speak

VoiceOnboardingScreen (screenState="conversation") -- TopicProgress bar shows current topic + completion. ConversationBubble for AI/user messages. MicButton states: idle/listening/processing. Deepgram STT + Gemini for conversation AI. Topics: business_name, services, team, pricing, service_area, jargon.
Section 3: Verification & Launch
Schedule Call (Concierge)
9:41
WHITE-GLOVE SERVICE

We'll Call You

No scheduling hassle. Tell us when works best and our team will reach out for a quick 15-minute verification call.

Your Phone Number
(330) 555-0147
Best Day to Call
Mon
Mar 2
Tue
Mar 3
Wed
Mar 4
Thu
Mar 5
Fri
Mar 6
Best Time
Morning
9am -- 12pm
Afternoon
12pm -- 5pm
Request My Call

I'll schedule myself later

ContractorOnboardingCall -- Concierge flow: WE call THEM. HeroIcon + badge. Day/time selectors. useMutation(api.contractor.scheduling.scheduleOnboardingCall). Success state with animated pulse rings.
Billing (Pro Plans Tab)
9:41

Billing & Subscription

Set up payments and choose your plan

In-Home
Invitations
Pro
Plans
Contract
Payouts
CURRENT PLAN
Basic
Pro Plus
Enterprise
$833 /mo
Billed annually (2 months free!)
Monthly
Annual
Unlimited
Leads
3.5-5%
Take Rate
Enhanced
Profile
Upgrade to Pro Plus
Pro Plus Features
Unlimited bids
Enhanced profile
Priority support
Lower fees (3.5% your leads / 5% 3bids)
Before/After stories
Recurring services
Annual Savings: Buy 10 months, get 2 months FREE!

Finish Later

ContractorOnboardingBilling -- 3-tab flow: In-Home Invitations, Pro Plans, Contract Payouts. TabNavigation + SimpleProgressDots. Plan tiers: Basic ($1/mo, 10%), Pro Plus ($999/$833, 3.5-5%), Enterprise ($1,999/$1,666, 3.5-5%). Stripe checkout session.
Onboarding Complete
9:41
3bids

You're all set!

Your contractor profile is ready. Welcome aboard.

Profile & Office

Business name, phone, and office address

Portfolio

Showcase your best work

Documents

Service agreement and licenses

Onboarding Call

Schedule your verification call

Billing & Subscription

Pro Plan, Stripe Connect, payment

Go to Dashboard
Start bidding on jobs
Onboarding complete!

You have a call scheduled for verification. Contractors are approved manually during the call.

ContractorOnboardingHub (allComplete state) -- All StepCards show H (success). Dashboard CTA card. TipCard variant="success" for completion message. useQuery(api.contractor.onboarding.getProgress).isComplete. Router: router.replace('/(contractor)/(tabs)').
Welcome & Hub
Welcome & Hub
9:41
Welcome & Hub
Content
Intro slides with value props, bullet points, and slide indicator
Items
Item Alpha
Updated 2h ago
Active
Item Beta
Updated 5h ago
Pending
Item Gamma
Updated 1d ago
Review
Profile & Services
Profile & Services
9:41
Profile & Services
Details
Title
Sample entry
Description
Enter description...
Content
Services selection grid with popular badges, count indicator
Documents & AI Call
Documents & AI Call
9:41
Documents & AI Call
Documents
Upload service agreements, licenses, and insurance documents for verification.
Drag & drop or tap to upload
Insurance Certificate
Business License
Pending
AI Call
Talk to our AI to fill gaps in your profile that documents can't capture.
5 min · AI-Powered · Private
Start AI Call
What the AI will ask
Pricing & services
Team structure
Service area boundaries
Portfolio & Scheduling
Portfolio & Scheduling
9:41
Portfolio & Scheduling
Details
Title
Sample entry
Description
Enter description...
Preview
Project Preview
Detailed view with all project information, photos, and metadata.
Media
Drag & drop or tap to upload
Details
Title
Sample entry
Description
Enter description...
Tools
Share your profile or scan to preview
Billing & Complete
Billing & Complete
9:41
Billing & Complete
Items
Item Alpha
Updated 2h ago
Active
Item Beta
Updated 5h ago
Pending
Item Gamma
Updated 1d ago
Review
Configuration
Option A
Option B
Option C
Overview
247
Total
+18%
Growth
Onboarding Workspace
Onboarding Workspace
https://app.3bids.io/contractor/onboarding
3Bids
Main
Welcome ⌘1
Profile ⌘2
Services ⌘3
Portfolio ⌘4
Call ⌘5
Billing ⌘6
Complete ⌘7
JC
James Carter
Contractor
Settings ⌘,

Onboarding Workspace

1,247
Total
+23%
Growth
89%
Rate
$42K
Revenue
Recent Activity
Item updated
2 minutes ago
Task completed
15 minutes ago
New notification
1 hour ago
Performance
Voice & AI Call
Voice & AI Call
https://app.3bids.io/contractor/onboarding/ai-call
3Bids
Main
Welcome ⌘1
Profile ⌘2
Services ⌘3
Portfolio ⌘4
Documents ⌘5
AI Call ⌘6
Voice ⌘7
Schedule ⌘8
Billing ⌘9
JC
James Carter
Contractor

AI Call & Voice Onboarding

AI Call
Optional · 5 min
Talk to our AI assistant
Capture tribal knowledge, fill gaps, and clarify pricing that docs can't explain.
Fill the gaps
Capture tribal knowledge
Owner stays in control
Start AI Call
Voice Onboarding
AI-Powered
Quick Setup
~5 min
Fast conversation for essential business info, services, and team basics.
Recommended
Discovery Conversation
10-30 min
Deep dive into your business model, software experiences, and customized setup.
Start Quick Setup
Plan Selection & Launch
Plan Selection & Launch
https://app.3bids.io/contractor/onboarding
3Bids
Main
Welcome ⌘1
Profile ⌘2
Services ⌘3
Portfolio ⌘4
Call ⌘5
Billing ⌘6
Complete ⌘7
JC
James Carter
Contractor
Settings ⌘,

Plan Selection & Launch

1,247
Total
+23%
Growth
89%
Rate
$42K
Revenue
Recent Activity
Item updated
2 minutes ago
Task completed
15 minutes ago
New notification
1 hour ago
Performance

Data Architecture

Schema Tables

  • contractorUsers -- auth, subscription, stripeConnectId, onboardingCallScheduled
  • contractorProfile -- name, phone, businessName, licenseNumber, bio, servicesOffered, serviceRadius, city, state, zipCode, avatarUrl, yearsExperience
  • contractorPortfolio -- title, description, category, photos[], beforePhotos[], afterPhotos[]
  • contractorDocuments -- type, fileUrl, status (pending/verified/rejected)

Mutations & Queries

  • api.contractor.auth.completeOnboarding
  • api.contractor.profile.update
  • api.contractor.portfolio.add / .update / .remove
  • api.contractor.portfolio.list
  • api.contractor.onboarding.getProgress
  • api.contractor.scheduling.scheduleOnboardingCall
  • api.contractor.documents.list
  • api.features.subscriptions.getCurrentSubscription
  • api.intake.voiceCall.getCallEligibility
  • api.intake.voiceCall.startIntakeCall
  • api.intake.voiceCall.skipIntakeCall
  • api.onboarding.voiceOnboardingIndex.startSession
  • api.onboarding.voiceOnboardingIndex.getActiveSession
  • api.onboarding.voiceOnboardingIndex.getRecommendations
  • api.onboarding.voiceOnboardingIndex.applyRecommendation
  • api.contractor.onboardingWizard.markPrimaryStepComplete

Key Components

  • StepCard -- variant="contractor" with terracotta accent
  • OfficeLocationManager -- multi-office with service radius
  • AvatarGeneratorModalV2 -- AI avatar (GPT Image 1.5)
  • BeforeAfterSlots + BeforeAfterSlider
  • MediaUpload -- variant="grid", max 10 photos
  • HeroIcon -- variant="terracotta"
  • FormFooter -- variant="contractor"
  • SimpleProgressDots -- variant="contractor"
  • ConversationBubble -- AI/user chat messages
  • MicButton -- states: idle/listening/processing
  • TopicProgress -- topic completion bar
  • RecommendationCard -- apply/reject AI suggestions

Integrations

  • Clerk -- Authentication, user session
  • Stripe Connect -- Payout bank account onboarding
  • Stripe Checkout -- Pro plan subscription billing
  • Stripe Payment Methods -- Card on file for lead purchases
  • SendGrid -- Welcome email, call confirmation
  • OpenAI GPT Image 1.5 -- AI avatar generation
  • Deepgram -- Speech-to-text for voice onboarding
  • Gemini -- Conversational AI for voice onboarding

Status Flow

pending → active → completed

Key Design Decisions

Design Pattern
TODO: Add design decision