AICyclingCoach/CL_backendfixes.md

🎯 Backend Implementation TODO List

Priority 1: Core API Gaps (Essential)

1.1 Plan Generation Endpoint

• Add plan generation endpoint in app/routes/plan.py

  @router.post("/generate", response_model=PlanSchema)
  async def generate_plan(
      plan_request: PlanGenerationRequest,
      db: AsyncSession = Depends(get_db)
  ):
  

• Create PlanGenerationRequest schema in app/schemas/plan.py

  class PlanGenerationRequest(BaseModel):
      rule_ids: List[UUID]
      goals: Dict[str, Any]
      user_preferences: Optional[Dict[str, Any]] = None
      duration_weeks: int = 12
  

• Update AIService.generate_plan() to handle rule fetching from DB
• Add validation for rule compatibility and goal requirements
• Add tests for plan generation workflow

1.2 Rule Parsing API

• Add natural language rule parsing endpoint in app/routes/rule.py

  @router.post("/parse-natural-language")
  async def parse_natural_language_rules(
      request: NaturalLanguageRuleRequest,
      db: AsyncSession = Depends(get_db)
  ):
  

• Create request/response schemas in app/schemas/rule.py

  class NaturalLanguageRuleRequest(BaseModel):
      natural_language_text: str
      rule_name: str
  
  class ParsedRuleResponse(BaseModel):
      parsed_rules: Dict[str, Any]
      confidence_score: Optional[float]
      suggestions: Optional[List[str]]
  

• Enhance AIService.parse_rules_from_natural_language() with better error handling
• Add rule validation after parsing
• Add preview mode before saving parsed rules

1.3 Section Integration with GPX Parsing

• Update app/services/gpx.py to create sections automatically

  async def parse_gpx_with_sections(file_path: str, route_id: UUID, db: AsyncSession) -> dict:
      # Parse GPX into segments
      # Create Section records for each segment
      # Return enhanced GPX data with section metadata
  

• Modify app/routes/gpx.py to create sections after route creation
• Add section creation logic in GPX upload workflow
• Update Section model to include more GPX-derived metadata
• Add section querying endpoints for route visualization

Priority 2: Data Model Enhancements

2.1 Missing Schema Fields

• Add missing fields to User model in app/models/user.py

  class User(BaseModel):
      name: Optional[str]
      email: Optional[str]
      fitness_level: Optional[str]
      preferences: Optional[JSON]
  

• Enhance Plan model with additional metadata

  class Plan(BaseModel):
      user_id: Optional[UUID] = Column(ForeignKey("users.id"))
      name: str
      description: Optional[str]
      start_date: Optional[Date]
      end_date: Optional[Date]
      goal_type: Optional[str]
      active: Boolean = Column(default=True)
  

• Add plan-rule relationship table (already exists but ensure proper usage)
• Update all schemas to match enhanced models

2.2 Database Relationships

• Fix User-Plan relationship in models
• Add cascade delete rules where appropriate
• Add database constraints for data integrity
• Create missing indexes for performance

  CREATE INDEX idx_workouts_garmin_activity_id ON workouts(garmin_activity_id);
  CREATE INDEX idx_plans_user_active ON plans(user_id, active);
  CREATE INDEX idx_analyses_workout_approved ON analyses(workout_id, approved);
  

Priority 3: API Completeness

3.1 Export/Import Functionality

• Create export service app/services/export_import.py

  class ExportImportService:
      async def export_user_data(user_id: UUID) -> bytes:
      async def export_routes() -> bytes:
      async def import_user_data(data: bytes, user_id: UUID):
  

• Add export endpoints in new app/routes/export.py

  @router.get("/export/routes")
  @router.get("/export/plans/{plan_id}")
  @router.get("/export/user-data")
  @router.post("/import/routes")
  @router.post("/import/plans")
  

• Support multiple formats (JSON, GPX, ZIP)
• Add data validation for imports
• Handle version compatibility for imports

3.2 Enhanced Dashboard API

