buster/api/prds/active/api_handler_refactoring_implementation_plan.md

Handler Refactoring Implementation Plan

Overview

This PRD outlines the overall implementation plan and priority order for the handler authentication refactoring project. It serves as a master plan that brings together all the individual refactoring PRDs for different handler categories.

Project Goal

Refactor all get, update, delete, and share handlers in libs/handlers to accept and utilize the AuthenticatedUser object from middleware instead of just a user_id parameter. This will improve security, reduce database queries, and create more consistent code patterns.

Dependencies

All sub-PRDs depend on the test utility implementation:

• api_handler_test_utils_implementation.md

Prioritized Implementation Order

The refactoring work should be completed in the following priority order to minimize integration issues and maximize efficiency:

Phase 1: Core Infrastructure (Week 1)

1. ⏳ Test Utilities (api_handler_test_utils_implementation.md)

   • Create mock AuthenticatedUser functions
   • Update test helper modules
   • Enable testing with various user roles
   • Estimated time: 1-2 days
   • Highest priority: Required for all other work

2. 🔜 Metrics Handlers (api_metrics_handlers_refactor.md)

   • Refactor metric handlers and tests
   • Use existing tests as validation
   • Enhance permission checks
   • Estimated time: 1 week
   • High priority: Has existing tests to validate approach

Phase 2: Core Functionality (Week 2)

3. 🔜 Chat Handlers (api_chat_handlers_refactor.md)

   • Refactor chat handlers
   • Update chat tests
   • Optimize user information usage
   • Estimated time: 1 week
   • High priority: Core application functionality

4. 🔜 Message Handlers (api_messages_handlers_refactor.md)

   • Refactor message handlers
   • Leverage chat handler patterns
   • Estimated time: 1-2 days
   • Medium-high priority: Part of chat functionality

Phase 3: Asset Management (Week 3)

5. 🔜 Collection Handlers (api_collections_handlers_refactor.md)

   • Refactor collection handlers
   • Update asset relationship logic
   • Estimated time: 1 week
   • Medium priority: Used throughout the application

6. 🔜 Dashboard Handlers (api_dashboards_handlers_refactor.md)

   • Refactor dashboard handlers
   • Update collection relationship logic
   • Estimated time: 1 week
   • Medium priority: Used throughout the application

Phase 4: Remaining Handlers (Week 4-5)

7. 🔜 Favorites Handlers (api_favorites_handlers_refactor.md)

   • Refactor favorites handlers
   • Relatively simple changes
   • Estimated time: 1-2 days
   • Lower priority: Used across multiple features

8. 🔜 Data Source Handlers (api_data_source_handlers_refactor.md)

   • Refactor data source handlers
   • Enhance organization-level permissions
   • Estimated time: 2-3 days
   • Lowest priority: Less direct user interaction

Phase 5: Integration and Testing (Week 5)

9. 🔜 Integration Testing

   • Run comprehensive integration tests
   • Validate all functionality works together
   • Fix any integration issues
   • Estimated time: 2-3 days

10. 🔜 Documentation and Cleanup

    • Update developer documentation
    • Clean up any temporary code
    • Final validation
    • Estimated time: 1-2 days

Dependency Graph

Test Utilities
    |
    ├─────> Metrics Handlers
    |
    ├─────> Chat Handlers ────> Message Handlers
    |
    ├─────> Collection Handlers ────> Dashboard Handlers
    |
    ├─────> Favorites Handlers
    |
    └─────> Data Source Handlers

Progress Tracking

Each sub-PRD will track its own implementation progress with these status indicators:

• ✅ Completed
• ⏳ In Progress
• 🔜 Planned
• ❌ Blocked

Testing Strategy

Unit Tests

• Each refactored handler must have updated unit tests
• Tests must use the new test utilities
• Tests should verify different user roles and permissions

Integration Tests

• End-to-end tests must validate complete request flows
• Cross-module tests must verify proper interaction between components
• Performance tests should confirm no regression

Rollback Procedure

If major issues are discovered during implementation:

1. Revert the specific handlers causing problems
2. Document issues in detail
3. Continue with other handlers that aren't affected
4. Create a mitigation plan before attempting the problematic handlers again

Success Criteria

• All handlers accept AuthenticatedUser instead of just user_id
• All tests pass with the new implementation
• REST endpoints properly pass the AuthenticatedUser object
• No regression in functionality or performance
• Code is more maintainable and consistent
• Improved security with more comprehensive permission checks

Timeline

Total estimated duration: 5 weeks

• Week 1: Test utilities and metrics handlers
• Week 2: Chat and message handlers
• Week 3: Collection and dashboard handlers
• Week 4: Favorites and data source handlers
• Week 5: Integration testing, documentation, and cleanup

References

• middleware::AuthenticatedUser struct in libs/middleware/src/types.rs
• Handler documentation in documentation/handlers.mdc
• PRD guidelines in documentation/prds.mdc
• Individual sub-PRDs for each handler category