motovaultpro/ROLLBACK-PROCEDURES.md

Rollback Procedures for MotoVaultPro Modernization

Purpose: Quick recovery procedures for each phase of modernization if issues arise.

🚨 Emergency Rollback Checklist

Before any rollback:

1. Document the issue - Note what went wrong in phase file
2. Stop services - make down to stop Docker containers
3. Backup current state - git stash or create branch if changes exist
4. Execute rollback - Follow phase-specific procedures below
5. Verify system works - make dev and test basic functionality
6. Update STATUS.md - Document rollback and current state

🔄 Phase-Specific Rollback Procedures

Phase 1: Analysis & Baseline - ROLLBACK

Risk Level: 🟢 LOW (No code changes, only analysis)

# If any analysis files were created that need to be removed:
git checkout -- STATUS.md HANDOFF-PROMPTS.md ROLLBACK-PROCEDURES.md
git clean -fd  # Remove untracked phase files

# Restore baseline
make down
make dev

# Verify system works
curl http://localhost:3001/health
open http://localhost:3000

Phase 2: React 19 Foundation - ROLLBACK

Risk Level: 🟡 MEDIUM (Package.json changes)

# Stop services
make down

# Rollback package.json changes
cd frontend
git checkout -- package.json package-lock.json
cd ..

# Rebuild with original packages
make rebuild

# Verify system works
make dev
curl http://localhost:3001/health
open http://localhost:3000

# Test key functionality
# - Login flow
# - Vehicle list loads
# - No console errors

Verification Commands:

cd frontend && npm list react  # Should show 18.2.0
cd frontend && npm list react-dom  # Should show 18.2.0

Phase 3: React Compiler - ROLLBACK

Risk Level: 🟡 MEDIUM (Build configuration changes)

# Stop services
make down

# Rollback all React Compiler changes
cd frontend
git checkout -- package.json package-lock.json
git checkout -- vite.config.ts  # If modified
git checkout -- tsconfig.json   # If modified

# Remove any React Compiler dependencies
rm -rf node_modules/.cache
cd ..

# Restore manual memoization if removed
git checkout -- frontend/src/  # Restore any useMemo/useCallback

# Rebuild
make rebuild

# Verify
make dev
# Test performance - should work as before

Phase 4: Backend Evaluation - ROLLBACK

Risk Level: 🟡 MEDIUM (Parallel services)

# Stop services
make down

# Rollback backend changes
cd backend
git checkout -- package.json package-lock.json
git checkout -- src/  # Restore any Fastify code

# Remove feature flags
git checkout -- .env*  # If feature flags were added
cd ..

# Rollback Docker changes if any
git checkout -- docker-compose.yml

# Rebuild
make rebuild

# Verify Express-only backend works
make dev
curl http://localhost:3001/health
# Should only show Express endpoints

Phase 5: TypeScript Modern - ROLLBACK

Risk Level: 🟠 HIGH (Type system changes)

# Stop services  
make down

# Rollback TypeScript configs
git checkout -- backend/tsconfig.json
git checkout -- frontend/tsconfig.json
git checkout -- frontend/tsconfig.node.json

# Rollback package versions
cd backend && git checkout -- package.json package-lock.json && cd ..
cd frontend && git checkout -- package.json package-lock.json && cd ..

# Rollback any syntax changes
git checkout -- backend/src/ frontend/src/

# Full rebuild required
make rebuild

# Verify types compile
cd backend && npm run type-check
cd frontend && npm run type-check
cd .. && make dev

Phase 6: Docker Modern - ROLLBACK

Risk Level: 🟠 HIGH (Infrastructure changes)

# Stop services
make down

# Rollback Docker files
git checkout -- backend/Dockerfile backend/Dockerfile.dev
git checkout -- frontend/Dockerfile frontend/Dockerfile.dev  
git checkout -- docker-compose.yml

# Clean Docker completely
docker system prune -a --volumes
docker builder prune --all

# Rebuild from scratch
make rebuild

# Verify system works with original Docker setup
make dev
make logs  # Check for any user permission errors

Phase 7: Vehicles Fastify - ROLLBACK

Risk Level: 🔴 CRITICAL (Core feature changes)

# IMMEDIATE: Stop services
make down