• Expand dashboard data in app/routes/dashboard.py

  @router.get("/metrics/weekly")
  @router.get("/metrics/monthly") 
  @router.get("/progress/{plan_id}")
  @router.get("/upcoming-workouts")
  

• Add aggregation queries for metrics
• Cache dashboard data for performance
• Add real-time updates capability

3.3 Advanced Workout Features

• Add workout comparison endpoint

  @router.get("/workouts/{workout_id}/compare/{compare_workout_id}")
  

• Add workout search/filtering

  @router.get("/workouts/search")
  async def search_workouts(
      activity_type: Optional[str] = None,
      date_range: Optional[DateRange] = None,
      power_range: Optional[PowerRange] = None
  ):
  

• Add bulk workout operations
• Add workout tagging system

Priority 4: Service Layer Improvements

4.1 AI Service Enhancements

• Add prompt caching to reduce API calls
• Implement prompt A/B testing framework
• Add AI response validation and confidence scoring
• Create AI service health checks
• Add fallback mechanisms for AI failures
• Implement rate limiting for AI calls
• Add cost tracking for AI API usage

4.2 Garmin Service Improvements

• Add incremental sync instead of full sync
• Implement activity deduplication logic
• Add webhook support for real-time sync
• Enhance error recovery for failed syncs
• Add activity type filtering
• Support multiple Garmin accounts per user

4.3 Plan Evolution Enhancements

• Add plan comparison functionality
• Implement plan rollback mechanism
• Add plan branching for different scenarios
• Create plan templates system
• Add automated plan adjustments based on performance

Priority 5: Validation & Error Handling

5.1 Input Validation

• Add comprehensive Pydantic validators for all schemas
• Validate GPX file integrity before processing
• Add business rule validation (e.g., plan dates, workout conflicts)
• Validate AI responses before storing
• Add file size/type restrictions

5.2 Error Handling

• Create custom exception hierarchy

  class CyclingCoachException(Exception):
  class GarminSyncError(CyclingCoachException):
  class AIServiceError(CyclingCoachException):
  class PlanGenerationError(CyclingCoachException):
  

• Add global exception handler
• Improve error messages for user feedback
• Add error recovery mechanisms
• Log errors with context for debugging

Priority 6: Performance & Monitoring

6.1 Performance Optimizations

• Add database query optimization
• Implement caching for frequently accessed data
• Add connection pooling configuration
• Optimize GPX file parsing for large files
• Add pagination to list endpoints
• Implement background job queue for long-running tasks

6.2 Enhanced Monitoring

• Add application metrics (response times, error rates)
• Create health check dependencies
• Add performance profiling endpoints
• Implement alerting for critical errors
• Add audit logging for data changes

Priority 7: Security & Configuration

7.1 Security Improvements

• Implement user authentication/authorization
• Add rate limiting to prevent abuse
• Validate file uploads for security
• Add CORS configuration properly
• Implement request/response logging (without sensitive data)
• Add API versioning support

7.2 Configuration Management

• Add environment-specific configs
• Validate configuration on startup
• Add feature flags system
• Implement secrets management
• Add configuration reload without restart

Priority 8: Testing & Documentation

8.1 Testing

• Create comprehensive test suite
  • Unit tests for services
  • Integration tests for API endpoints
  • Database migration tests
  • AI service mock tests
• Add test fixtures for common data
• Implement test database setup/teardown
• Add performance tests for critical paths
• Create end-to-end tests for workflows

8.2 Documentation

• Generate OpenAPI documentation
• Add endpoint documentation with examples
• Create service documentation
• Document deployment procedures
• Add troubleshooting guides

---

🎯 Recommended Implementation Order:

1. Week 1: Priority 1 (Core API gaps) - Essential for feature completeness
2. Week 2: Priority 2 (Data model) + Priority 5.1 (Validation) - Foundation improvements
3. Week 3: Priority 3.1 (Export/Import) + Priority 4.1 (AI improvements) - User-facing features
4. Week 4: Priority 6 (Performance) + Priority 8.1 (Testing) - Production readiness

This todo list will bring your backend implementation to 100% design doc compliance and beyond, making it production-ready with enterprise-level features! 🚀