Caregiver onboarding - application flow v8

The redesigned caregiver self-registration flow for Birth Rebel - a mobile-first, multi-step application that replaces the old Typeform + CSV import. This spec covers everything from the landing page to application submission. What happens after submission (password, profile completion, review, go-live) is handled by the existing caregiver onboarding added in pull request #26 ("PR26") and is only referenced here. Clickable prototype: caregiver-onboarding-v11.html (in this folder).

How to read this. Humans: the intro, §1 state machine, and §9 open questions give the shape. Engineers/Claude: all sections - especially §2 taxonomy, §3 validation, §4 error states, and §6 system notes.

Action - copy sign-off. "Leah" is the founder, who appears as a friendly guide throughout the flow. All of her speech-bubble copy in the prototype is placeholder and must be reviewed and edited by Leah before build.

Copy style. Use normal hyphens (-), not em or en dashes, throughout all product copy.

1 State machine & scope

This spec owns the application. After submit, the caregiver is handed to the existing onboarding (PR26) - they set a password by email, complete their profile, the team reviews, and they go live. The password-set email is sent immediately on submission (not after review), so the caregiver can finish their profile before the team reviews it.

This spec · logged outVisitor

/caregiver/register. No account yet.

This spec · account in backgroundCompleting application

Multi-step form. Draft autosaved.

This spec · handoffSubmitted

"Check your email to create your password."

PR26 · existing onboardingPassword & profile

Set password → agreements, training certificate, payout details.

PR26Under review

Team review within 72h.

PR26Live & matchable

Approved; visible to parents.

This spec - landing → application → submitted/handoff screen. Covered in PR26 - password, profile completion, review, go-live (referenced only).

Declined is a terminal branch off review - communication & reapply still open (Q8).

2 Items taxonomy

Every field the application collects, in order, and whether it gates submission. Must blocks submit · Nudge optional · Cond conditional.

Step	Field(s)	Class	Notes
Landing	Email	Must	Required + format-validated (gates "Get started"). Creates account + draft in background. Locked after creation - it's the login identity, shown read-only with no in-flow edit. Early uniqueness check (Q7).
Goals	What you're hoping for	Nudge	Select up to 2 (single interaction); curated list, no "Other".
About you	First name, Last name	Must	Required.
About you	Phone	Must	International (E.164). Pronouns removed.
About you	Address (line 1, city, country)	Must	Global address lookup + manual fallback. Line 2 / postcode / region optional. Framed as safeguarding, not proximity.
Your practice	Caregiver type (4: doula, lactation, sleep, hypnobirthing)	Must	≥1. Drives the conditional specialisms below.
	Years practising / Births supported	Must	Mutually-exclusive bands (incl. "less than a year").
	Hourly rate (1-hr virtual)	Must	Currency (ISO 4217) + banded amount. Match input + analytics (Q16).
	Services / care types · Bio (care style)	Must / Nudge	Bio is mandatory - shown to parents & used for matching. Services optional.
Your practice	Areas of specialisation	Nudge	Role-conditional - the per-type specialism lists (defined by the founder) for each caregiver type selected, plus a shared Family & identity group. Sits in "Your practice" (expertise).
Your matches	Availability (grid + school-holiday flag)	Nudge	Starting point only; granular settings added later.
Your matches	Languages	Must	≥1; type-ahead from a standard list; English pre-added.
Check & submit	GDPR consent	Must	Hard gate on submit; timestamp stored.
Collected later, in PR26 onboarding: password, agreements (service agreement + code of conduct), training certificate, payout details (Stripe). Certificates/documents are not part of the application.

3 Validation rules

All rules enforced client-side and server-side - the public submission endpoint must re-validate (client checks are bypassable).

Field	Rule
Email	Standard format; lowercased; uniqueness checked at first entry (Q7).
Phone	International, incl. country code; strip separators; store E.164. Use a library (e.g. libphonenumber).
Address	Global lookup; line 1, city, country required; postcode/ZIP optional (format varies by country) - never hard-block.
Names	Required; trimmed; sensible max length.
Bio (care style)	Required; minimum length to avoid empty/placeholder submissions.
Type / Years / Births / Languages	Type ≥1; Years & Births single band each; Languages ≥1.
Hourly rate	Currency from ISO 4217; amount as a defined band (Q16).
GDPR consent	Must be explicitly ticked; store timestamp.

Continue gating. Each step's primary action stays disabled until that step's required fields are valid, evaluated in real time (on input), not only on click. Inline errors still show if a user edits a field then leaves it invalid.

4 Error & edge states

Field validation - inline red border + message; Continue blocked (see §3 gating).
Email already registered - detected early; offer "log in & continue" + password reset, never a dead-end (Q7).
Drop-off mid-flow - saved draft; returning shows a welcome-back/resume at the last step. Cross-device via secure resume link (Q11).
Submit failure / offline - keep all input; show retry with reassurance the data is safe.
Address not found - always allow manual entry; never block on the lookup.
Declined - handled in review (PR26). Applicant comms + reapply window still open (Q8).

