Skip to content

Mobile Signin Flow

Plan Metadata

  • Plan type: plan
  • Parent plan: N/A
  • Depends on:
  • auth-system.md
  • Status: documentation

System Intent

  • What is being built: Contract for mobile sign-in flow execution from start-signin through complete-signin.
  • Primary consumer(s): Login/verify screens, auth provider methods, and auth request wrappers.
  • Boundary (black-box scope only): requestPasswordlessSignIn and completePasswordlessSignInWithCode behavior, including integration expectations against the auth-system contract.
  • Ownership constraint: backend endpoint status/code semantics are owned by auth-system.md; this plan owns only caller behavior and local state transitions.

Stage Gate Tracker

  • [x] Stage 1 Mermaid approved
  • [x] Stage 2 I/O contracts approved
  • [x] Stage 3 pseudocode/technical details approved or skipped

1. Mermaid Diagram

Reference: .agent/skills/create-mermaid-diagram/SKILL.md

flowchart TD
  A[API Client Factory - main/app/lib/api/getApi.ts] -->|request interceptor asks for token| B[Session Token Resolver - main/app/lib/api/auth/session.ts]
  B -->|refresh expired token using username refreshToken| C[Cognito Refresh Path - main/app/lib/api/auth/refreshSession.ts]
  B -->|token or null returned| A

  D[Auth Start Request - main/app/lib/api/auth/requestPasswordlessSignIn.ts] -->|start-signin request| F[Auth System Contract Boundary - docs/plans/auth-system.md]
  E[Auth Handoff Request - main/app/lib/api/auth/completePasswordlessSignInWithCode.ts] -->|complete-signin request| F
  D -->|builds client and sends request| A
  E -->|builds client and sends request| A
  A -->|sends auth requests with optional bearer token| F

  classDef unchanged fill:#d3d3d3,stroke:#666,stroke-width:1px;
  classDef updated fill:#ffe58a,stroke:#666,stroke-width:1px;
  classDef deleted fill:#f4a6a6,stroke:#666,stroke-width:1px;
  classDef created fill:#a8e6a3,stroke:#666,stroke-width:1px;

  class A,B,C,D,E,F unchanged;

Boundary note: docs/plans/auth-system.md is intentionally represented as a separate-system contract boundary.

2. Black-Box Inputs and Outputs

Keep this short. Define types in JSON-style blocks and capture each flow with path-level rows. Section intent: integration-level contract for start-signin and complete-signin.

Global Types

Define shared types used across multiple flows.

EmailAddress {
  value: string
}

ChallengeSession {
  value: string
}

HandoffCode {
  value: string
}

AuthSession {
  accessToken: string
  idToken: string
  refreshToken: string
  expiresAt: number
  userId: string
  username: string
}

StandardError {
  status?: number
  code?: string
  message: string
}

Flow: main/app/lib/api/auth/auth-provider.tsx.AuthProvider, main/app/__tests__/auth-provider.test.tsx, main/app/__tests__/auth-signin-api.test.ts

Type Definitions

SignInFlowInput {
  email?: EmailAddress
  handoff_code?: HandoffCode
}

SignInFlowOutput {
  phase: "start-signin" | "complete-signin"
  challenge_session?: ChallengeSession
  session?: AuthSession
  persisted_session: boolean
}

Paths

path-name input output/expected state change path-type notes updated
signin-flow.start-signin-success SignInFlowInput email valid SignInFlowOutput phase=start-signin challenge_session=string persisted_session=false happy path provider delegates to requestPasswordlessSignIn and receives challenge session
signin-flow.start-signin-invalid-email SignInFlowInput email invalid StandardError message=validation error error request is rejected before downstream auth contract call
signin-flow.complete-signin-success SignInFlowInput handoff_code valid after start-signin SignInFlowOutput phase=complete-signin session=AuthSession persisted_session=true happy path provider delegates to completePasswordlessSignInWithCode and persists returned session
signin-flow.complete-signin-invalid-code SignInFlowInput handoff_code malformed or rejected StandardError message=Unable to complete sign-in with handoff code. error complete-signin fails and no session is persisted
signin-flow.complete-signin-response-incomplete SignInFlowInput handoff_code valid but backend response missing token fields StandardError message=Unable to complete sign-in with handoff code. error wrapper rejects incomplete token bundle and prevents partial sign-in state

Test coverage note: dedicated mobile sign-in integration tests are currently not present under main/app/__tests__. Backend error/status code behavior note: see docs/plans/auth-system.md for authoritative endpoint contracts.

3. Pseudocode / Technical Details for Critical Flows (Optional)

  • Flow name:: signin-flow-integration 

    user submits email in login screen
call requestPasswordlessSignIn through auth provider
receive challenge session
user submits handoff code in verify screen
call completePasswordlessSignInWithCode through auth provider
validate returned token bundle
persist session and transition user into authenticated app surface

  • Implementation notes:

  • This plan intentionally focuses on sign-in and complete-sign-in integration behavior.
  • Route gating display outcomes remain in mobile-auth-gating.md.
  • Backend endpoint semantics remain in auth-system.md.

After all stages are approved, apply .agent/skills/reconcile-plans/SKILL.md to propagate contract updates across linked plans.