rideaware-api/TODO.md

TODO Features

User Management

• User Registration & Login: Email authentication with JWT tokens
• User Profile: Bio, stats, zones (HR/Power), equipment, FTP, weight
• Password Recovery: Email-based reset with secure tokens
• Onboarding Wizard: Guided setup with profile, metrics, equipment, and preferences steps
• [~] OAuth Integration: Garmin & Wahoo OAuth implemented; Google, Apple, Strava pending
• Account Roles: Athlete, Coach, Admin; team/org workspaces
• Multi-device Sessions: Seamless handoff across web/mobile

Workout Planning

• Workout Scheduling: Calendar view with monthly navigation, rich workout cards (duration, TSS, zone-colored segment charts, status borders)
• Templates Library: 11 built-in templates (Recovery, Endurance, Tempo, Sweet Spot, Threshold, Over-Unders, VO2max, Sprint, Ramp Test) with category browsing
• Template Scheduling: Browse and schedule templates directly from calendar Add Workout modal
• Structured Workout Builder: Interval builder with warmup/main/cooldown sections, power targets (%FTP), cadence, repeats, rest intervals, and live preview chart
• Export Structured Workouts: .zwo (Zwift), Garmin FIT/Workout, Wahoo
• AI-Powered Planning: Generate plans by goal, time, fitness level
• Adaptive Scheduling: Auto-reschedule based on missed sessions, fatigue, weather
• Goal Setting & Tracking: SMART goals with real-time progress bars
• Race/Event Planner: Target events, taper builder, gear checklist

Workout Tracking

• Workout CRUD: Create, read, update, delete workouts with calendar integration
• Device Capture: File upload (FIT/TCX/GPX activity import with metric extraction)
• ZWO Import: Client-side Zwift workout file parsing
• Equipment Tracking: Bike/components mileage auto-tracking, service interval reminders, distance/duration since last service
• [~] Tags & Notes: RPE & Notes fields implemented in backend; mood, conditions, injuries, and tag system still pending
• Drag-drop Calendar: Reorder/reschedule workouts by dragging

Workout Visualization

• Workout Detail Modal: Interval chart, auto-generated workout summary, zone distribution, completed metrics, equipment, Garmin/Wahoo push
• Power Zone System: 7-zone model (Recovery through Neuromuscular) with color-coded visualization
• Mini Segment Charts: Compact zone-colored bars on calendar cards
• Zone Distribution: Horizontal stacked bar with time-in-zone breakdown
• TSS/IF Calculation: Training Stress Score and Intensity Factor from segment data

Dashboard

• Stats Overview: Total rides, distance, time, elevation gain
• Calendar Widget: Compact monthly calendar with workout cards, month navigation
• Next Workout: Upcoming workout display with link to calendar
• Today's Progress: Completion percentage for daily workouts
• Profile Display: Welcome message with first/last name from user profile
• Interactive Charts: Activity trends (CTL/ATL/TSB), power curves

Advanced Analytics

• Stats Page: Summary, weekly, and monthly aggregated statistics
• Personal Bests: Personal records tracking
• Interactive Dashboards: Charts for training load, power curves, trends
• Progress Insights (AI): Automatic highlights, plateau detection, anomaly alerts
• Comparisons: Before/after, season-over-season, segment/time comparisons
• Custom Reports: Export CSV/PDF; shareable report links

Workout Library

• Browse Library: System and user workouts with search, category, type, and difficulty filters
• Workout Detail Page: Full workout view with interval chart and segment breakdown
• Create Custom Workouts: Interval builder with warmup/main/cooldown structure
• My Workouts: User's custom workout collection
• Favorites: Save and browse favorite workouts
• Ratings: Star rating system with comments
• Community Sharing: Public/private workout sharing

Training & Coaching

• Structured Workouts: Interval builder with targets (%FTP, cadence, repeats)
• Coaching & Guidance: Coach portal, athlete assignments, plan reviews
• Virtual Training Rides: Integrations with Zwift/Rouvy/RGT; video routes
• Messaging: Coach-athlete chat, comments on sessions, file attachments

Integrations & Data

• Garmin Connect: OAuth2 PKCE flow, push workouts, connection management
• Wahoo Cloud API: OAuth2 flow, push workouts as plans, connection management
• Activity Import: FIT (session metrics), TCX (lap aggregation), GPX (Haversine distance, elevation)
• Workout Export: FIT (Garmin-compatible), ZWO (Zwift-compatible)
• Strava Sync: OAuth login + activity sync
• TrainingPeaks: Calendar + workout push
• Intervals.icu: Integration (push workouts + sync activities)
• COROS, Apple Health, Google Fit: Wearable sync
• Music Integration: Spotify/Apple Music workout-matched playlists
• Public API & Webhooks: For partners, coaches, clubs

