Feel Pro Club Docs

Appearance

0001. Authentication, Entry, and Session Routing ​

Status: Approved Author: Codex Created: 2026-03-09

Overview ​

This PRD defines how users enter Feel Pro Club, move through the introductory story, authenticate mid-onboarding, and get routed into the correct post-login journey. It covers default onboarding entry, invite-driven team joining, session restoration, and the stable top-level route model.

Problem Statement ​

Feel Pro Club has multiple first-session outcomes: a user may be creating a team as an organizer, joining a team from an invitation as a main or substitute player, joining as a known player, or continuing independently as a free player. The entry system must introduce the product without slowing users down, authenticate them before profile setup, preserve invite context across web and mobile surfaces, and land users in the correct post-onboarding destination without asking them to manually declare a role up front.

Goals ​

  • Let every new session begin with onboarding rather than a role selector or branching gate.
  • Let new users understand the product promise before authentication without forcing them through the full intro.
  • Authenticate users inside onboarding, not as a disconnected precondition.
  • Preserve invitation context from invite tap through installation, authentication, and profile completion.
  • Route authenticated users into the correct next step based on invitation status, memberships, and wizard completion state.

Success Metrics ​

  • High completion rate from first open to successful authentication.
  • Low drop-off between welcome/authentication and first profile action.
  • High percentage of invited users who complete onboarding and land in the invited team without manual recovery.
  • High percentage of returning members who land in the expected post-auth destination without manual recovery.

Scope ​

In Scope ​

  • Four-screen introductory carousel and its skip/back behavior.
  • Mid-onboarding authentication checkpoint with Google and Apple entry points.
  • Splash/loading transition before the first functional screen.
  • Invite-link handling across web landing and mobile app handoff.
  • Invite-token validation and preservation during authentication and onboarding.
  • Stable route mapping for top-level sections and wizard parents.

Out of Scope ​

  • Password, magic-link, phone, or email-code authentication.
  • Backend provider session/token handling, account recovery, or provider-specific failure UX.
  • Deep implementation details for mobile install prompts, app-store redirection, or universal-link infrastructure.

Personas and Roles ​

  • New user: Has never used Feel Pro Club and needs onboarding plus authentication before profile setup.
  • Organizer: Creates a team after completing profile onboarding and becomes the initial team owner/operator.
  • Invited player: Receives an invitation to join a specific team as a main player or substitute player and should land in the team experience after profile completion.
  • Free player: Completes onboarding without an invitation and enters the independent player journey.
  • Known player: Receives an invitation into a lighter-weight team relationship and, after completing onboarding, lands in the team experience rather than in organizer flows.

User Journey ​

  1. Every new session starts in pre-onboarding, where the user can consume the four intro cards or skip ahead.
  2. The user authenticates with Google or Apple from the welcome screen embedded in onboarding.
  3. The system captures basic identity information and routes the user into profile completion.
  4. If the user entered through a valid team invitation, the invitation context remains attached throughout onboarding and authentication.
  5. After profile completion, the system routes the user according to context.
  6. An organizer candidate continues into team creation.
  7. An invited main player, substitute player, or known player is added to the target team and lands in home.
  8. A free player continues into the independent player path and lands in home once onboarding is complete.

Functional Requirements ​

Entry and Session Bootstrap ​

  1. All users shall start from onboarding entry rather than from a role selector or intent picker shown before onboarding.
  2. The session bootstrap layer shall support at least these outcomes: organizer team creation, invited team member join, known player join, and free player onboarding.
  3. When entry context is still being prepared, the app shall show a branded splash/loading state before continuing.
  4. When a user has valid team invitation context, the routing layer shall preserve that context through onboarding instead of discarding it.
  5. When a user logs out, the next session shall start from the intro flow again.
  1. The intro flow shall contain four story cards that explain the main product value propositions: organizing games, managing confirmations, finding teams, and reducing cancellations.
  2. Users shall be able to move forward one step at a time, move backward from steps two to four, or skip the intro entirely.
  3. Users who log out and return shall see the intro again before reaching authentication.
  4. Users shall be able to revisit the intro later from the welcome/authentication screen.
  5. The intro shall be informational only; it shall not collect persistent user data.