# Rollback vehicles feature
cd backend
git checkout -- src/features/vehicles/
git checkout -- src/app.ts  # Restore Express routing
git checkout -- package.json package-lock.json

# Rollback any database migrations if run
# Check backend/src/features/vehicles/migrations/
# Manually rollback any schema changes if applied

# Clean rebuild
cd .. && make rebuild

# CRITICAL VERIFICATION:
make dev
# Test vehicles API endpoints:
curl -H "Authorization: Bearer $TOKEN" http://localhost:3001/api/vehicles
# Test frontend vehicles page works
# Verify vehicle CRUD operations work

Phase 8: Backend Complete - ROLLBACK

Risk Level: 🔴 CRITICAL (Full backend replacement)

# EMERGENCY STOP
make down

# Full backend rollback
cd backend
git checkout HEAD~10 -- .  # Rollback multiple commits if needed
# OR restore from known good commit:
git checkout <LAST_GOOD_COMMIT> -- src/

# Rollback package.json to Express
git checkout -- package.json package-lock.json

# Full system rebuild
cd .. && make rebuild

# FULL SYSTEM VERIFICATION:
make dev
# Test ALL features:
# - Vehicles CRUD
# - Fuel logs (if implemented)
# - Stations (if implemented)
# - Authentication
# - All API endpoints

Phase 9: React 19 Advanced - ROLLBACK

Risk Level: 🟡 MEDIUM (Advanced features)

# Stop services
make down

# Rollback advanced React 19 features
cd frontend
git checkout -- src/  # Restore to basic React 19

# Keep React 19 but remove advanced features
# Don't rollback to React 18 unless critically broken

# Rebuild
cd .. && make rebuild

# Verify basic React 19 works without advanced features
make dev

Phase 10: Final Optimization - ROLLBACK

Risk Level: 🟢 LOW (Optimization only)

# Stop services
make down

# Rollback optimization changes
git checkout -- frontend/vite.config.ts
git checkout -- backend/  # Any optimization configs
git checkout -- docker-compose.yml  # Production optimizations

# Rebuild
make rebuild

# Verify system works (may be slower but functional)
make dev

🎯 Specific Recovery Scenarios

Database Issues

# If migrations caused issues
make down
docker volume rm motovaultpro_postgres_data
make dev  # Will recreate fresh database
# Re-run migrations manually if needed
make shell-backend
npm run migrate:all

Redis/Cache Issues

# Clear all cache
make down
docker volume rm motovaultpro_redis_data
make dev

MinIO/Storage Issues

# Clear object storage
make down  
docker volume rm motovaultpro_minio_data
make dev

Complete System Reset

# NUCLEAR OPTION - Full reset to last known good state
git stash  # Save any work
git checkout main  # Or last good branch
make down
docker system prune -a --volumes
make dev

# If this doesn't work, restore from git:
git reset --hard <LAST_GOOD_COMMIT>

🔍 Verification After Rollback

Basic System Check

# Services startup
make dev
sleep 30  # Wait for startup

# Health checks
curl http://localhost:3001/health  # Backend
curl http://localhost:3000         # Frontend

# Log checks  
make logs | grep -i error

Frontend Verification

# Open frontend
open http://localhost:3000

# Check for console errors
# Test login flow
# Test main vehicle functionality
# Verify mobile/desktop responsive works

Backend Verification

# API endpoints work
curl http://localhost:3001/api/vehicles  # Should require auth
curl http://localhost:3001/health        # Should return healthy

# Database connectivity
make shell-backend
psql postgresql://postgres:localdev123@postgres:5432/motovaultpro -c "SELECT 1;"

# Redis connectivity  
redis-cli -h redis ping

Full Integration Test

# Run test suite
make test

# Manual integration test:
# 1. Login to frontend
# 2. Add a vehicle with VIN
# 3. View vehicle list
# 4. Edit vehicle
# 5. Delete vehicle
# All should work without errors

📝 Rollback Documentation

After any rollback:

1. Update STATUS.md - Set current phase back to previous
2. Update phase file - Document what went wrong
3. Create issue note - In phase file, note the failure for future reference
4. Plan retry - Note what needs to be done differently next time

---

Remember: Better to rollback early than to continue with broken system. Each phase builds on the previous, so a solid foundation is critical.