# RateRight Voice Signup Flow Design

## Problem Statement
Construction workers face significant friction with traditional email/password signup:
- Gloves/dirty hands make typing difficult
- On-site conditions (sunlight, noise, safety concerns)
- Limited time during breaks (smoko)
- Email is often personal, not work-focused
- Complex forms are abandonment points

## Target User Persona
- **Dave the Chippy**: 34, carpenter, 12 years experience
- **Context**: 15-minute smoko break, phone in one hand, pie in the other
- **Goal**: Get on RateRight to find better paying jobs
- **Constraint**: Zero typing, 2-minute maximum signup

## Voice-First User Journey

### 1. Landing & Trigger (15 seconds)
**Screen**: Big "START VOICE SIGNUP" button
**Voice Prompt**: "Hey mate, ready to join RateRight? Just tap and talk."
**Action**: Single tap to activate voice signup

### 2. Phone Number Capture (30 seconds)
**Voice**: "What's your mobile number? Just say it naturally."
**User**: "Oh four two three, four five six, seven eight nine"
**System**: Repeats back: "So that's zero four two three, four five six, seven eight nine?"
**User**: "Yeah that's right"
**Validation**: Australian mobile format (04xx xxx xxx)

### 3. SMS Verification (45 seconds - background)
**System**: "Sweet, we're sending you a code right now."
**SMS**: "Your RateRight code is 8472. Welcome to better pay!"
**Voice**: "What's the 4-digit code we just texted you?"
**User**: "Eight four seven two"
**Fallback**: "Resend code" voice command available

### 4. Voice Profile Creation (45 seconds)
**Voice**: "Awesome! Now tell us about yourself. What do you do?"
**User**: "I'm a chippy, been doing carpentry for about 12 years now"

**System extracts**:
- Trade: Carpenter ✅
- Experience: 12 years ✅

**Voice**: "Where do you usually work?"
**User**: "Mostly around Sydney, inner west area"

**System extracts**:
- Location: Sydney, Inner West ✅

**Voice**: "What's your hourly rate?"
**User**: "I usually get about 65 an hour"

**System extracts**:
- Rate: $65/hour ✅

### 5. Name Capture (30 seconds)
**Voice**: "Last thing - what should we call you?"
**User**: "David, but everyone calls me Dave"
**System**: "Nice to meet you, Dave! Your profile is ready."

### 6. Completion (15 seconds)
**Voice**: "You're all set! Jobs matching your skills will start coming through."
**Screen**: "Welcome Dave! 🎉 Your first matches are loading..."

**Total Time**: 2 minutes 30 seconds maximum

## Technical Implementation

### Speech-to-Text Technology Choice

**Primary: Web Speech API (Browser Native)**
- ✅ Free, no API costs
- ✅ Works offline with downloaded languages
- ✅ Australian English optimized
- ✅ Real-time processing
- ❌ Browser dependent (Chrome/Safari best)
- ❌ Requires HTTPS

**Fallback: Whisper API (OpenAI)**
- ✅ 99% accuracy with Australian accents
- ✅ Handles background noise well
- ✅ Cloud-based, consistent
- ❌ $0.006/minute audio (~$0.01 per signup)
- ❌ Requires internet

**Implementation Strategy**:
1. Try Web Speech API first
2. If confidence < 80%, fallback to Whisper
3. Cache successful transcriptions locally

### Voice Processing Logic

```javascript
// Trade Detection
const tradeKeywords = {
  'carpenter': ['chippy', 'carpenter', 'carpentry', 'wood work'],
  'electrician': ['sparky', 'electrician', 'electrical', 'wiring'],
  'plumber': ['plumber', 'plumbing', 'pipes', 'drainage'],
  'bricklayer': ['brickie', 'bricklayer', 'bricklaying', 'masonry'],
  'concreter': ['concreter', 'concrete', 'slab', 'pour'],
  'steelfixer': ['steelfixer', 'reinforcement', 'reo', 'steel fixing'],
  'painter': ['painter', 'painting', 'paint', 'spray'],
  'plasterer': ['plasterer', 'plastering', 'gyprock', 'render']
};

// Experience Extraction
const experiencePatterns = [
  /(\d+)\s*years?/i,
  /(\d+)\s*yrs?/i,
  /about\s*(\d+)\s*years?/i,
  /(\d+)\s*plus\s*years?/i
];

// Location Processing
const locationPatterns = {
  'sydney': ['sydney', 'inner west', 'eastern suburbs', 'north shore'],
  'melbourne': ['melbourne', 'inner north', 'south east', 'bayside'],
  'brisbane': ['brisbane', 'north side', 'south side', 'bayside'],
  'perth': ['perth', 'northern suburbs', 'southern suburbs'],
  'adelaide': ['adelaide', 'hills', 'northern suburbs']
};

// Rate Extraction
const ratePatterns = [
  /\$(\d+)\s*(?:per|an?)\s*hour/i,
  /(\d+)\s*dollars?\s*(?:an?\s*hour|per\s*hour)/i,
  /about\s*\$(\d+)/i,
  /around\s*\$(\d+)/i
];
```

### Database Schema Changes

