cim_summary/PRODUCTION_MIGRATION_GUIDE.md

🏭 Production Migration Guide

Complete guide for safely migrating tested features from testing to production environment

📋 Overview

This guide provides a step-by-step process to safely migrate your tested features from the testing environment to production, ensuring 100% correctness and proper configuration.

---

🔍 Pre-Migration Checklist

✅ Testing Environment Validation

• All features work correctly in testing environment
• No critical bugs or issues identified
• Performance meets production requirements
• Security measures are properly implemented
• Database migrations have been tested
• API endpoints are functioning correctly
• Frontend components are working as expected

✅ Production Environment Preparation

• Production environment files exist (.env.production)
• Production Firebase project is accessible
• Production database is ready for migrations
• Production service accounts are configured
• Production API keys are available
• Production storage buckets are set up

✅ Code Quality Checks

• All tests pass in testing environment
• Code review completed
• No console.log statements in production code
• Error handling is comprehensive
• Security headers are properly configured
• Rate limiting is enabled

---

🚀 Migration Process

Step 1: Create Production Environment Files

Backend Production Environment (backend/.env.production)

# Node Environment
NODE_ENV=production

# Firebase Configuration (Production Project)
FB_PROJECT_ID=cim-summarizer
FB_STORAGE_BUCKET=cim-summarizer.appspot.com
FB_API_KEY=your-production-api-key
FB_AUTH_DOMAIN=cim-summarizer.firebaseapp.com

# Supabase Configuration (Production Instance)
SUPABASE_URL=https://your-production-project.supabase.co
SUPABASE_ANON_KEY=your-production-anon-key
SUPABASE_SERVICE_KEY=your-production-service-key

# Google Cloud Configuration (Production Project)
GCLOUD_PROJECT_ID=cim-summarizer
DOCUMENT_AI_LOCATION=us
DOCUMENT_AI_PROCESSOR_ID=your-production-processor-id
GCS_BUCKET_NAME=cim-processor-uploads
DOCUMENT_AI_OUTPUT_BUCKET_NAME=cim-processor-processed
GOOGLE_APPLICATION_CREDENTIALS=./serviceAccountKey.json

# LLM Configuration (Production with appropriate limits)
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=your-anthropic-key
LLM_MAX_COST_PER_DOCUMENT=5.00
LLM_ENABLE_COST_OPTIMIZATION=true
LLM_USE_FAST_MODEL_FOR_SIMPLE_TASKS=true

# Email Configuration (Production)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-production-email@gmail.com
EMAIL_PASS=your-app-password
EMAIL_FROM=noreply@cim-summarizer.com
WEEKLY_EMAIL_RECIPIENT=jpressnell@bluepointcapital.com

# Vector Database (Production)
VECTOR_PROVIDER=supabase

# Production-specific settings
RATE_LIMIT_MAX_REQUESTS=500
RATE_LIMIT_WINDOW_MS=900000
AGENTIC_RAG_DETAILED_LOGGING=false
AGENTIC_RAG_PERFORMANCE_TRACKING=true
AGENTIC_RAG_ERROR_REPORTING=true

# Week 8 Features Configuration
# Cost Monitoring
COST_MONITORING_ENABLED=true
USER_DAILY_COST_LIMIT=100.00
USER_MONTHLY_COST_LIMIT=1000.00
DOCUMENT_COST_LIMIT=25.00
SYSTEM_DAILY_COST_LIMIT=5000.00

# Caching Configuration
CACHE_ENABLED=true
CACHE_TTL_HOURS=168
CACHE_SIMILARITY_THRESHOLD=0.85
CACHE_MAX_SIZE=50000

# Microservice Configuration
MICROSERVICE_ENABLED=true
MICROSERVICE_MAX_CONCURRENT_JOBS=10
MICROSERVICE_HEALTH_CHECK_INTERVAL=30000
MICROSERVICE_QUEUE_PROCESSING_INTERVAL=5000

# Processing Strategy
PROCESSING_STRATEGY=document_ai_agentic_rag
ENABLE_RAG_PROCESSING=true
ENABLE_PROCESSING_COMPARISON=false

