UI/UX + User Flows

Document the user journeys and interaction flows for your application.

Primary User Flows

Onboarding Flow

Steps:

1. User lands on homepage
2. Clicks "Get Started" or "Sign Up"
3. BetterAuth authentication flow initiates
4. User creates account (email/OAuth)
5. Redirected to profile setup (optional)
6. Arrives at dashboard with onboarding tips

Subscription Purchase Flow

Steps:

1. User views pricing page
2. Selects subscription tier
3. System checks authentication
4. If not logged in: redirected to sign in
5. Polar.sh checkout modal opens
6. User completes payment
7. Webhook updates subscription status
8. Confirmation page with next steps
9. Premium features unlocked

Core Feature Usage Flow

Document your main feature's user flow:

Secondary User Flows

Email Notification Flow

sequenceDiagram
    participant User
    participant App
    participant Convex
    participant Resend
    participant Email

    User->>App: Performs Action
    App->>Convex: Trigger Action
    Convex->>Convex: Process Logic
    Convex->>Resend: Send Email Request
    Resend->>Email: Deliver Email
    Email->>User: Receive Notification

Triggers:

• Welcome email on signup
• Subscription confirmation
• Payment receipt
• Feature notifications
• Weekly digest

AI Chat Interaction Flow

Steps:

1. User types message in chat
2. Message sent to Convex action
3. Action calls OpenAI API
4. Response streamed back to client
5. UI updates in real-time

Error & Edge Cases

Payment Failure Flow

Session Expiration Flow

Mobile vs Desktop Flows

Responsive Behavior

Conversion Funnel

Track where users drop off:

Drop-off Points to Monitor:

1. Landing → Sign Up: Unclear value proposition?
2. Sign Up → Trial: Friction in onboarding?
3. Trial → Active: Feature complexity?
4. Active → Paid: Pricing concerns?

User Personas & Flows

Persona 1: First-Time User

Goal: Understand the product and complete first task

Flow:

1. Lands on homepage
2. Watches demo video
3. Signs up for free account
4. Completes onboarding tutorial
5. Creates first item
6. Invites team member (optional)

Persona 2: Returning User

Goal: Quick access to regular workflow

Flow:

1. Direct login from bookmark
2. Dashboard shows recent activity
3. Continues previous work
4. Performs daily tasks
5. Logs out

Persona 3: Power User

Goal: Maximize efficiency with advanced features

Flow:

1. Uses keyboard shortcuts
2. Bulk operations
3. API integration setup
4. Custom automation rules
5. Analytics dashboard review

Accessibility Considerations

• Keyboard Navigation: All flows accessible via keyboard
• Screen Readers: ARIA labels for flow steps
• Visual Indicators: Clear focus states
• Error Messages: Descriptive and actionable
• Skip Links: Jump to main content

Flow Optimization Opportunities

Metrics to Track

• Time to First Value: How quickly users achieve their first success
• Completion Rate: % of users who finish key flows
• Drop-off Points: Where users abandon the flow
• Error Rate: How often users encounter errors
• User Satisfaction: Feedback scores for each flow