Comprehensive view of data flow, decision points, and AI integration
flowchart TB
Start([User Access]) --> Auth{Authenticated?}
Auth -->|No| StravaOAuth[Strava OAuth Flow]
StravaOAuth --> StoreToken[Store Access Token
in DynamoDB]
StoreToken --> CheckOnboarding{First Time
User?}
CheckOnboarding -->|Yes| Onboarding[User Onboarding Flow]
CheckOnboarding -->|No| Dashboard
%% Onboarding Flow
Onboarding --> CollectInfo[Collect User Info:
- Training Goals
- Experience Level
- Race Targets
- Available Training Time]
CollectInfo --> CalcZones{HR Zones
Known?}
CalcZones -->|No| EstimateZones[Estimate from
Recent Activities]
CalcZones -->|Yes| InputZones[User Inputs Zones]
EstimateZones --> SetupProfile[Create User Profile]
InputZones --> SetupProfile
SetupProfile --> GenerateInitialPlan[Generate Initial
Training Plan]
GenerateInitialPlan --> FetchUserHistory[Fetch Recent
Strava History]
FetchUserHistory --> AssessBaseline[Assess Current Fitness:
- Recent Volume
- Intensity Distribution
- Recovery Patterns]
AssessBaseline --> PrepareOnboardingAI[Prepare AI Context:
- User Goals
- Current Fitness
- Training Principles
- Time Constraints]
PrepareOnboardingAI --> GeminiPlanGen[Gemini AI:
Generate Periodized Plan]
GeminiPlanGen --> StructurePlan[Structure Plan:
- Base/Build/Peak/Taper
- Weekly Sessions
- Progressive Overload
- Recovery Weeks]
StructurePlan --> StorePlan[Store Plan in DynamoDB]
StorePlan --> Dashboard
Auth -->|Yes| Dashboard[Dashboard View]
%% Strava Webhook Flow
StravaWebhook[Strava Webhook Event] --> ValidateWebhook{Valid Subscription
Verification?}
ValidateWebhook -->|Challenge| ReturnChallenge[Return Challenge]
ValidateWebhook -->|Activity Event| ProcessWebhook[Process Activity Event]
ProcessWebhook --> CheckEventType{Event Type?}
CheckEventType -->|Create/Update| FetchActivity[Fetch Full Activity
from Strava API]
CheckEventType -->|Delete| RemoveActivity[Mark Activity Deleted]
FetchActivity --> ExtractMetrics[Extract Key Metrics:
- Distance, Duration
- HR Zones, Pace
- Elevation, Type]
ExtractMetrics --> StoreActivity
%% Data Storage Decision
StoreActivity{Data Size Check} -->|< 300KB| SaveDynamoDB[Store in DynamoDB]
StoreActivity -->|> 300KB| TrimAndArchive[Trim Data +
Archive to S3]
TrimAndArchive --> SaveDynamoDB
SaveDynamoDB --> CheckWeekly{End of Week?}
%% Weekly Summary Generation
CheckWeekly -->|Yes| GenerateWeekly[Trigger Weekly
Summary Generation]
CheckWeekly -->|No| End1([End])
GenerateWeekly --> FetchWeekData[Fetch Week's Activities
from DynamoDB]
FetchWeekData --> FetchGarminData{Garmin
Connected?}
FetchGarminData -->|Yes| CheckCache{Data Cached
Today?}
CheckCache -->|Yes| UseCachedGarmin[Use Cached Garmin Data]
CheckCache -->|No| FetchGarminAPI[Fetch from Garmin API:
- Sleep, HRV
- Body Battery
- Stress, Steps]
FetchGarminAPI --> CacheGarmin[Cache Daily
Garmin Data]
CacheGarmin --> UseCachedGarmin
FetchGarminData -->|No| SkipGarmin[Skip Garmin Data]
UseCachedGarmin --> PrepareAIContext[Prepare AI Context]
SkipGarmin --> PrepareAIContext
%% AI Context Preparation
PrepareAIContext --> IncludeBaseline[Include:
- Training Philosophy
- HR Zones, VDOT
- Polarized Training]
IncludeBaseline --> FetchHistoricalSummaries[Fetch Historical Context:
- Past 4 Weekly Summaries
- Last Plan Completion
- Trend Data]
FetchHistoricalSummaries --> IncludeWeekData[Include Week Data:
- All Activities
- Total Volume/TSS
- HR Distribution]
IncludeWeekData --> CheckActivePlan{Active Plan
Exists?}
CheckActivePlan -->|Yes| AddPlanContext[Add Plan Context:
- Current Phase
- Planned vs Actual
- Adherence Rate
- Upcoming Key Workouts]
CheckActivePlan -->|No| IncludeGarminMetrics
AddPlanContext --> IncludeGarminMetrics
IncludeGarminMetrics{Garmin Data
Available?}
IncludeGarminMetrics -->|Yes| AddRecovery[Add Recovery Metrics:
- Sleep Quality/Duration
- HRV Trends
- Body Battery
- Stress Levels]
IncludeGarminMetrics -->|No| SkipRecovery[Skip Recovery Data]
AddRecovery --> CheckConcerns{Recovery
Concerns?}
SkipRecovery --> SendToGemini
CheckConcerns -->|Yes| FlagConcerns[Flag Patterns:
- Low Sleep
- Declining HRV
- High Stress
- Low Body Battery]
CheckConcerns -->|No| SendToGemini[Send to Gemini AI]
FlagConcerns --> SendToGemini
%% AI Processing
SendToGemini --> GeminiAnalysis[Gemini AI Analysis:
- Training Load
- Recovery State
- Zone Distribution
- Recommendations]
GeminiAnalysis --> GenerateSummary[Generate Weekly Summary:
- Performance Analysis
- Training Balance
- Adaptation Guidance
- Next Week Plan]
GenerateSummary --> StoreSummary{Summary Size}
StoreSummary -->|< 300KB| SaveSummaryDB[Store in DynamoDB]
StoreSummary -->|> 300KB| ArchiveSummary[Archive Summary to S3
+ Store Reference]
ArchiveSummary --> SaveSummaryDB
SaveSummaryDB --> DisplaySummary[Display on Dashboard]
DisplaySummary --> End2([End])
%% Dashboard Data Flow
Dashboard --> LoadUserData[Load User Profile
from DynamoDB]
LoadUserData --> FetchRecentActivities[Fetch Recent Activities]
FetchRecentActivities --> CheckS3Archive{Large Data
in S3?}
CheckS3Archive -->|Yes| FetchS3[Fetch from S3
with Fallback]
CheckS3Archive -->|No| UseDynamoDB[Use DynamoDB Data]
FetchS3 --> MergeData[Merge Data Sources]
UseDynamoDB --> MergeData
MergeData --> FetchGarminDashboard{Fetch Garmin
Metrics?}
FetchGarminDashboard -->|Yes| CheckDailyCache{Cached
Today?}
CheckDailyCache -->|Yes| ShowCached[Show Cached Metrics]
CheckDailyCache -->|No| FetchGarminLive[Fetch Live Garmin Data]
FetchGarminLive --> UpdateCache[Update Daily Cache]
UpdateCache --> ShowCached
FetchGarminDashboard -->|No| SkipDashGarmin[Show Strava Only]
ShowCached --> DisplayDashboard[Render Dashboard:
- Recent Activities
- Weekly Summary
- Garmin Health Metrics
- Training Trends]
SkipDashGarmin --> DisplayDashboard
DisplayDashboard --> End3([End])
%% Plan Management Flow
PlanRequest[User Requests
New Plan] --> CheckExistingPlan{Active Plan
Exists?}
CheckExistingPlan -->|Yes| ConfirmReplace{Replace
Existing?}
ConfirmReplace -->|No| CancelRequest([Cancel])
ConfirmReplace -->|Yes| ArchiveOldPlan[Archive Current Plan]
CheckExistingPlan -->|No| StartNewPlan[Start Plan Generation]
ArchiveOldPlan --> StartNewPlan
StartNewPlan --> CollectPlanGoals[Collect Plan Details:
- Race Date/Distance
- Target Time
- Training Days/Week
- Key Constraints]
CollectPlanGoals --> FetchCurrentFitness[Fetch Current Fitness:
- Recent 4-8 weeks
- Volume Trends
- Best Performances]
FetchCurrentFitness --> CalculateVDOT[Calculate VDOT
from Recent Races]
CalculateVDOT --> PreparePlanAI[Prepare AI Context:
- User Profile & Zones
- Current Fitness
- Training History
- Race Goals]
PreparePlanAI --> GeminiPlanCreate[Gemini AI:
Generate Custom Plan]
GeminiPlanCreate --> PeriodizePlan[Create Periodization:
- Phase Durations
- Weekly Progression
- Recovery Integration
- Taper Schedule]
PeriodizePlan --> StorePlanData{Plan Size}
StorePlanData -->|< 300KB| SavePlanDB[Store in DynamoDB]
StorePlanData -->|> 300KB| ArchivePlanS3[Archive to S3 +
Store Reference]
ArchivePlanS3 --> SavePlanDB
SavePlanDB --> DisplayNewPlan[Display Plan
to User]
DisplayNewPlan --> PlanEnd([End])
%% Plan Completion Flow
PlanComplete[Plan End Date
Reached] --> CheckCompletion{Plan
Completed?}
CheckCompletion -->|Yes| AnalyzePlanResults[Analyze Plan Outcomes]
CheckCompletion -->|Partial| FlagIncomplete[Flag Incomplete Plan]
AnalyzePlanResults --> CompareActualVsPlanned[Compare:
- Planned vs Actual Volume
- Session Completion Rate
- Key Workout Results
- Race Performance]
FlagIncomplete --> CompareActualVsPlanned
CompareActualVsPlanned --> FetchFinalMetrics[Fetch Final Metrics:
- VDOT Change
- Volume Progression
- Recovery Trends
- Performance Gains]
FetchFinalMetrics --> GeminiPlanReview[Gemini AI:
Plan Review & Analysis]
GeminiPlanReview --> GenerateReport[Generate Completion Report:
- Success Metrics
- Lessons Learned
- Recommendations
- Next Steps]
GenerateReport --> ArchivePlanComplete[Archive Completed Plan:
- Move to S3
- Add Completion Metadata
- Link to Report]
ArchivePlanComplete --> StoreArchiveRef[Update DynamoDB
with Archive Reference]
StoreArchiveRef --> PromptNextPlan{Continue
Training?}
PromptNextPlan -->|Yes| SuggestNextGoals[Suggest Next Goals
Based on Progress]
PromptNextPlan -->|No| MarkInactive[Mark User Inactive]
SuggestNextGoals --> OfferPlanGen[Offer New
Plan Generation]
OfferPlanGen --> CompletionEnd([End])
MarkInactive --> CompletionEnd
%% Chat Interaction Flow
UserChat[User Asks Question/
Provides Feedback] --> LoadChatContext[Load Chat Context]
LoadChatContext --> FetchUserProfile[Fetch User Profile
& Current Plan]
FetchUserProfile --> FetchRecentHistory[Fetch Recent:
- Last 2 weeks activities
- Latest summary
- Recovery trends]
FetchRecentHistory --> FetchHistoricalChat[Fetch Historical Context:
- Past 4 summaries
- Recent plan changes
- Previous Q&A]
FetchHistoricalChat --> AssembleChatContext[Assemble Full Context:
- User profile/zones
- Current plan status
- Recent training
- Recovery state
- Historical summaries
- Conversation history]
AssembleChatContext --> SendChatToGemini[Send to Gemini AI]
SendChatToGemini --> GeminiChatResponse[Generate Response:
- Answer questions
- Provide guidance
- Suggest adjustments]
GeminiChatResponse --> CheckPlanUpdate{Plan Update
Needed?}
CheckPlanUpdate -->|Yes| ProposeUpdate[Propose Plan Changes]
CheckPlanUpdate -->|No| ReturnResponse[Return Response to User]
ProposeUpdate --> UserApproves{User
Approves?}
UserApproves -->|Yes| UpdatePlan[Update Active Plan]
UserApproves -->|No| ReturnResponse
UpdatePlan --> LogChange[Log Plan Change:
- Reason
- Timestamp
- Modified Sessions]
LogChange --> ReturnResponse
ReturnResponse --> ChatEnd([End])
%% Plan Adaptation Flow
WeeklySummaryComplete[Weekly Summary
Generated] --> EvaluatePlanAdherence[Evaluate Plan Adherence:
- Sessions completed
- Volume vs target
- Intensity adherence]
EvaluatePlanAdherence --> CheckDeviations{Significant
Deviations?}
CheckDeviations -->|Yes| AnalyzeDeviations[Analyze Patterns:
- Consistent under-training?
- Over-reaching?
- Missed key workouts?
- Recovery issues?]
CheckDeviations -->|No| ContinuePlan[Continue Current Plan]
AnalyzeDeviations --> AssessRecovery[Assess Recovery State:
- HRV trends
- Sleep quality
- Body Battery
- Fatigue markers]
AssessRecovery --> PrepareAdaptationContext[Prepare Adaptation Context:
- Plan structure
- Adherence data
- Recovery state
- Upcoming phases]
PrepareAdaptationContext --> GeminiAdaptation[Gemini AI:
Recommend Adaptations]
GeminiAdaptation --> GenerateAdaptations[Generate Suggestions:
- Volume adjustments
- Intensity modifications
- Recovery additions
- Session swaps]
GenerateAdaptations --> AutoApplyMinor{Minor
Adjustments?}
AutoApplyMinor -->|Yes| ApplyAutoUpdates[Auto-apply:
- Small volume tweaks
- Recovery day adds
- Log in plan history]
AutoApplyMinor -->|No| FlagForReview[Flag for User Review]
ApplyAutoUpdates --> NotifyUser[Notify User of Changes]
FlagForReview --> NotifyUser
NotifyUser --> DisplayOnDashboard[Display on Dashboard
with Rationale]
DisplayOnDashboard --> AdaptationEnd([End])
ContinuePlan --> AdaptationEnd
%% Error Handling
RemoveActivity --> End1
ReturnChallenge --> End4([End])
style GenerateWeekly fill:#90EE90
style GeminiAnalysis fill:#87CEEB
style StoreActivity fill:#FFD700
style FetchGarminAPI fill:#FFA500
style PrepareAIContext fill:#DDA0DD
style CheckConcerns fill:#FF6B6B
style Onboarding fill:#98FB98
style GenerateInitialPlan fill:#87CEEB
style GeminiPlanGen fill:#87CEEB
style GeminiPlanCreate fill:#87CEEB
style GeminiPlanReview fill:#87CEEB
style ArchivePlanComplete fill:#FFB6C1
style AnalyzePlanResults fill:#DDA0DD
style UserChat fill:#E6E6FA
style GeminiChatResponse fill:#87CEEB
style AssembleChatContext fill:#DDA0DD
style UpdatePlan fill:#FFA07A
style EvaluatePlanAdherence fill:#DDA0DD
style GeminiAdaptation fill:#87CEEB
style ApplyAutoUpdates fill:#FFA07A
style FetchHistoricalSummaries fill:#F0E68C