Modal Flow System

XState-powered authentication flows for complex user interactions

Modal Flow System

Overview

The authentication modal flow system uses XState to manage complex multi-step user authentication workflows. This provides predictable state management for authentication interactions while maintaining a smooth user experience.

Key Components

• XState Flow Management: Predictable state transitions for authentication steps
• Modal Flow Provider: React context for managing authentication modal state
• Step-based Progression: Guided user journey through authentication process
• Redirect Handling: Seamless navigation after successful authentication

Architecture Summary

1. Flow Definition

   • Closed state (modal hidden)
   • Email collection (determine account status)
   • Login/Register forms (based on email check)
   • Password reset flow (if needed)
   • Completion and redirect

2. State Management

   • XState machine for predictable transitions
   • React context for component access
   • Event-driven progression through steps

3. User Experience

   • Single modal for all authentication flows
   • Context-aware form presentation
   • Smooth transitions between steps

Flow Steps

Core Authentication Steps

• CLOSED: Modal is hidden, no authentication in progress
• EMAIL_COLLECTION: User enters email, system determines account status
• LOGIN: Existing user authentication form
• REGISTER: New user registration form
• REQUEST_RESET: Password reset request form
• RESET_SENT: Confirmation screen for reset email
• COMPLETE: Successful authentication, redirect to target

Flow Progression Logic

1. Email Check: Determines if account exists for provided email
2. Form Selection: Shows login or register form based on account status
3. Reset Option: Available from login form for password recovery
4. Completion: Successful authentication triggers redirect to intended destination

Provider Integration

Modal Flow Provider

The AuthModalFlowProvider wraps components that need authentication modal access:

• Manages modal visibility state
• Handles flow progression
• Provides context for authentication actions

Usage Pattern

Components can trigger authentication flows and handle completion:

• Open modal with optional redirect target
• Close modal programmatically
• Access current flow state for UI decisions

State Transitions

Entry Points

• Direct modal opening from any component
• Automatic triggering on protected route access
• Manual authentication initiation

Exit Conditions

• Successful authentication completion
• User cancellation (close modal)
• Navigation away from authentication context

Error Handling

• Invalid credentials return to appropriate form
• Network errors maintain current state with error display
• Validation errors provide inline feedback

Trade-Offs

Area	Decision	Benefit	Cost or Risk
State Management	XState machine	Predictable, debuggable	Learning curve, complexity
Modal Approach	Single modal for all flows	Consistent UX, simpler state	Less flexibility for custom flows
Flow Progression	Email-first detection	Smooth UX, fewer decisions	Additional API call overhead
Context Provider	React context	Easy component access	Provider nesting requirements

Why It Works for Nomey

• Creator onboarding → Guided flow reduces friction for new users
• Mobile-first design → Modal approach works well on all screen sizes
• Subscription focus → Clear authentication flow supports conversion
• Developer experience → XState provides debugging and testing benefits

The modal flow system creates a consistent, predictable authentication experience that guides users through complex workflows while maintaining developer confidence in state management.