Skip to content

USER_FLOW.md

Latest commit

 

History

History
297 lines (230 loc) · 7.59 KB

USER_FLOW.md

File metadata and controls

297 lines (230 loc) · 7.59 KB

User Flow - Automatic Data Import

🎯 How It Works Now

Your Strides.ai app now automatically pulls data from Strava when a user connects! Here's the complete flow:

1. User Opens Web App

User visits: http://localhost:5173

What they see:

  • Beautiful dark dashboard with sample data
  • "Connect Strava" button in top navigation (orange gradient)
  • Training metrics, charts, and AI coach

2. User Clicks "Connect Strava"

What happens:

  1. Frontend requests authorization URL from backend
  2. User is redirected to Strava's OAuth page
  3. User logs into Strava (if not already logged in)
  4. Strava shows authorization request:
    • "Strides.ai wants to..."
    • View your activities
    • View your profile
  5. User clicks "Authorize"

3. Automatic Data Import (New!)

Behind the scenes (happens automatically):

graph LR
    A[User Authorizes] --> B[OAuth Callback]
    B --> C[Save Tokens to DB]
    C --> D[Create User Files]
    D --> E[🔄 Auto-Import 30 Runs]
    E --> F[Transform to JSON]
    F --> G[Save to activities.json]
    G --> H[Redirect to Dashboard]
    H --> I[Show User's Data!]
Loading

Import happens in seconds:

  • Fetches last 30 activities from Strava
  • Filters for runs only (Run + VirtualRun)
  • Transforms to our JSON schema
  • Saves to user_data/athlete_<id>/activities.json
  • All automatic - no manual click needed!

4. Dashboard Updates with User's Data

What the user sees:

  • ✅ Top nav shows: "Connected | [Profile Pic] John Doe"
  • 📊 Dashboard displays THEIR activities (not sample data!)
  • 🎯 Goals Manager available
  • 📥 Import more runs option (10, 30, or 100)
  • 💬 AI coach has their training data

5. Ongoing Usage

On subsequent visits:

  • User is still logged in (session persists)
  • Dashboard always shows their data
  • Can import more activities anytime
  • Can set goals via Goals Manager
  • Can chat with AI coach about their training

🔄 Data Flow

When Connected

GET /api/data
  → Check session for user_id
  → Load from user_data/athlete_<id>/activities.json
  → Return user's actual data

When Not Connected

GET /api/data
  → No user_id in session
  → Load from database (sample data)
  → Return demo data

📋 What Gets Imported Automatically

On First Connection (Automatic)

  • 30 most recent runs from Strava
  • Transformed to include:
    • Distance (miles)
    • Pace (min/mile)
    • Moving time
    • Elevation gain
    • Heart rate (if available)
    • Cadence (if available)

User Can Import More (Manual)

  • Click "10" → Last 10 runs
  • Click "30" → Last 30 runs
  • Click "100" → Full history

Data Stored

Backend/user_data/athlete_<strava_id>/
├── activities.json        # All imported runs
├── weekly_summary.json    # Aggregated by week (via n8n)
└── metadata.json          # Goals and preferences

🎨 User Experience

Before Connection

┌─────────────────────────────────────┐
│ 🏃 Training Overview                │
│ Sample data shown                   │
│                                     │
│ [Connect Strava] button visible    │
└─────────────────────────────────────┘

During Connection

┌─────────────────────────────────────┐
│ Redirecting to Strava...            │
│ ↓                                   │
│ Strava Authorization Page           │
│ "Authorize Strides.ai?"             │
│ ↓                                   │
│ Importing your activities...        │
│ (happens automatically!)            │
└─────────────────────────────────────┘

After Connection

┌─────────────────────────────────────┐
│ ✓ Connected | [Pic] John Doe       │
│                                     │
│ 🏃 YOUR Training Overview           │
│ Your actual runs displayed          │
│                                     │
│ [Goals Manager] [Import More]       │
└─────────────────────────────────────┘

💡 Key Features

✅ Automatic

  • No manual "import" button needed
  • Data appears immediately after OAuth
  • Smooth, seamless experience

✅ Multi-User Ready

  • Each user has separate data files
  • Sessions keep users logged in
  • Data never mixed between users

✅ Fallback to Demo

  • Not connected? See sample data
  • Connected? See your data
  • Graceful degradation

✅ Additional Import

  • Want more than 30 runs? Click to import
  • Choose 10, 30, or 100 activities
  • Duplicate detection (won't import twice)

🔧 Technical Implementation

Backend Changes

  1. Helper Function (import_user_activities())

    • Reusable activity import logic
    • Used by both OAuth callback and manual import

  2. OAuth Callback (/api/strava/callback)

    • After saving tokens: import_user_activities(user_id, 30)
    • Non-blocking - won't fail OAuth if import fails
    • Logs import results

  3. Data Endpoint (/api/data)

    • Checks for session['user_id']
    • If exists: load from user_data/athlete_<id>/
    • If not: load from database (sample data)

Frontend - No Changes Needed!

  • Dashboard already checks connection status
  • Automatically requests /api/data
  • Backend handles user vs. sample data

🚀 Testing the Flow

  1. Ensure Strava credentials configured

    cat Backend/.env
# Should have STRAVA_CLIENT_ID and STRAVA_CLIENT_SECRET

  2. Open dashboard

    http://localhost:5173

  3. Click "Connect Strava"

    • Redirects to Strava
    • Authorize the app

  4. Watch the magic!

    • Returns to dashboard
    • Activities automatically imported
    • Dashboard shows YOUR runs
    • No additional clicks needed

  5. Check the data

    ls -la Backend/user_data/athlete_*/
# Should see activities.json with your runs

cat Backend/user_data/athlete_*/activities.json
# Your actual Strava data!

🎯 User Journey Summary

  1. Open app → See demo data
  2. Click Connect → Go to Strava
  3. Authorize → Auto-import 30 runs
  4. Returned to app → See YOUR data
  5. Set goals → Use Goals Manager
  6. Import more → Click 10/30/100 button
  7. Chat with coach → AI knows your training!

Total clicks needed: Just 2 (Connect + Authorize)

Time to see your data: ~5 seconds

Manual steps: ZERO! Everything automatic!

📊 What This Enables

For Users

  • Instant gratification - data appears immediately
  • No learning curve - just sign in
  • Personalized experience from the start

For You (Developer)

  • Multi-user ready from day 1
  • Scalable architecture
  • Clean separation of user data

For AI Coach

  • Real training data to analyze
  • Personalized recommendations
  • Context-aware coaching

🔮 Future Enhancements

When you deploy to production and set up n8n:

  1. Real-time Sync

    • Complete a run on Strava
    • Webhook triggers n8n
    • New run appears in dashboard automatically

  2. Weekly Aggregation

    • n8n calculates weekly metrics
    • Updates weekly_summary.json
    • Dashboard charts update

  3. Advanced Analytics

    • Training load calculation
    • Fatigue detection
    • Performance trends

All built on the foundation you have now! 🎉