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`
  ```python
  @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`
  ```python
  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`
  ```python
  @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`
  ```python
  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
  ```python
  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`
  ```python
  class User(BaseModel):
      name: Optional[str]
      email: Optional[str]
      fitness_level: Optional[str]
      preferences: Optional[JSON]
  ```
- [ ] **Enhance Plan model** with additional metadata
  ```python
  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
  ```sql
  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`
  ```python
  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`
  ```python
  @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`
  ```python
  @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**
  ```python
  @router.get("/workouts/{workout_id}/compare/{compare_workout_id}")
  ```
- [ ] **Add workout search/filtering**
  ```python
  @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**
  ```python
  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! 🚀