Authentication Checkpoint ​

  1. Authentication shall happen after the intro and before player profile onboarding.
  2. The visible MVP authentication options are Google and Apple sign-in.
  3. Successful authentication shall populate a display name and email for the current session before the player profile wizard starts.
  4. Authentication shall hand the user directly into the profile setup flow rather than dropping them on a generic home screen first.
  5. Authentication shall not require the user to declare whether they are an organizer, invited player, known player, or free player before profile setup begins.
  6. On successful account creation, a welcome email shall be sent to the user's registered email address.

Invitation Entry and Cross-Platform Handoff ​

  1. Organizer-issued invitations shall be represented by a unique token associated with a specific team invitation and valid for 24 hours.
  2. When a user taps an invite link, they shall first land on a web surface that explains the invitation and its target team context.
  3. The invite landing experience shall allow the user to choose to install or open the mobile app.
  4. When the user moves from the web invite landing into the mobile app, the same invitation token and team context shall remain available without requiring the user to reopen the original link.
  5. Invited users shall still pass through pre-onboarding, authentication, and profile completion; however, they shall bypass normal post-profile branching and join the invited team automatically once onboarding is complete.
  6. When an already-authenticated user with a completed profile taps a valid invite link, they shall skip onboarding and be added to the invited team directly. The user shall land in the invited team's workspace.
  7. If an organizer-intent user who deferred team creation taps an invite link, they shall join the invited team (skipping onboarding if already completed). The user can create their own team later from the app. Organizer intent is not lost.
  8. If the invitation token is expired, invalid, or already consumed, the system shall block automatic join behavior and present a recoverable fallback path instead of silently dropping the user into an unrelated journey.

Routing and URL Model ​

  1. Top-level product areas shall have stable, shareable routes.
  2. Wizard flows shall share a parent route rather than changing the URL on every step.
  3. Direct links to player detail screens in the market shall resolve into the corresponding detail state when enough local data exists.
  4. Browser back/forward behavior shall synchronize with in-app screen state instead of resetting the session.
  5. Invite URLs shall resolve into an invite-aware entry route that can preserve the invitation token across web and app boundaries.

Business Rules and Permissions ​

  • Entry routing depends on invitation context, completed onboarding state, and any existing team-specific membership state.
  • Organizers become team creators only after completing profile onboarding; they are not selected through a pre-auth role choice.
  • Invited main players, substitute players, and known players shall join the target team automatically after completing the required onboarding steps.
  • Free players shall follow the independent onboarding branch after profile completion.
  • Known players shall not be treated as organizers for the purposes of team creation or administration.
  • When a user authenticates with a second provider (Google or Apple) that shares the same email as an existing account, the accounts shall be merged automatically. The user retains all existing teams, profiles, and data.

UX Considerations ​

  • The intro should feel skippable, not mandatory.
  • Authentication should read as a combined sign-up and log-in checkpoint rather than separate auth funnels.
  • Invite landing should make the team context obvious before asking the user to install or open the app.
  • Invited users should feel continuity between the web invite surface and the mobile onboarding flow, with no need to re-enter team information manually.
  • The splash state should be short and purely transitional; it should not become a second onboarding surface.

Error States ​

  • Session bootstrap, invite validation, and provider callbacks shall use explicit loading and timeout states. If one of those steps times out, the user shall see retry rather than an indefinitely blocked splash screen.
  • If third-party authentication succeeds but FPC user sync or provider-account merge fails, the app shall keep the authenticated session, explain that account setup is incomplete, and offer retry instead of dropping the user into a generic route with no recoverable context.
  • Invite-token network failures shall be presented as temporary validation errors, not as expired or invalid-link states. Terminal invalid-link messaging may be shown only after a completed validation response confirms that condition.
  • If web-to-app handoff loses the invite token, the app shall show an invite-recovery state with a path back to the invite landing experience instead of silently continuing as an unrelated generic session.
  • Concurrent sign-in on another device shall not silently clear the current device's in-progress invite or onboarding route state. If re-authentication becomes necessary, the user shall see an explanatory message before being returned to welcome.

Linear Issues ​

IDTitle
FPC-5Authentication, Entry, and Session Routing (Epic)
FPC-6Shared types and constants for auth, users, and invitations
FPC-7API — User sync and profile endpoints
FPC-8API — Invitation validate and accept endpoints
FPC-9App — Routing architecture and session bootstrap
FPC-10App — Intro carousel (4 slides)
FPC-11App — Welcome/auth screen (Google + Apple)
FPC-12App — Invite landing page and token persistence
FPC-13App — Splash screen and loading state