# Agentic RAG Configuration
AGENTIC_RAG_ENABLED=true
AGENTIC_RAG_MAX_AGENTS=6
AGENTIC_RAG_PARALLEL_PROCESSING=true
AGENTIC_RAG_VALIDATION_STRICT=true
AGENTIC_RAG_RETRY_ATTEMPTS=3
AGENTIC_RAG_TIMEOUT_PER_AGENT=60000

# Agent-Specific Configuration
AGENT_DOCUMENT_UNDERSTANDING_ENABLED=true
AGENT_FINANCIAL_ANALYSIS_ENABLED=true
AGENT_MARKET_ANALYSIS_ENABLED=true
AGENT_INVESTMENT_THESIS_ENABLED=true
AGENT_SYNTHESIS_ENABLED=true
AGENT_VALIDATION_ENABLED=true

# Quality Control
AGENTIC_RAG_QUALITY_THRESHOLD=0.8
AGENTIC_RAG_COMPLETENESS_THRESHOLD=0.9
AGENTIC_RAG_CONSISTENCY_CHECK=true

# Logging Configuration
LOG_LEVEL=info
LOG_FILE=logs/production.log

# Security Configuration
BCRYPT_ROUNDS=12

# Database Configuration (Production)
DATABASE_URL=https://your-production-project.supabase.co
DATABASE_HOST=db.supabase.co
DATABASE_PORT=5432
DATABASE_NAME=postgres
DATABASE_USER=postgres
DATABASE_PASSWORD=your-production-supabase-password

# Redis Configuration (Production)
REDIS_URL=redis://localhost:6379
REDIS_HOST=localhost
REDIS_PORT=6379

Frontend Production Environment (frontend/.env.production)

# Firebase Configuration (Production)
VITE_FIREBASE_API_KEY=your-production-api-key
VITE_FIREBASE_AUTH_DOMAIN=cim-summarizer.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=cim-summarizer
VITE_FIREBASE_STORAGE_BUCKET=cim-summarizer.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your-production-sender-id
VITE_FIREBASE_APP_ID=your-production-app-id

# Backend API (Production)
VITE_API_BASE_URL=https://us-central1-cim-summarizer.cloudfunctions.net/api

# Environment
VITE_NODE_ENV=production

Step 2: Configure Firebase Projects

Backend Firebase Configuration (backend/.firebaserc)

{
  "projects": {
    "default": "cim-summarizer",
    "production": "cim-summarizer",
    "testing": "cim-summarizer-testing"
  }
}

Frontend Firebase Configuration (frontend/.firebaserc)

{
  "projects": {
    "default": "cim-summarizer",
    "production": "cim-summarizer",
    "testing": "cim-summarizer-testing"
  }
}

Step 3: Run the Production Migration Script

# Make the script executable
chmod +x deploy-production.sh

# Run the production migration
./deploy-production.sh

The script will automatically:

1. ✅ Run pre-migration checks
2. ✅ Create a production backup branch
3. ✅ Switch to production environment
4. ✅ Run production tests
5. ✅ Build for production
6. ✅ Run database migrations
7. ✅ Deploy to production
8. ✅ Verify deployment

---

🔧 Manual Migration Steps (Alternative)

If you prefer to run the migration manually:

Step 1: Create Production Backup

# Create backup branch
BACKUP_BRANCH="backup-production-$(date +%Y%m%d-%H%M%S)"
git checkout -b "$BACKUP_BRANCH"
git add .
git commit -m "Backup: Production state before migration $(date)"
git checkout preview-capabilities-phase1-2

Step 2: Switch to Production Environment

# Switch backend to production
cd backend
cp .env.production .env
firebase use production
cd ..

# Switch frontend to production
cd frontend
cp .env.production .env
firebase use production
cd ..

Step 3: Run Tests and Build

# Backend tests and build
cd backend
npm test
npm run build
cd ..

# Frontend tests and build
cd frontend
npm test
npm run build
cd ..

Step 4: Run Database Migrations

cd backend
export NODE_ENV=production
npm run db:migrate
cd ..

Step 5: Deploy to Production

# Deploy Firebase Functions
firebase deploy --only functions --project cim-summarizer

