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

cp job_apply_ai/ui/app.py job_apply_ai/ui/app_legacy.py

2. Switch to new Flask app

# 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

cd frontend
npm install
cd ..

4. Start both servers

# 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

# 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

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

cd frontend
npm run build

2. Install Dependencies

pip install -r requirements.txt
pip install flask-cors  # New dependency for API

3. Run the Server

python -m job_apply_ai.ui.app

4. Access the App

• Main app: http://localhost:5050
• API endpoints: http://localhost:5050/api/*

Environment Variables

# 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:

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:

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)

FLASK_ENV=production python -m job_apply_ai.ui.app

Frontend (Nginx/Vercel/etc)

# 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:

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

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

Backend

# 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

# 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:

# 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