```sql
-- Users Table Updates
ALTER TABLE users ADD COLUMN:
- phone_number VARCHAR(20) UNIQUE NOT NULL
- phone_verified BOOLEAN DEFAULT FALSE
- signup_method ENUM('voice', 'traditional') DEFAULT 'voice'
- voice_data JSONB -- Store voice profile metadata
- created_at TIMESTAMP DEFAULT NOW()
- last_active TIMESTAMP

-- Voice Data Structure
{
  "voice_signup": {
    "completed_at": "2024-01-15T10:30:00Z",
    "confidence_scores": {
      "trade": 0.95,
      "experience": 0.89,
      "location": 0.92,
      "rate": 0.87
    },
    "raw_transcriptions": {
      "trade": "I'm a chippy, been doing carpentry for about 12 years now",
      "location": "Mostly around Sydney, inner west area",
      "rate": "I usually get about 65 an hour"
    },
    "fallback_used": false,
    "total_time_seconds": 145
  }
}

-- Trades Table (New)
CREATE TABLE trades (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  slug VARCHAR(50) UNIQUE NOT NULL,
  display_order INTEGER DEFAULT 0,
  active BOOLEAN DEFAULT TRUE
);

-- Locations Table (New)
CREATE TABLE locations (
  id SERIAL PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  state VARCHAR(50) NOT NULL,
  postcode_prefix VARCHAR(4),
  lat DECIMAL(10,8),
  lng DECIMAL(11,8)
);
```

### SMS Verification Flow

```javascript
// Using Twilio or similar
const smsFlow = {
  sendVerificationCode: async (phoneNumber) => {
    const code = Math.floor(1000 + Math.random() * 9000).toString();
    const message = `Your RateRight code is ${code}. Welcome to better pay!`;
    
    await twilio.messages.create({
      body: message,
      from: process.env.TWILIO_PHONE,
      to: phoneNumber
    });
    
    // Store code with expiry (5 minutes)
    await redis.setex(`verify:${phoneNumber}`, 300, code);
  },
  
  verifyCode: async (phoneNumber, userCode) => {
    const storedCode = await redis.get(`verify:${phoneNumber}`);
    return storedCode === userCode;
  }
};
```

## Fallback for Non-Voice Users

### Traditional Flow Option
**Button**: "Prefer to type? Click here"
- Standard form with email/password
- Trade dropdown selection
- Experience slider
- Location autocomplete
- Rate input field

### Accessibility Considerations
- Large touch targets (minimum 44px)
- High contrast mode
- Screen reader support
- Haptic feedback on actions
- Offline capability with sync

### Error Handling
- "Sorry, didn't catch that - could you repeat?"
- "Having trouble with voice? Try typing instead"
- Background noise detection
- Confidence threshold alerts
- Multiple retry attempts

## Implementation Estimate

### Phase 1: MVP (2-3 weeks)
- [ ] Web Speech API integration
- [ ] Basic voice processing logic
- [ ] Phone number validation
- [ ] SMS verification setup
- [ ] Simple profile extraction
- [ ] Fallback to traditional form

### Phase 2: Enhanced (2 weeks)
- [ ] Whisper API fallback
- [ ] Advanced NLP processing
- [ ] Confidence scoring
- [ ] Voice data storage
- [ ] Analytics integration
- [ ] A/B testing framework

### Phase 3: Polish (1 week)
- [ ] Noise cancellation
- [ ] Voice training/calibration
- [ ] Multi-language support
- [ ] Advanced error handling
- [ ] Performance optimization

**Total Timeline**: 5-6 weeks
**Development Team**: 2 developers, 1 designer
**Estimated Cost**: $15,000-20,000

## Success Metrics

### Primary KPIs
- Voice signup completion rate: Target 75%
- Time to complete: Target < 3 minutes
- Voice recognition accuracy: Target > 90%
- SMS verification success: Target > 95%

### Secondary Metrics
- Fallback rate to traditional form: < 20%
- User satisfaction score: > 4.5/5
- Profile completion quality: > 85%
- Conversion to active user: > 60%

## Risk Mitigation

### Technical Risks
- **Speech recognition accuracy**: Implement confidence scoring + fallback
- **Background noise**: Use noise cancellation + suggest quiet environment
- **Browser compatibility**: Progressive enhancement + feature detection
- **Network connectivity**: Offline-first approach with sync

### User Experience Risks
- **Privacy concerns**: Clear data usage explanation
- **Voice fatigue**: Keep interactions short and natural
- **Accent recognition**: Test with diverse user base
- **Accessibility**: Provide multiple input methods

## Future Enhancements

### Voice 2.0 Features
- Voice profile updates ("Hey RateRight, I now charge $70/hour")
- Voice job search ("Find me carpentry jobs in Parramatta")
- Voice portfolio updates ("Just finished a deck in Bondi")
- Multi-language voice support

### AI Integration
- Smart job matching based on voice tone/enthusiasm
- Automated rate suggestions based on experience
- Voice-based skill assessment
- Personality matching with employers

---

**Design Principle**: Every interaction should feel like talking to a mate at the pub - casual, helpful, and respectful of their time.