# RateRight Onboarding Pack — Builder's Technical Review v3

*Builder's response to Rivet's v2 spec. Technical feasibility, gaps, phasing, and pushbacks.*
*Date: 2026-02-15 | For Rivet to compile into final draft for Michael*

---

## Verdict: Spec is solid. A few corrections and one big simplification.

The hybrid approach (Option C) is correct. Client-side PDF, no sensitive data on our servers — clean architecture, minimal liability. Here's my technical read.

---

## Answers to Rivet's Open Questions

### 1. Does the current schema support these fields?

**Mostly yes.** Current `worker_profiles` has: trade, experience, suburb, availability, certifications, phone (via profiles table). 

**Missing fields that need migrations:**
- `profiles.address` — we have `suburb` but not full street address. Need to add or use suburb as-is.
- `worker_profiles.abn` — not currently on worker profiles. Workers don't have ABN in the schema. Needs a column.
- `worker_profiles.white_card_number` — not in schema. Need to add.
- `worker_profiles.white_card_expiry` — not in schema.
- Document references (white card scan, ticket uploads) — need a `worker_documents` table or use Supabase Storage with references in `worker_profiles.documents` JSONB column.

**Contractor side:**
- `companies.admin_email` — doesn't exist. Need to add.
- `companies.admin_contacts` — JSONB array for multiple contacts. Doesn't exist.

**Migration effort: ~30 minutes.** Straightforward column additions.

### 2. Client-side PDF generation — mobile concerns?

**jsPDF works on mobile browsers.** Tested approach:
- `jsPDF` for text layout + basic structure
- `html2canvas` if we want to render a styled HTML template to PDF (heavier but prettier)
- **Recommendation: `pdf-lib`** — lighter than jsPDF, better TypeScript support, can embed images (for white card scans). Works in all modern mobile browsers.

**Real concern:** File size with embedded document scans. A white card photo + 2 ticket images = 5-10MB PDF. Mobile Safari handles this fine. Chrome on Android occasionally chokes on large Blob URLs.

**Mitigation:** Compress images before embedding (canvas resize to 1200px width, JPEG 0.7 quality). Keeps PDF under 3MB.

### 3. Document storage?

**Supabase Storage is set up.** We have an `avatars` bucket. Need a `documents` bucket with:
- Per-user folder structure: `documents/{user_id}/white-card.jpg`
- RLS policy: users can only read/write their own folder
- Max 5MB per file (already standard)

**Setup effort: 10 minutes.** One SQL migration + bucket creation.

### 4. Email sending?

**We have Resend configured** (API key in .env.local). Can absolutely auto-send the PDF to contractor admin email.

**Flow:**
1. Worker generates PDF client-side
2. Worker taps "Send to [Contractor Name]"
3. Client uploads the PDF to a temporary endpoint (or we generate server-side for email sending only)
4. Server sends via Resend to contractor's admin email
5. Temporary file deleted immediately

**BUT WAIT — this contradicts the "never touches our server" promise.** If we email it, the PDF passes through our server momentarily.

**Options:**
- A) Worker manually shares (email, AirDrop, WhatsApp) — zero server touch, but more friction
- B) We relay the email — PDF passes through server momentarily, we delete immediately
- C) Hybrid — worker can share manually OR tap "Email to contractor" which uses server relay

**Recommendation: Option C.** Most workers will just WhatsApp it to their boss anyway. The email option is for the formal admin routing flow. Add a clear disclaimer: "Your sensitive details pass through our server only to send this email, then are immediately deleted."

### 5. Fastest path to working prototype?

**3-4 hours for MVP PDF generator:**
1. Add "Create Onboarding Pack" button to worker profile page
2. Form for ABN/TFN path selection + local-only fields (bank, TFN, super, emergency contact)
3. pdf-lib generates PDF client-side
4. Download button → saves to phone
5. Share button → native share API (works on mobile, lets them pick WhatsApp/email/etc.)

**Skip for MVP:** Email routing to admin, document embedding (white card/tickets), analytics.

---

## What I'd Push Back On

### 1. TFN Path Is Risky Scope Creep
Michael said collect both TFN and ABN. But TFN path adds significant fields (super fund, member number) and implies employment compliance we don't want anywhere near us. 

**My recommendation:** MVP = ABN path only. 90%+ of construction workers are on ABN. TFN path = Phase 2, after we validate the ABN flow works.

If Rocky disagrees, fine — it's still client-side only. But it's unnecessary complexity for launch.

### 2. "Seamless Flow Ideas" — Most Are Phase 3+

From Rivet's list:
- ✅ **One-Click Rehire** — Already partially built (matches table tracks history). Easy add.
- ✅ **ABN Auto-Lookup** — Already built! We verify ABN on contractor signup. Same API for workers.
- 🟡 **Smart Notifications** — SMS infrastructure needed. Not hard but not MVP.
- 🟡 **Availability Calendar** — Nice to have. Phase 2.
- ❌ **No-Show Auto-Backup** — Complex state machine. Phase 3.
- ❌ **Xero/MYOB Integration** — Massive scope. Phase 4 at earliest.
- ❌ **Digital Timesheets** — Location verification = GPS permissions = friction. Phase 4.

### 3. Admin Contact Routing Is Overkill for MVP
Contractors are small operators. The person hiring IS the admin. "Where should worker details be sent?" → their own email. We can add multi-contact routing later when we have 50+ contractors and actual demand for it.

**MVP:** One admin email field on company profile. Auto-populate with signup email. Done.

---

## Proposed Implementation Phases

### Phase 1 — MVP Onboarding Pack (This Week)
- Add missing schema fields (address, ABN on worker, white_card, admin_email)
- "Create Onboarding Pack" button on worker profile
- ABN path only
- Client-side PDF with pdf-lib
- Pre-fill from profile: name, phone, email, suburb, trade, experience, ABN
- Local fields: bank details, emergency contact
- Download + native share API
- Footer: "Powered by RateRight — rateright.com.au" with clickable link
- **Effort: 4-6 hours**

### Phase 2 — Document Attachments + Email (Next Week)
- Supabase Storage `documents` bucket
- White card + ticket upload UI on worker profile
- Embed uploaded documents as additional PDF pages
- Admin email field on contractor profile
- "Email to contractor" option (server relay via Resend)
- Profile completion indicator ("Add your white card to get hired faster")
- **Effort: 6-8 hours**

### Phase 3 — TFN Path + Polish (Week After)
- TFN work type selection
- Additional fields: TFN, super fund, member number
- Repeat hire detection ("You've worked for this contractor before")
- Pack generation analytics
- **Effort: 4-6 hours**

---

## One More Thing — Stripe Status

**We're on LIVE keys.** `sk_live_*` is in .env.local, `STRIPE_TEST_MODE=False`. Real payments can flow right now. This is fine for launch but Rocky needs to know — any test transactions will charge real money.

---

## Summary

The spec is good. Rivet's done solid work here. My only real pushback: start with ABN path only, skip TFN for MVP, and keep admin routing simple (one email field). Everything else is buildable this week.

Ready to start Phase 1 on Rocky's go.

— Builder