5 Responsive & layout (mobile + desktop)

Rule	Detail
Single column always	One column at every width - multi-column forms hurt completion. Desktop adds width & breathing room, not extra columns of fields.
Breakpoints	<768 mobile (full-width). ≥768 centred card, max 680px. ≥1100 max 760px.
"Phone frame"	A mobile artifact only; on desktop it renders as a centred card on the page - no device chrome.
Padding / type	Content padding scales 20 → 56 → 72px; H1 23 → 28px. Tap targets ≥44px on mobile.
Selection grids	2-up mobile → 3-up ≥768px (shortens long lists, e.g. the 12 doula specialisms).
Footer nav	Back + Continue at the foot of the card; may stick to bottom on mobile. Gating (§3) applies at all widths.
Landing	May use a wider/2-column hero on desktop; form steps stay single-column.

6 System notes & flags (engineering)

Retention & pre-population (must-have). Everything captured in the application must be retained and surfaced in the caregiver's profile, with fields pre-populated. When they reach the PR26 profile-completion step, they should see and edit what they already entered - never re-enter it. The application and the profile must read/write the same caregiver record.

Flags & conflicts to resolve before build

Schema coverage. New/changed fields - goals, hourly rate (currency+band), banded years/births, and the expanded role-conditional specialism taxonomy - likely exceed the existing caregivers columns (fixed specialism booleans; free-text years/births). Expect a migration and probably a specialisms join table.
Account / record linking. The application creates a draft record (no auth user yet); PR26's password-set creates the auth user. They must link cleanly and pre-populate the profile. Recent commits fixed caregivers.user_id linking - verify the new draft→user path is compatible.
Status model (Q6). States needed - draft, submitted, under-review, live, declined - can't be expressed by the existing active boolean. Needs an explicit status field.
Canonical /auth (Q5). CLAUDE.md §10.1 forbids a separate caregiver login page. Registration may live at a public route, but login must route through /auth.
Pricing dependency. Whether/how the rate informs matching and what parents see depends on the payment/margin model (docs/payment-flow-decisions.md, payment-flow-margin-config-spec.md) - don't finalise in isolation.

7 Analytics

PostHog - deferred to a later phase. The step-level funnel and event taxonomy (registration started / step viewed / step completed / abandoned / submitted) are to be added later, not in this build. PII discipline (no raw email/phone/address; EU host) and per-step routing will be defined then.

8 Out of scope

Password, profile completion, agreements, training certificate, payout details, review & go-live - existing onboarding (PR26); referenced, not specced here.
Approval workflow - needs design (follow-up). The admin/team side - reviewing submitted applications, approve/decline, and the under-review → live transitions - is not yet designed and does not exist in production today. Out of scope for this application flow, but a required piece of work before launch; should align with whatever PR26 introduces.
Parent-side matching UI and payment/margin config - separate workstreams.
PostHog analytics - deferred (§7).
Full accessibility audit - spec notes focus/keyboard/labels; full audit at build.

9 Open questions

Stable numbering across versions. Reply by number.

Reconcile registration route + caregiver login with canonical /auth.

CLAUDE.md §10.1 forbids a separate caregiver login page. Confirm before build.

Explicit status enum vs. overloaded active boolean?

Five+ states needed. Assumption: introduce a status field + migration.

Declined applicants - email them, and a reapply window?

Handled in review (PR26). Assumption: respectful decline email + defined window.

Q10

Global address lookup - which provider, pre-fill vs. validate-only?

Cost per lookup + data residency. Assumption: a global autocomplete (e.g. Google Places) + manual fallback.

Q11

Drop-off re-engagement - provider & cadence?

Per CLAUDE.md §10.3: Resend for the secure resume link, Klaviyo for the nudge cadence (e.g. +24h, +3d).

Q13 / Q14

Documents & insurance - handled in PR26 onboarding.

Now collected in the PR26 profile step (training certificate, agreements). Still to settle there: which documents are uploaded vs. viewed, and whether insurance expiry is captured (for renewal reminders / auto-pause).

Q16

Rate banding - scheme, and how across currencies?

£-bands don't map cleanly once global. Options: per-currency bands / raw+band-at-analysis / FX-normalise. ISO 4217 covers currency only.

Q18

Confirm specialisms dropped from the per-type lists.

"Bereavement / loss" & "complex health needs" aren't in the new role lists. Assumed intentional; confirm or find them a home.

Resolved / superseded: Q1 (goals = select up to 2) · Q2 (no parallel set-up - profile via PR26) · Q3 (guide-voice density - folded into Leah copy sign-off) · Q4 (review SLA = 72h) · Q7 (early email-taken recovery) · Q9 (certs out of application) · Q12 (PostHog deferred) · Q15/Q17 (rate captured; setup handed to PR26) · Q19 (password email sent immediately on submit - see §1).