cim_summary/DEPLOYMENT_GUIDE.md

# Deployment Guide - Cloud-Only Architecture

This guide covers the standardized deployment process for the CIM Document Processor, which has been optimized for cloud-only deployment using Google Cloud Platform services.

## Architecture Overview

- **Frontend**: React/TypeScript application deployed on Firebase Hosting
- **Backend**: Node.js/TypeScript API deployed on Google Cloud Run (recommended) or Firebase Functions
- **Storage**: Google Cloud Storage (GCS) for all file operations
- **Database**: Supabase (PostgreSQL) for data persistence
- **Authentication**: Firebase Authentication

## Prerequisites

### Required Tools
- [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) (gcloud)
- [Firebase CLI](https://firebase.google.com/docs/cli)
- [Docker](https://docs.docker.com/get-docker/) (for Cloud Run deployment)
- [Node.js](https://nodejs.org/) (v18 or higher)

### Required Permissions
- Google Cloud Project with billing enabled
- Firebase project configured
- Service account with GCS permissions
- Supabase project configured

## Quick Deployment

### Option 1: Deploy Everything (Recommended)
```bash
# Deploy backend to Cloud Run + frontend to Firebase Hosting
./deploy.sh -a
```

### Option 2: Deploy Components Separately
```bash
# Deploy backend to Cloud Run
./deploy.sh -b cloud-run

# Deploy backend to Firebase Functions
./deploy.sh -b firebase

# Deploy frontend only
./deploy.sh -f

# Deploy with tests
./deploy.sh -t -a
```

## Manual Deployment Steps

### Backend Deployment

#### Cloud Run (Recommended)

1. **Build and Deploy**:
   ```bash
   cd backend
   npm run deploy:cloud-run
   ```

2. **Or use Docker directly**:
   ```bash
   cd backend
   npm run docker:build
   npm run docker:push
   gcloud run deploy cim-processor-backend \
     --image gcr.io/cim-summarizer/cim-processor-backend:latest \
     --region us-central1 \
     --platform managed \
     --allow-unauthenticated
   ```

#### Firebase Functions

1. **Deploy to Firebase**:
   ```bash
   cd backend
   npm run deploy:firebase
   ```

### Frontend Deployment

1. **Deploy to Firebase Hosting**:
   ```bash
   cd frontend
   npm run deploy:firebase
   ```

2. **Deploy Preview Channel**:
   ```bash
   cd frontend
   npm run deploy:preview
   ```

## Environment Configuration

### Required Environment Variables

#### Backend (Cloud Run/Firebase Functions)
```bash
NODE_ENV=production
PORT=8080
PROCESSING_STRATEGY=agentic_rag
GCLOUD_PROJECT_ID=cim-summarizer
DOCUMENT_AI_LOCATION=us
DOCUMENT_AI_PROCESSOR_ID=your-processor-id
GCS_BUCKET_NAME=cim-summarizer-uploads
DOCUMENT_AI_OUTPUT_BUCKET_NAME=cim-summarizer-document-ai-output
LLM_PROVIDER=anthropic
VECTOR_PROVIDER=supabase
AGENTIC_RAG_ENABLED=true
ENABLE_RAG_PROCESSING=true
SUPABASE_URL=your-supabase-url
SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_SERVICE_KEY=your-supabase-service-key
ANTHROPIC_API_KEY=your-anthropic-key
OPENAI_API_KEY=your-openai-key
JWT_SECRET=your-jwt-secret
JWT_REFRESH_SECRET=your-refresh-secret
```

#### Frontend
```bash
VITE_API_BASE_URL=your-backend-url
VITE_FIREBASE_API_KEY=your-firebase-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
```

## Configuration Files

### Firebase Configuration

#### Backend (`backend/firebase.json`)
```json
{
  "functions": {
    "source": ".",
    "runtime": "nodejs20",
    "ignore": [
      "node_modules",
      "src",
      "logs",
      "uploads",
      "*.test.ts",
      "*.test.js",
      "jest.config.js",
      "tsconfig.json",
      ".eslintrc.js",
      "Dockerfile",
      "cloud-run.yaml"
    ],
    "predeploy": ["npm run build"],
    "codebase": "backend"
  }
}
```

#### Frontend (`frontend/firebase.json`)
```json
{
  "hosting": {
    "public": "dist",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**",
      "src/**",
      "*.test.ts",
      "*.test.js"
    ],
    "headers": [
      {
        "source": "**/*.js",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "public, max-age=31536000, immutable"
          }
        ]
      }
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ],
    "cleanUrls": true,
    "trailingSlash": false
  }
}
```

### Cloud Run Configuration

#### Dockerfile (`backend/Dockerfile`)
- Multi-stage build for optimized image size
- Security best practices (non-root user)
- Proper signal handling with dumb-init
- Optimized for Node.js 20

#### Cloud Run YAML (`backend/cloud-run.yaml`)
- Resource limits and requests
- Health checks and probes
- Autoscaling configuration
- Environment variables

## Development Workflow

### Local Development
```bash
# Backend
cd backend
npm run dev

# Frontend
cd frontend
npm run dev
```

### Testing
```bash
# Backend tests
cd backend
npm test

# Frontend tests
cd frontend
npm test

# GCS integration tests
cd backend
npm run test:gcs
```

### Emulators
```bash
# Firebase emulators
cd backend
npm run emulator:ui

cd frontend
npm run emulator:ui
```

## Monitoring and Logging

### Cloud Run Monitoring
- Built-in monitoring in Google Cloud Console
- Logs available in Cloud Logging
- Metrics for CPU, memory, and request latency

### Firebase Monitoring
- Firebase Console for Functions monitoring
- Real-time database monitoring
- Hosting analytics

### Application Logging
- Structured logging with Winston
- Correlation IDs for request tracking
- Error categorization and reporting

## Troubleshooting

### Common Issues

1. **Build Failures**
   - Check Node.js version compatibility
   - Verify all dependencies are installed
   - Check TypeScript compilation errors

2. **Deployment Failures**
   - Verify Google Cloud authentication
   - Check project permissions
   - Ensure billing is enabled

3. **Runtime Errors**
   - Check environment variables
   - Verify service account permissions
   - Review application logs

### Debug Commands
```bash
# Check deployment status
gcloud run services describe cim-processor-backend --region=us-central1

# View logs
gcloud logs read "resource.type=cloud_run_revision"

# Test GCS connection
cd backend
npm run test:gcs

# Check Firebase deployment
firebase hosting:sites:list
```

## Security Considerations

### Cloud Run Security
- Non-root user in container
- Minimal attack surface with Alpine Linux
- Proper signal handling
- Resource limits

### Firebase Security
- Authentication required for sensitive operations
- CORS configuration
- Rate limiting
- Input validation

### GCS Security
- Service account with minimal permissions
- Signed URLs for secure file access
- Bucket-level security policies

## Cost Optimization

### Cloud Run
- Scale to zero when not in use
- CPU and memory limits
- Request timeout configuration

### Firebase
- Pay-per-use pricing
- Automatic scaling
- CDN for static assets

### GCS
- Lifecycle policies for old files
- Storage class optimization
- Request optimization

## Migration from Local Development

This deployment configuration is designed for cloud-only operation:

1. **No Local Dependencies**: All file operations use GCS
2. **No Local Database**: Supabase handles all data persistence
3. **No Local Storage**: Temporary files only in `/tmp`
4. **Stateless Design**: No persistent local state

## Support

For deployment issues:
1. Check the troubleshooting section
2. Review application logs
3. Verify environment configuration
4. Test with emulators first

For architecture questions:
- Review the design documentation
- Check the implementation summaries
- Consult the GCS integration guide