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 specified handler categories.

## Project Goal
Refactor all get, update, delete, and share handlers in the following modules to accept and utilize the `AuthenticatedUser` object from `middleware` instead of just a `user_id` parameter:
- `libs/handlers/src/chats/`
- `libs/handlers/src/metrics/`
- `libs/handlers/src/collections/`
- `libs/handlers/src/dashboards/`

This will improve security, reduce database queries, and create more consistent code patterns.

## Prioritized Implementation Order

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

### 1. Metrics Handlers (Week 1)
- Implementation outlined in `api_metrics_handlers_refactor.md`
- Includes test utilities creation as part of this PRD
- Refactor metric handlers and tests
- Make REST endpoint updates
- Run comprehensive tests to validate the changes
- ✅ Success criteria: All metric handlers and tests pass with the new parameter format

### 2. Chat Handlers (Week 2)
- Implementation outlined in `api_chat_handlers_refactor.md`
- Refactor chat handlers and tests
- Make REST endpoint updates
- Run comprehensive tests to validate the changes
- ✅ Success criteria: All chat handlers and tests pass with the new parameter format

### 3. Collection Handlers (Week 3)
- Implementation outlined in `api_collections_handlers_refactor.md`
- Refactor collection handlers and tests
- Make REST endpoint updates
- Run comprehensive tests to validate the changes
- ✅ Success criteria: All collection handlers and tests pass with the new parameter format

### 4. Dashboard Handlers (Week 4)
- Implementation outlined in `api_dashboards_handlers_refactor.md`
- Refactor dashboard handlers and tests
- Make REST endpoint updates
- Run comprehensive tests to validate the changes
- ✅ Success criteria: All dashboard handlers and tests pass with the new parameter format

## Dependency Graph

```
Metrics Handlers (includes test utilities)
    |
    ├────> Chat Handlers
    |
    ├────> Collection Handlers
    |
    └────> Dashboard Handlers
```

## Progress Tracking
Each sub-PRD will track its own implementation progress with these status indicators:
- ✅ Completed
- ⏳ In Progress
- 🔜 Planned
- ❌ Blocked

## Testing Integration

Testing is integrated into each PRD's implementation plan. Each handler refactoring will not be considered complete until:

1. The necessary test utilities are implemented (as part of the metrics handlers PRD)
2. All unit tests for the handlers are updated to use the new parameter format
3. All tests pass with the new implementation
4. Integration tests validate that REST endpoints work with the refactored handlers

## General Pattern for Each Handler Refactoring

For each handler category, the implementation will follow this general pattern:

1. Update function signatures from `user_id: &Uuid` to `user: &AuthenticatedUser`
2. Update function implementations to use `user.id` where appropriate
3. Enhance permission checking using organizational and team roles
4. Update tests to use the test utilities
5. Verify all tests pass
6. Update related REST endpoints
7. Validate with integration testing

## 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
The overall project will be considered successful when:
- All specified 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
- Improved security with more comprehensive permission checks

## Timeline
Total estimated duration: 4 weeks

- Week 1: Metrics handlers (includes test utilities)
- Week 2: Chat handlers
- Week 3: Collection handlers
- Week 4: Dashboard handlers

## 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