# RateRight SMS Signup Specification

## Overview
SMS-first signup designed for construction workers who:
- Don't regularly use email
- Have basic/feature phones
- Need quick, simple registration
- Work on sites with poor WiFi

**Goal**: Sign up in under 60 seconds with just a phone number.

## User Flow

### 1. Phone Number Entry (5 seconds)
- Simple screen: "Enter your phone number"
- Auto-detect country code (Australia default: +61)
- Format as they type: 04xx xxx xxx
- Big, thumb-friendly number pad

### 2. SMS Code Verification (30-45 seconds)
- Send 6-digit code instantly
- Auto-detect SMS and fill code (on smartphones)
- Manual entry fallback for basic phones
- Progress indicator: "Sending code..." → "Code sent!"

### 3. Welcome Screen (5 seconds)
- "You're in!" confirmation
- Brief explanation of what's next
- Option to add name/trade later

### 4. Progressive Profile (Optional, anytime after)
- Collect name when they post first review
- Ask for trade when they browse jobs
- Request location when searching local work

## Technical Approach

### SMS Provider: Twilio Verify
- **Cost**: $0.05 per verification + $0.0083 per SMS (AU)
- **Benefits**: Managed OTP, fraud protection, compliance
- **Features**: Rate limiting, auto-retry, voice fallback

### Alternative Providers
- **Vonage**: Similar pricing, good international support
- **MessageBird**: Strong in APAC region
- **AWS SNS**: Lowest cost but more complex setup

### Implementation Stack
```
Frontend: React Native (iOS/Android) + mobile web
Backend: Node.js/Express API
Database: PostgreSQL (store phone, basic profile)
SMS: Twilio Verify API
Security: Rate limiting, OTP hashing, HTTPS only
```

## Security Measures

### Rate Limiting
- Max 3 attempts per phone number per 15 minutes
- Max 5 SMS sends per number per hour
- Max 10 verifications per IP per day

### SIM Swap Protection
- Check phone number age/carrier (via Twilio Lookup)
- Flag recent SIM changes (within 7 days)
- Require additional verification for suspicious numbers

### Code Security
- 6-digit numeric codes (1 million combinations)
- 5-minute expiry time
- One-time use only
- Hashed storage in database

### Fallback Options
- Voice call with spoken code (for SMS delivery issues)
- Email backup (optional, for users who prefer it)
- Support contact for failed verifications

## Progressive Profile Building

### Immediate (Optional)
- Name: "What should we call you?"
- Trade: "What's your trade?" (dropdown: Carpenter, Electrician, etc.)

### After First Interaction
- Location: Ask when searching jobs/reviews
- Experience: "How many years in the trade?"
- Specializations: Multi-select after profile creation

### Ongoing
- Reviews written → Build reputation score
- Jobs viewed → Suggest relevant trades
- Location searches → Recommend local work

### Benefits
- Reduces signup friction by 70%
- Increases completion rates
- Gathers data when contextually relevant
- Respects user privacy

## Email Fallback Strategy

### When to Offer Email
- After 2 failed SMS attempts
- User explicitly chooses "Use email instead"
- International users (high SMS costs)

### Email Flow
- Collect email → Send verification link
- Keep phone number optional
- Allow adding phone later for notifications

## Implementation Plan

### Phase 1: MVP (2 weeks)
- [ ] Twilio Verify integration
- [ ] Basic phone → SMS → welcome flow
- [ ] Rate limiting and security
- [ ] Mobile-responsive design

### Phase 2: Polish (1 week)
- [ ] Auto-detect SMS codes
- [ ] Voice call fallback
- [ ] Better error handling
- [ ] Analytics tracking

### Phase 3: Progressive (1 week)
- [ ] Name/trade collection prompts
- [ ] Profile completion incentives
- [ ] A/B test timing of profile asks

### Phase 4: Scale (ongoing)
- [ ] International SMS support
- [ ] Additional providers for redundancy
- [ ] Advanced fraud detection
- [ ] Support for WhatsApp/Signal verification

## Success Metrics

### Primary
- Signup completion rate: Target >85%
- Time to complete: Target <60 seconds
- SMS delivery rate: Target >95%

### Secondary
- Profile completion rate (7 days): Target >60%
- User retention (30 days): Target >40%
- Support tickets: Target <2% of signups

## Cost Estimates (Per User)
- SMS verification: $0.0583 AUD
- Monthly SMS notifications: $0.0083 AUD each
- Support/fraud costs: $0.02 AUD estimated
- **Total first month**: ~$0.10 AUD per active user

## Risk Mitigation

### SMS Delivery Issues
- Multiple provider fallback
- Voice call option
- WhatsApp verification (future)

### Fraud Prevention
- Rate limiting at multiple levels
- Device fingerprinting
- Carrier/number validation
- Manual review for suspicious patterns

### User Experience
- Clear error messages
- Retry options
- Support contact visibility
- Progress indicators

## Future Enhancements
- WhatsApp Business API integration
- Push notifications (after app install)
- One-tap signup with carrier authentication
- Biometric verification (face/fingerprint)