# Package Upgrade Plan

## Overview
Upgrading all packages to latest versions before codebase becomes too complex. Strategy: upgrade incrementally, test after each major upgrade, fix breaking changes.

## Backend Packages to Upgrade

### Critical Major Version Upgrades (Breaking Changes Expected)

1. **NestJS Framework** (v10 → v11) - MAJOR
   - @nestjs/common: 10.4.20 → 11.1.6
   - @nestjs/core: 10.4.20 → 11.1.6
   - @nestjs/platform-express: 10.4.20 → 11.1.6
   - @nestjs/platform-socket.io: 10.4.20 → 11.1.6
   - @nestjs/websockets: 10.4.20 → 11.1.6
   - @nestjs/testing: 10.4.20 → 11.1.6
   - @nestjs/cli: 10.4.9 → 11.0.10
   - @nestjs/schematics: 10.2.3 → 11.0.7
   - **Breaking Changes**: Check NestJS v11 migration guide
   - **Risk**: HIGH - Core framework upgrade
   - **Test Requirements**: Full regression testing

2. **Apollo Server** (v4 → v5) - MAJOR
   - @apollo/server: 4.12.2 → 5.0.0
   - **Breaking Changes**: GraphQL schema changes, middleware changes
   - **Risk**: MEDIUM - Only affects GraphQL endpoints
   - **Test Requirements**: GraphQL endpoint testing

3. **Jest** (v29 → v30) - MAJOR
   - jest: 29.7.0 → 30.2.0
   - @types/jest: 29.5.14 → 30.0.0
   - **Breaking Changes**: Test framework syntax changes
   - **Risk**: LOW - Mainly test code
   - **Test Requirements**: Run test suite

4. **ESLint** (v8 → v9) - MAJOR
   - eslint: 8.57.1 → 9.36.0
   - eslint-config-prettier: 9.1.2 → 10.1.8
   - **Breaking Changes**: Flat config format
   - **Risk**: LOW - Development tool only
   - **Test Requirements**: Linting passes

5. **OpenAI SDK** (v5 → v6) - MAJOR
   - openai: 5.23.2 → 6.0.1
   - **Breaking Changes**: API method signatures
   - **Risk**: MEDIUM - Affects AI features
   - **Test Requirements**: AI conversation testing

### Minor/Patch Version Upgrades (Low Risk)

6. **AWS SDK** - PATCH
   - @aws-sdk/client-s3: 3.899.0 → 3.901.0
   - @aws-sdk/lib-storage: 3.900.0 → 3.901.0
   - @aws-sdk/s3-request-presigner: 3.899.0 → 3.901.0
   - **Risk**: VERY LOW - Patch updates

7. **TypeScript** - PATCH
   - typescript: 5.9.2 → 5.9.3
   - **Risk**: VERY LOW - Patch update

8. **Node Types** - MAJOR (but safe)
   - @types/node: 20.19.18 → 24.6.2
   - **Risk**: LOW - Type definitions only

9. **Other Minor Updates**
   - @nestjs/graphql: 13.1.0 → 13.2.0
   - cache-manager: 7.2.2 → 7.2.3
   - redis: 5.8.2 → 5.8.3

## Upgrade Strategy

### Phase 1: Low-Risk Patches (Start Here)
```bash
# Patch updates - safe, no breaking changes
npm update typescript
npm update @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
npm update cache-manager redis
npm update @types/node
```
- **Test**: Basic compile + server starts
- **Time**: 10 minutes

### Phase 2: Minor Version Bumps
```bash
npm install @nestjs/graphql@latest
```
- **Test**: GraphQL endpoints still work
- **Time**: 15 minutes

### Phase 3: OpenAI SDK Upgrade (Medium Risk)
```bash
npm install openai@latest
```
- **Check**: OpenAI v6 migration guide
- **Fix**: AI conversation code
- **Test**: Voice transcription + AI chat
- **Time**: 30-60 minutes

### Phase 4: Jest Upgrade (Medium Risk)
```bash
npm install -D jest@latest @types/jest@latest
npm install -D ts-jest@latest  # May need update too
```
- **Check**: Jest v30 migration guide
- **Fix**: Test configuration
- **Test**: Run full test suite
- **Time**: 30-45 minutes

### Phase 5: ESLint Upgrade (Medium Risk)
```bash
npm install -D eslint@latest eslint-config-prettier@latest
```
- **Check**: ESLint v9 flat config migration
- **Fix**: .eslintrc.js → eslint.config.js
- **Test**: Linting passes
- **Time**: 30-45 minutes

### Phase 6: Apollo Server Upgrade (High Risk)
```bash
npm install @apollo/server@latest
```
- **Check**: Apollo Server v5 migration guide
- **Fix**: GraphQL server setup
- **Test**: All GraphQL queries/mutations
- **Time**: 1-2 hours

### Phase 7: NestJS v11 Upgrade (HIGHEST RISK - DO LAST)
```bash
npm install @nestjs/common@latest @nestjs/core@latest @nestjs/platform-express@latest @nestjs/platform-socket.io@latest @nestjs/websockets@latest
npm install -D @nestjs/cli@latest @nestjs/schematics@latest @nestjs/testing@latest
```
- **Check**: NestJS v11 migration guide: https://docs.nestjs.com/migration-guide
- **Fix**: Breaking changes across entire codebase
- **Test**: FULL regression testing
- **Time**: 2-4 hours

## Testing Checklist After Each Phase

- [ ] Backend compiles with no TypeScript errors
- [ ] Server starts successfully
- [ ] Health endpoint responds
- [ ] Auth endpoints work (login/register)
- [ ] Protected endpoints require JWT
- [ ] Database connections work
- [ ] GraphQL playground loads (if applicable)
- [ ] WebSocket connections work
- [ ] All tests pass
- [ ] No new console warnings

## Rollback Plan

Each phase should be committed separately:
```bash
git add .
git commit -m "Phase X: Upgrade [package names]"
```

If issues arise:
```bash
git revert HEAD
npm install
```

## Estimated Total Time

- Phase 1-2: 30 minutes
- Phase 3-5: 2-3 hours
- Phase 6-7: 3-6 hours

**Total: 5-9 hours** (spread over multiple sessions)

## Notes

- Keep backend server running in watch mode to catch compile errors immediately
- Test each endpoint manually after major upgrades
- Check deprecation warnings in console
- Update this document with any issues encountered