ALwrity/backend/api/content_planning/docs/INTEGRATION_PLAN.md

Content Planning Module - Integration Plan

📋 Current Status

✅ Completed:

1. Folder Structure: Moved to backend/api/content_planning/
2. Models: Request and response models extracted
3. Utilities: Error handlers, response builders, constants
4. First Routes: Strategies and calendar events routes
5. Testing Foundation: Comprehensive test suite in place

🔄 In Progress:

1. Route Extraction: Need to extract remaining routes
2. Service Layer: Need to extract business logic
3. Integration: Need to integrate with main app

❌ Remaining:

1. Gap Analysis Routes: Extract gap analysis endpoints
2. AI Analytics Routes: Extract AI analytics endpoints
3. Calendar Generation Routes: Extract calendar generation endpoints
4. Health Monitoring Routes: Extract health endpoints
5. Service Layer: Extract business logic services
6. Main App Integration: Update main app to use new structure

🎯 Next Steps (Priority Order)

Phase 1: Complete Route Extraction (Day 2-3)

1.1 Extract Gap Analysis Routes

# Create gap_analysis.py route file
touch backend/api/content_planning/api/routes/gap_analysis.py

Endpoints to extract:

• POST /gap-analysis/ - Create gap analysis
• GET /gap-analysis/ - Get gap analyses
• GET /gap-analysis/{analysis_id} - Get specific analysis
• POST /gap-analysis/analyze - Analyze content gaps

1.2 Extract AI Analytics Routes

# Create ai_analytics.py route file
touch backend/api/content_planning/api/routes/ai_analytics.py

Endpoints to extract:

• POST /ai-analytics/content-evolution - Content evolution analysis
• POST /ai-analytics/performance-trends - Performance trends
• POST /ai-analytics/predict-performance - Performance prediction
• POST /ai-analytics/strategic-intelligence - Strategic intelligence
• GET /ai-analytics/ - Get AI analytics
• GET /ai-analytics/stream - Stream AI analytics
• GET /ai-analytics/results/{user_id} - Get user results
• POST /ai-analytics/refresh/{user_id} - Refresh analysis
• DELETE /ai-analytics/cache/{user_id} - Clear cache
• GET /ai-analytics/statistics - Get statistics
• GET /ai-analytics/health - AI analytics health

1.3 Extract Calendar Generation Routes

# Create calendar_generation.py route file
touch backend/api/content_planning/api/routes/calendar_generation.py

Endpoints to extract:

• POST /generate-calendar - Generate comprehensive calendar
• POST /optimize-content - Optimize content for platform
• POST /performance-predictions - Predict content performance
• POST /repurpose-content - Repurpose content across platforms
• GET /trending-topics - Get trending topics
• GET /comprehensive-user-data - Get comprehensive user data
• GET /calendar-generation/health - Calendar generation health

1.4 Extract Health Monitoring Routes

# Create health_monitoring.py route file
touch backend/api/content_planning/api/routes/health_monitoring.py

Endpoints to extract:

• GET /health - Content planning health
• GET /health/backend - Backend health
• GET /health/ai - AI services health
• GET /database/health - Database health
• GET /debug/strategies/{user_id} - Debug strategies

Phase 2: Extract Service Layer (Day 3)

2.1 Create Service Files

# Create service files
touch backend/api/content_planning/services/strategy_service.py
touch backend/api/content_planning/services/calendar_service.py
touch backend/api/content_planning/services/gap_analysis_service.py
touch backend/api/content_planning/services/ai_analytics_service.py
touch backend/api/content_planning/services/calendar_generation_service.py

2.2 Extract Business Logic

• Move business logic from routes to services
• Create service interfaces
• Implement dependency injection
• Add service layer error handling

Phase 3: Main App Integration (Day 4)

3.1 Update Main App

# In backend/app.py or main router file
from api.content_planning.api.router import router as content_planning_router

# Include the router
app.include_router(content_planning_router)

3.2 Remove Original File

# After successful integration and testing
rm backend/api/content_planning.py

Phase 4: Testing & Validation (Day 4)

4.1 Run Comprehensive Tests

cd backend/api/content_planning/tests
python run_tests.py

4.2 Validate Integration

• Test all endpoints through main app
• Verify response consistency
• Check error handling
• Validate performance

🚀 Implementation Commands

Step 1: Extract Remaining Routes

# Create route files
cd backend/api/content_planning/api/routes
touch gap_analysis.py ai_analytics.py calendar_generation.py health_monitoring.py

Step 2: Update Router

# Update router.py to include all routes
from .routes import strategies, calendar_events, gap_analysis, ai_analytics, calendar_generation, health_monitoring

router.include_router(strategies.router)
router.include_router(calendar_events.router)
router.include_router(gap_analysis.router)
router.include_router(ai_analytics.router)
router.include_router(calendar_generation.router)
router.include_router(health_monitoring.router)

Step 3: Create Service Layer

# Create service files
cd backend/api/content_planning/services
touch strategy_service.py calendar_service.py gap_analysis_service.py ai_analytics_service.py calendar_generation_service.py

Step 4: Update Main App

# In backend/app.py
from api.content_planning.api.router import router as content_planning_router
app.include_router(content_planning_router)

📊 Success Criteria

Functionality Preservation

• ✅ All existing endpoints work identically
• ✅ Response formats unchanged
• ✅ Error handling consistent
• ✅ Performance maintained

Code Quality

• ✅ File sizes under 300 lines
• ✅ Function sizes under 50 lines
• ✅ Clear separation of concerns
• ✅ Consistent patterns

Maintainability

• ✅ Easy to navigate structure
• ✅ Clear dependencies
• ✅ Comprehensive testing
• ✅ Good documentation

🎯 Timeline

Day 2: Complete Route Extraction

• Extract gap analysis routes
• Extract AI analytics routes
• Extract calendar generation routes
• Extract health monitoring routes
• Update main router

Day 3: Service Layer & Integration

• Create service layer
• Extract business logic
• Update main app integration
• Test integration

Day 4: Testing & Validation

• Run comprehensive tests
• Validate all functionality
• Performance testing
• Remove original file

🔧 Rollback Plan

If issues arise during integration:

1. Keep Original File: Don't delete original until fully validated
2. Feature Flags: Use flags to switch between old and new
3. Gradual Migration: Move endpoints one by one
4. Comprehensive Testing: Test each step thoroughly
5. Easy Rollback: Maintain ability to revert quickly

📞 Support

For issues during integration:

1. Check test results for specific failures
2. Review error logs and stack traces
3. Verify import paths and dependencies
4. Test individual components in isolation
5. Use debug endpoints to troubleshoot