Nutrition & Recovery

• Nutrition Planning: Meal plans, macros, carb periodization
• Nutrition Tracking: Food log, barcode/manual entry, hydration tracking
• Recovery Optimization: Sleep/HRV import, readiness score, rest day prompts
• Injury Prevention & Management: Screeners, red-flag alerts, return-to-ride flow
• Supplement & Allergy Flags: Notes and reminders in plan builder

Community & Social

• Social Sharing: One-click share to Strava/social with privacy controls
• Community Forum: Topics, groups/clubs, moderation tools
• Leaderboards: Global, club, event, and route/segment leaderboards
• Challenges & Streaks: Time-boxed events, badges, streak protection

Gamification & Engagement

• Achievements & Badges: Milestones (consistency, PRs, climbing, streaks)
• Personalized Recommendations (AI): Next best workout, videos, articles
• Rewards & Incentives: Points store, partner discounts, raffles

Notifications & Comms

• Reminders: Email, push, SMS; smart timing
• Digest Emails: Weekly plan, monthly progress
• Real-time Alerts: Overtraining risk, missed session, weather hazard

Accessibility & Internationalization

• A11y: WCAG 2.2 AA, keyboard nav, screen reader labels
• Localization: i18n framework, units (imperial/metric), timezones
• Color-blind Safe Palettes: Analytics & maps

Mobile & Apps

• PWA Offline Mode: Log workouts offline; sync when online
• Native App Shell: Background sync, notifications, wearables bridge

Security, Privacy & Compliance

• Privacy Controls: Public/private by item, club privacy, anonymized leaderboards
• Data Protection: Encryption at rest/in transit, secrets rotation
• Compliance: GDPR/CCPA requests (export/delete), age gating, COPPA checks
• Audit Logs: Admin and coach actions

Admin, Billing & Ops

• Admin Console: User management, feature flags, content moderation
• Subscriptions: Free/Pro/Coach tiers, trials, coupons, taxes (Stripe)
• Telemetry & Observability: Metrics, tracing, error reporting, uptime SLOs
• Scalability: Queueing for imports/exports, background jobs
• Backups & DR: Automated backups, restore drills, RTO/RPO defined

Content & Library

• Exercise Library: Strength/mobility videos with cues and progressions
• Knowledge Base: Articles on training, nutrition, recovery
• Route Library: GPX planner/import, elevation profiles, weather overlays

Possible Future Features

• Virtual Reality (VR) Integration: Immersive rides with real-time metrics
• Augmented Reality (AR) Integration: HUD overlays during rides
• Machine Learning (ML) Integration: Injury risk models, plan optimization, weather-aware ETA and fueling estimates

---

Completed - Phase 1: Authentication & User Management

Infrastructure

• Migrated from Python/Flask to Go with Chi router
• Restructured project with clean architecture (cmd/, internal/, pkg/)
• PostgreSQL + GORM ORM setup with migrations
• Docker/Podman containerization with multi-stage builds

Authentication

• User signup with validation (username, email, password strength)
• User login with JWT tokens (access + refresh)
• Password hashing with bcrypt
• Protected routes with Bearer token authentication
• Password reset flow with email tokens

User Profiles

• User model with relationships (Profile, PasswordReset, Sessions)
• User profile with stats (HR zones, FTP, weight, total rides, distance, time)
• Email service integration (Resend) for notifications
• Automatic profile creation on user signup

Code Quality

• Repository pattern for data access
• Service layer for business logic
• Auth middleware for protected routes
• Error handling and validation
• Environment configuration with .env

---

Completed - Phase 2: Profiles, Equipment & Workouts

API Endpoints

• GET/PUT /api/protected/profile - Full profile management
• POST/GET/PUT/DELETE /api/protected/equipment - Bike/gear CRUD
• GET /api/protected/zones - Calculate HR & power training zones
• POST/GET/PUT/DELETE /api/protected/workouts - Full workout CRUD
• GET /api/protected/workouts/month - Calendar month filtering
• GET /api/protected/workout-types - Predefined workout types
• POST /api/protected/workouts/upload - ZWO file import & parsing
• GET /api/protected/stats/summary - Overall ride statistics
• GET /api/protected/stats/weekly - Weekly aggregated stats
• GET /api/protected/stats/monthly - Monthly aggregated stats
• GET /api/protected/stats/personal-bests - Personal records
• GET /api/protected/workout-templates - List templates (with category filter)
• GET /api/protected/workout-templates/detail - Template with full segments
• POST /api/protected/workouts/from-template - Create workout from template

---

Completed - Phase 2.5: Export & Device Integration

Workout Export

• GET /api/protected/workouts/export/fit - FIT workout file export (Garmin-compatible)
• GET /api/protected/workouts/export/zwo - ZWO file export (Zwift-compatible)
• Segment-to-FIT mapping (warmup/steady/interval/cooldown/ramp/freeride)
• Power targets converted from %FTP to absolute watts for device display
• github.com/muktihari/fit library integration for FIT encoding