# Deploy Firebase Hosting
firebase deploy --only hosting --project cim-summarizer

# Deploy Firebase Storage rules
firebase deploy --only storage --project cim-summarizer

Step 6: Verify Deployment

# Test health endpoint
curl -s "https://cim-summarizer.web.app/health"

# Test API endpoints
curl -s "https://cim-summarizer.web.app/api/cost/user-metrics"
curl -s "https://cim-summarizer.web.app/api/cache/stats"
curl -s "https://cim-summarizer.web.app/api/processing/health"

---

🔄 Rollback Process

If you need to rollback to the previous production version:

Step 1: Switch to Backup Branch

git checkout backup-production-YYYYMMDD-HHMMSS

Step 2: Switch to Production Environment

./scripts/switch-environment.sh production

Step 3: Deploy Backup Version

firebase deploy --only functions,hosting,storage --project cim-summarizer

Step 4: Return to Main Branch

git checkout preview-capabilities-phase1-2

---

📊 Post-Migration Verification

Health Checks

1. Frontend Health: Visit https://cim-summarizer.web.app
2. API Health: Check https://cim-summarizer.web.app/health
3. Authentication: Test login/logout functionality
4. Document Upload: Upload a test document
5. Document Processing: Process a test document
6. PDF Generation: Download a generated PDF
7. Cost Monitoring: Check cost tracking functionality
8. Cache Management: Verify caching is working
9. Microservice Health: Check processing queue status

Performance Monitoring

1. Response Times: Monitor API response times
2. Error Rates: Check for any new errors
3. Cost Tracking: Monitor actual costs vs. expected
4. Database Performance: Check query performance
5. Memory Usage: Monitor Firebase Functions memory usage

Security Verification

1. Authentication: Verify all endpoints require proper authentication
2. Rate Limiting: Test rate limiting functionality
3. Input Validation: Test input validation on all endpoints
4. CORS: Verify CORS is properly configured
5. Security Headers: Check security headers are present

---

🚨 Troubleshooting

Common Issues

Environment Configuration Issues

# Check environment variables
cd backend
node -e "console.log(process.env.NODE_ENV)"
cd ../frontend
node -e "console.log(process.env.VITE_NODE_ENV)"

Firebase Project Issues

# Check current Firebase project
firebase projects:list
firebase use

# Switch to correct project
firebase use production

Database Migration Issues

# Check migration status
cd backend
npm run db:migrate:status

# Run migrations manually
npm run db:migrate

Deployment Issues

# Check Firebase Functions logs
firebase functions:log --project cim-summarizer

# Check deployment status
firebase functions:list --project cim-summarizer

Emergency Rollback

If immediate rollback is needed:

# Quick rollback to backup
git checkout backup-production-YYYYMMDD-HHMMSS
./scripts/switch-environment.sh production
firebase deploy --only functions,hosting,storage --project cim-summarizer

---

📈 Monitoring and Maintenance

Daily Monitoring

1. Health Checks: Monitor application health
2. Error Logs: Review error logs for issues
3. Performance Metrics: Track response times and throughput
4. Cost Monitoring: Monitor daily costs
5. User Activity: Track user engagement

Weekly Maintenance

1. Log Analysis: Review and clean up logs
2. Performance Optimization: Identify and fix bottlenecks
3. Security Updates: Apply security patches
4. Backup Verification: Verify backup processes
5. Cost Analysis: Review cost trends and optimization opportunities

Monthly Reviews

1. Feature Performance: Evaluate new feature performance
2. User Feedback: Review user feedback and issues
3. Infrastructure Scaling: Plan for scaling needs
4. Security Audit: Conduct security reviews
5. Documentation Updates: Update documentation as needed

---

✅ Success Criteria

Your production migration is successful when:

• All features work correctly in production
• No critical errors in production logs
• Performance meets or exceeds requirements
• Security measures are properly enforced
• Cost monitoring is accurate and functional
• Caching system is working efficiently
• Microservice architecture is stable
• Database migrations completed successfully
• All API endpoints are accessible and secure
• Frontend is responsive and error-free

---

🎉 Congratulations! Your production migration is complete and ready for users!

Last Updated: 2025-08-16
Migration Status: Ready for Execution