DEPLOYMENT_GUIDE.md

# Deployment & Migration Guide

Complete guide for deploying the new React frontend and updated Flask backend.

## Overview

This project has been upgraded with:
- **Modern React 18 Frontend** with Framer Motion animations
- **Updated Flask Backend** with REST API endpoints
- **Improved State Management** with Zustand
- **Professional SaaS Design** with black & emerald colors

## Quick Migration Path

### For Current Users

If you're already running the project with the old HTML interface:

1. **Backup your current setup**
```bash
cp job_apply_ai/ui/app.py job_apply_ai/ui/app_legacy.py
```

2. **Switch to new Flask app**
```bash
# Rename the new app to be the main file
mv job_apply_ai/ui/app_new.py job_apply_ai/ui/app.py
```

3. **Install frontend dependencies**
```bash
cd frontend
npm install
cd ..
```

4. **Start both servers**
```bash
# Terminal 1: Backend
python -m job_apply_ai.ui.app

# Terminal 2: Frontend (for development)
cd frontend
npm run dev
```

## Development Setup

### Local Development with Hot Reload

```bash
# Terminal 1: Start Flask backend
source venv/bin/activate  # or venv\Scripts\activate.bat on Windows
python -m job_apply_ai.ui.app

# Terminal 2: Start React dev server
cd frontend
npm install  # if first time
npm run dev
```

Visit: `http://localhost:3000`

### Build Frontend for Production

```bash
cd frontend
npm run build
```

Output: `frontend/dist/` → copied to `job_apply_ai/ui/static/dist/`

## Deployment Options

### Option 1: Standalone Flask Server (Recommended)

Serves both the React frontend and API from a single Flask server.

#### Steps

1. **Build Frontend**
```bash
cd frontend
npm run build
```

2. **Install Dependencies**
```bash
pip install -r requirements.txt
pip install flask-cors  # New dependency for API
```

3. **Run the Server**
```bash
python -m job_apply_ai.ui.app
```

4. **Access the App**
- Main app: `http://localhost:5050`
- API endpoints: `http://localhost:5050/api/*`

#### Environment Variables

```bash
# Core
FLASK_ENV=production
FLASK_DEBUG=False
SECRET_KEY=your_random_secret_key_here
PORT=5050

# Storage
JOB_APPLY_AI_DATA_DIR=/path/to/data

# Tailoring
CV_TAILORING_MODE=local  # or 'api'
CV_ENABLE_SUMMARY_TAILORING=1

# For API mode
LLM_PROVIDER=groq
GROQ_API_KEY=your_key_here
GROQ_MODEL=llama-3.3-70b-versatile
```

### Option 2: Docker Deployment

Create a `Dockerfile`:

```dockerfile
FROM node:18-alpine as frontend
WORKDIR /app/frontend
COPY frontend/package*.json ./
RUN npm install
COPY frontend/ .
RUN npm run build

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt && pip install flask-cors gunicorn

COPY . .
COPY --from=frontend /app/frontend/dist ./job_apply_ai/ui/static/dist

ENV FLASK_ENV=production
ENV PYTHONUNBUFFERED=1

EXPOSE 5050
CMD ["gunicorn", "--bind", "0.0.0.0:5050", "job_apply_ai.ui.app:app"]
```

Build and run:
```bash
docker build -t job-apply-ai .
docker run -p 5050:5050 job-apply-ai
```

### Option 3: Separate Frontend & Backend

Run React and Flask on different servers (useful for separate scaling).

#### Backend (Flask)
```bash
FLASK_ENV=production python -m job_apply_ai.ui.app
```

#### Frontend (Nginx/Vercel/etc)
```bash
# Build
cd frontend
npm run build

# Deploy to Vercel, Netlify, or your own server
npm install -g vercel
vercel deploy dist
```

In `vite.config.ts`, update API URL:
```typescript
server: {
  proxy: {
    '/api': {
      target: 'https://your-backend.com',  // Change to production backend
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, '')
    }
  }
}
```

## Production Checklist

- [ ] Set `FLASK_DEBUG=False`
- [ ] Use `sqlite` or `postgresql` for sessions (not default)
- [ ] Set strong `SECRET_KEY`
- [ ] Configure CORS properly for your domain
- [ ] Enable HTTPS in production
- [ ] Set appropriate resource limits
- [ ] Configure backup for generated CVs
- [ ] Set up monitoring/logging
- [ ] Test file uploads with various CV formats
- [ ] Verify batch processing stability with many jobs

## Performance Optimization

### Frontend
```bash
# Analyze bundle
npm install -g vite-plugin-visualizer
npm run build -- --analyze
```

### Backend
```python
# Use production-grade WSGI server
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5050 job_apply_ai.ui.app:app
```

### Caching
- Enable browser caching for static assets
- Use Redis for session storage (optional)
- Implement job result caching

## Scaling Considerations

### Horizontal Scaling
- Use reverse proxy (Nginx) to load balance
- Store sessions in Redis or database
- Use shared storage for generated CVs

### Vertical Scaling
- Increase worker processes for Flask/Gunicorn
- Allocate more memory for CV processing
- Use distributed task queue for batch jobs

## Troubleshooting

### Frontend won't load
```bash
# Check if Flask is running
curl http://localhost:5050

# Check if React build exists
ls job_apply_ai/ui/static/dist/index.html

# Verify CORS is enabled
npm run dev  # Use dev server instead
```

### API endpoints returning 404
- Ensure `app_new.py` is being used (not legacy `app.py`)
- Check Flask logs for errors
- Verify API routes match frontend expectations

### File upload fails
- Check upload folder permissions
- Verify disk space available
- Check file size limits in Flask config

### Memory issues
- Reduce max job batch size
- Implement streaming for large CVs
- Use separate worker processes

## Rollback Procedure

If issues occur:

```bash
# Restore old Flask app
mv job_apply_ai/ui/app.py job_apply_ai/ui/app_new.py
mv job_apply_ai/ui/app_legacy.py job_apply_ai/ui/app.py

# Restart server
python -m job_apply_ai.ui.app
```

## Support

For issues or questions:
1. Check frontend logs in browser DevTools
2. Check Flask logs in terminal
3. Review specific error messages
4. Contact project maintainers

## Next Steps

- [ ] Test the new React frontend thoroughly
- [ ] Migrate user data if needed
- [ ] Train users on new interface
- [ ] Monitor performance and stability
- [ ] Gather feedback for improvements