Phase 4: Conversation Router Unification

[manavgup]

Phase 4: Router Unification

Parent Issue: #539 - Conversation System Refactoring
Depends On: Phase 3 (Service Consolidation)
Estimated Effort: 2-3 days

---

Objective

Merge 2 duplicate REST APIs (1,036 lines) into 1 unified conversation API that uses the unified service from Phase 3.

Current State

Routers to Consolidate:

• conversation_router.py (418 lines) - Full CRUD conversation API
• chat_router.py (618 lines) - Overlapping chat functionality

Problems:

• Duplicate endpoints: Both routers expose similar conversation operations
• API confusion: Developers unsure which router to use
• Maintenance burden: Changes need to be made in 2 places
• Inconsistent responses: Different error handling and response formats

---

Tasks

1. Router Analysis

• Audit all endpoints in conversation_router.py
• Audit all endpoints in chat_router.py
• Identify duplicate/overlapping endpoints
• Document endpoint differences and usage patterns
• Map frontend usage of both routers

2. Create Unified Router

• Merge all endpoints into conversation_router.py
• Standardize request/response models
• Consistent error handling across all endpoints
• Use unified service from Phase 3
• Add comprehensive OpenAPI documentation
• Include usage examples in docstrings

3. Update API Documentation

• Update OpenAPI/Swagger documentation
• Add migration guide for API consumers
• Document deprecated endpoints
• Update docs/api/index.md

4. Add Deprecation Warnings

• Add deprecation headers to chat_router.py endpoints
• Return deprecation warnings in response bodies
• Add logging for deprecated endpoint usage
• Document Phase 7 removal timeline

5. Testing

• Migrate all router tests to unified router
• Add tests for all consolidated endpoints
• Verify backward compatibility
• Test deprecated router still works with warnings
• API integration tests

---

Success Criteria

• ✅ Single unified conversation router (~600-700 lines)
• ✅ All conversation endpoints in one place
• ✅ Consistent API responses
• ✅ Uses unified service from Phase 3
• ✅ Old router deprecated with warnings
• ✅ All tests passing
• ✅ API documentation updated

---

API Consolidation Goals

• Endpoint reduction: Merge duplicate endpoints
• Response time: Maintain 3ms service performance
• Code reduction: 1,036 lines → ~600 lines (42% reduction)
• API clarity: Single source of truth for conversation operations

---

Files to Update

• backend/rag_solution/router/conversation_router.py (merge endpoints)
• backend/rag_solution/router/chat_router.py (add deprecation)
• docs/api/index.md (update API docs)
• docs/development/conversation-system-refactoring.md (update progress)

---

Migration Guide Sections

• Endpoint mapping (old → new)
• Request/response format changes
• Authentication/authorization changes
• Error handling changes
• Code examples for common operations

---

Related Issues

• Refactor conversation system: eliminate 55% redundancy and fix N+1 queries #539 - Parent: Conversation System Refactoring
• Phase 3 - Service Consolidation (dependency)