Skip to content
Ideony

ADR 0024: Clerk identifier-first unified auth flow

ADR 0024: Clerk identifier-first unified auth flow

Section titled “ADR 0024: Clerk identifier-first unified auth flow”
  • Status: Accepted
  • Date: 2026-04-19
  • Deciders: Ideony team

Context

Section titled “Context”

Separate sign-in / sign-up screens (“Do you have an account?” → pick path) are a cold first-impression anti-pattern — users don’t always know if they have an account, and the forked UX feels dated. Every SOTA consumer product (Stripe, Airbnb, Linear, Notion, Vercel, Uber, Revolut, Shopify, Wise, Apple) uses identifier-first unified auth: user enters email/phone, system auto-detects existing account, routes to password entry OR account creation on step 2.

Ideony’s welcome tour + auth overhaul (locked 2026-04-19) needed to align with this SOTA pattern while keeping Clerk as the auth provider (ADR-0005).

Decision

Section titled “Decision”

Use Clerk’s <SignIn /> with signUpForceRedirectUrl — Clerk handles the branching internally. Single route /(welcome)/continue replaces separate sign-in + sign-up screens. The step-2 divergence adds name + phone + role chip (“Cerco un pro / Sono un pro”) only for new-account flow.

Deep Clerk appearance theming (variables + targeted elements) applied so the embedded Clerk components match Italian Sole palette + Gambarino + Switzer typography (ADR-0010).

Consequences

Section titled “Consequences”
  • One entry point = warmer first impression (matches SOTA)
  • Lower user cognitive load — system decides if sign-in or sign-up
  • Role selection (consumer / pro) captured at step 2 of sign-up, not pre-auth
  • Clerk owns the branching logic — no custom state machine to maintain − Theming surface is larger (must style both sign-in + sign-up variants deeply) − Tied to Clerk’s component API — deep theming fragile across Clerk version bumps (mitigate via locked @clerk/clerk-expo version until tested)

Alternatives considered

Section titled “Alternatives considered”
  • Separate /sign-in + /sign-up routes — prior pattern; cold first-impression, dated UX
  • Custom unified form (no Clerk component) — full theming control but loses Clerk’s passwordless OAuth flows + rebuild maintenance burden
  • <SignUp /> as default, link to sign-in — biases toward new-account path; doesn’t handle ambiguous “do I have an account?” case
Section titled “Related”