OAuth Infrastructure

• OAuthConnection model with AES-256-GCM token encryption
• OAuthState model for CSRF protection during OAuth flows
• Shared OAuth service (state management, PKCE, token exchange, auto-refresh)
• OAuth config loader from environment variables

Garmin Connect Integration

• GET /api/protected/garmin/auth - OAuth2 PKCE flow initiation
• GET /api/garmin/callback - OAuth callback handler
• POST /api/protected/workouts/push/garmin - Push workout to Garmin Connect
• GET /api/protected/garmin/status - Connection status check
• DELETE /api/protected/garmin/disconnect - Revoke connection

Wahoo Cloud API Integration

• GET /api/protected/wahoo/auth - OAuth2 flow initiation
• GET /api/wahoo/callback - OAuth callback handler
• POST /api/protected/workouts/push/wahoo - Push workout as Wahoo plan
• GET /api/protected/wahoo/status - Connection status check
• DELETE /api/protected/wahoo/disconnect - Revoke connection

---

Completed - Phase 2.6: Activity Import & Equipment Mileage

Activity File Import (FIT/TCX/GPX)

• POST /api/protected/workouts/import - Import activity files (multipart upload)
• FIT activity parser using muktihari/fit decoder (session-level metrics)
• TCX activity parser (lap aggregation, trackpoint elevation gain)
• GPX activity parser (Haversine distance, elevation gain, extension parsing)
• Extracts: duration, distance, avg/max power, avg/max HR, elevation gain, calories, cadence
• Can create new completed workout or update existing planned workout with actual data
• Supports optional equipment_id assignment on import

Equipment Mileage & Service Tracking

• Auto-increment equipment mileage when activities are imported with equipment assigned
• Total distance (km), total duration (seconds), total rides tracked per equipment
• Service interval configuration (distance-based and/or duration-based)
• Distance and duration since last service counters
• POST /api/protected/equipment/service - Record service (resets counters)
• GET /api/protected/equipment/service-status - Check if equipment needs servicing

---

Completed - Phase 3: Frontend & Full-Stack Features

Vue 3 Frontend (Tailwind CSS v4)

• Vue 3 Composition API with <script setup>, Pinia stores, Vue Router 4
• Responsive dark/light mode UI with Tailwind CSS
• Docker/Podman containerized with Nginx serving

Dashboard

• Stats overview cards (rides, distance, time, elevation)
• Compact calendar widget with monthly navigation and workout cards
• Next workout display with today's progress bar
• Profile-aware welcome message (first/last name)
• Workout detail modal from calendar clicks

Calendar & Workout Management

• Full monthly calendar with TrainingPeaks-style workout cards
• Rich cards: duration, TSS badge, zone-colored mini segment chart, title, status borders
• Add Workout modal with Manual and From Template tabs
• Template browser with category filtering, detail preview (IntervalDisplay), and direct scheduling
• Workout builder (IntervalBuilder) in manual tab with warmup/main/cooldown, power targets, cadence, repeats, presets, live chart preview
• Structure-to-segments conversion for API submission
• File upload support (FIT/TCX/GPX activity import, ZWO workout import)

Workout Detail & Visualization

• IntervalDisplay chart (section-colored bars, height = power, width = time)
• Auto-generated workout summary text (detects repeat patterns)
• Zone distribution (stacked bar + time-in-zone legend)
• MiniSegmentChart for calendar cells
• 7-zone power model with hex color mapping
• TSS and IF calculation from segments
• Garmin/Wahoo push buttons with connection status

Workout Library

• Browse system + user workouts with search, filters (type, category, difficulty)
• Workout detail page with interval chart
• Create/edit custom workouts with interval builder
• My Workouts and Favorites collections
• Star rating with comments

Other Pages

• Equipment management with service tracking, mileage display, record service
• Training zones page (HR & power zones)
• Stats page (summary, weekly, monthly, personal bests)
• Templates browser page with category filter and scheduling
• Onboarding wizard (profile, metrics, equipment, preferences steps)
• Settings: Garmin/Wahoo connections page with OAuth flow
• User profile editor

---

Next Phase: Phase 4 - OAuth Login & Platform Sync

OAuth Login

• Google OAuth 2.0 (sign in with Google)
• Apple Sign-In
• Strava OAuth (sign in + activity sync)

Platform Sync

• Strava activity sync (import completed rides)
• TrainingPeaks calendar sync
• Intervals.icu integration (push workouts + sync activities)

Calendar Enhancements

• Drag-and-drop workout rescheduling
• ICS sync (Google Calendar / Apple Calendar / Outlook)
• Week view and day view options