Skip to content

docs: add new user onboarding handling plan - #4182

Open
gilgardosh wants to merge 2 commits into
mainfrom
claude/new-user-login-data-g7dtxp
Open

docs: add new user onboarding handling plan#4182
gilgardosh wants to merge 2 commits into
mainfrom
claude/new-user-login-data-g7dtxp

Conversation

@gilgardosh

@gilgardosh gilgardosh commented Aug 11, 2026

Copy link
Copy Markdown
Collaborator

Summary

Add comprehensive documentation outlining the problem, root causes, and phased solution for handling unauthenticated new users who sign up via Auth0 but lack a business_users row.

Changes

  • New file: docs/new-user-onboarding/plan.md — a detailed 7-section design document covering:
    • Current behaviour: traces the signup path, server JWT handling, and client-side broken state (error toasts, reauth loops, empty dashboard)
    • Root causes: API conflation of "not authenticated" vs "authenticated but not provisioned", missing client provisioning state, unreachable invitations, and enabled-but-broken public signup
    • Target UX: dedicated /welcome screen with branches for email verification, pending invitations, no workspace, or normal app access
    • Proposed changes: four phased implementation plan:
      • Phase 0 (ship first): new ONBOARDING_REQUIRED error code, un-guarded viewer query, client-side guard and /welcome route
      • Phase 1: claim pending invitations without email link via claimInvitation mutation
      • Phase 2: self-serve workspace creation (feature-flagged)
      • Phase 3: product decision on signup policy (enable self-serve or disable public signup)
    • Security notes: JWT verification, email verification gating, and data exposure constraints
    • Testing strategy: unit tests for directives, viewer resolver, claim invitation flow, and client-side guard/urql integration
    • Files touched: comprehensive list of server and client modules affected

Implementation Notes

This is a planning document only — no code changes. It serves as the specification for the upcoming implementation work across packages/server and packages/client. The phased approach allows Phase 0 (correctness fix) to ship independently before product decides on Phases 2 vs 3.

https://claude.ai/code/session_01344D5q1uyAHuwRJ3yyDX46

@gilgardosh
gilgardosh temporarily deployed to accounter-fullstack August 11, 2026 10:42 — with GitHub Actions Inactive
@gilgardosh
gilgardosh temporarily deployed to accounter-fullstack August 11, 2026 10:42 — with GitHub Actions Inactive
@github-actions

github-actions Bot commented Aug 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🚀 Snapshot Release (alpha)

The latest changes of this PR are available as alpha on npm (based on the declared changesets):

Package Version Info
@accounter/client 0.1.0-alpha-20260813085405-230edd38a6d55bd79966d89d7a73496f4f82ee75 npm ↗︎ unpkg ↗︎
@accounter/gmail-listener 0.1.3-alpha-20260813085405-230edd38a6d55bd79966d89d7a73496f4f82ee75 npm ↗︎ unpkg ↗︎
@accounter/green-invoice-graphql 0.8.7-alpha-20260813085405-230edd38a6d55bd79966d89d7a73496f4f82ee75 npm ↗︎ unpkg ↗︎
@accounter/hashavshevet-mesh 0.2.13-alpha-20260813085405-230edd38a6d55bd79966d89d7a73496f4f82ee75 npm ↗︎ unpkg ↗︎
@accounter/israeli-vat-scraper 0.1.13-alpha-20260813085405-230edd38a6d55bd79966d89d7a73496f4f82ee75 npm ↗︎ unpkg ↗︎
@accounter/modern-poalim-scraper 0.11.0-alpha-20260813085405-230edd38a6d55bd79966d89d7a73496f4f82ee75 npm ↗︎ unpkg ↗︎
@accounter/payper-mesh 0.2.13-alpha-20260813085405-230edd38a6d55bd79966d89d7a73496f4f82ee75 npm ↗︎ unpkg ↗︎
@accounter/scraper-app 0.0.3-alpha-20260813085405-230edd38a6d55bd79966d89d7a73496f4f82ee75 npm ↗︎ unpkg ↗︎
@accounter/server 0.2.0-alpha-20260813085405-230edd38a6d55bd79966d89d7a73496f4f82ee75 npm ↗︎ unpkg ↗︎
@accounter/shaam-uniform-format-generator 0.2.7-alpha-20260813085405-230edd38a6d55bd79966d89d7a73496f4f82ee75 npm ↗︎ unpkg ↗︎
@accounter/shaam6111-generator 0.1.9-alpha-20260813085405-230edd38a6d55bd79966d89d7a73496f4f82ee75 npm ↗︎ unpkg ↗︎

@gilgardosh
gilgardosh temporarily deployed to accounter-fullstack August 11, 2026 11:44 — with GitHub Actions Inactive
@gilgardosh
gilgardosh temporarily deployed to accounter-fullstack August 11, 2026 11:44 — with GitHub Actions Inactive
@gilgardosh gilgardosh mentioned this pull request Aug 11, 2026
Merged
@gilgardosh
gilgardosh temporarily deployed to accounter-fullstack August 11, 2026 15:34 — with GitHub Actions Inactive
@gilgardosh
gilgardosh temporarily deployed to accounter-fullstack August 11, 2026 15:34 — with GitHub Actions Inactive
@gilgardosh gilgardosh self-assigned this Aug 11, 2026
This was referenced Aug 11, 2026
Open
Merged
claude added 2 commits August 13, 2026 11:49
@claude @gilgardosh
docs: plan for handling authenticated users with no linked tenant
7ebccd6 
Traces the current broken path (valid Auth0 JWT + no business_users row ->
UNAUTHENTICATED -> refreshAuth loop, error toasts, empty dashboard) and
proposes a phased fix: a distinct ONBOARDING_REQUIRED error code, a viewer
query and /welcome screen, pending-invitation claiming by verified email,
and an optional flagged self-serve workspace creation.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01344D5q1uyAHuwRJ3yyDX46
@claude @gilgardosh
docs: make onboarding plan invitation-only, drop self-serve signup
87648cd 
Replaces the flagged self-serve workspace phase with closing public signup
on the Auth0 database connection, and notes why phases 0-1 are still needed
under invitation-only (pre-existing accounts, expired/revoked invitations,
non-database connections, users removed from their last business).

Also applies prettier formatting so the doc passes the CI check.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01344D5q1uyAHuwRJ3yyDX46
@gilgardosh
gilgardosh force-pushed the claude/new-user-login-data-g7dtxp branch from 7d7402c to 87648cd Compare August 13, 2026 08:52
@gilgardosh
gilgardosh temporarily deployed to accounter-fullstack August 13, 2026 08:52 — with GitHub Actions Inactive
@gilgardosh
gilgardosh temporarily deployed to accounter-fullstack August 13, 2026 08:52 — with GitHub Actions Inactive
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@gilgardosh gilgardosh

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@gilgardosh @claude