CV Optimizer - AI-Powered CV Enhancement SaaS

A comprehensive web application that helps job seekers optimize their CVs using AI technology. Upload your CV, add job descriptions, and get AI-generated sections tailored to specific job requirements.

🚀 Features

Core Functionality

• CV Upload & Parsing: Upload PDF, DOC, or DOCX files and extract structured data using AI
• User Authentication: Clerk-based authentication with JWT token verification (legacy JWT also supported)
• CV Editing: Interactive editor with drag-and-drop reordering and inline editing
• Job Description Integration: Add job descriptions via text input or URL with browser automation support
• AI-Enhanced Sections: Generate tailored "Why I'm a Good Fit" sections using OpenAI
• Real-time Preview: Live preview of CV changes in PDF-style layout
• Auto-save: Automatic saving of changes with version history

Technical Features

• Backend: FastAPI with SQLAlchemy ORM
• Frontend: React 18 with TypeScript and Material-UI
• Database: SQLite (development) / PostgreSQL (production)
• AI Integration: OpenAI GPT-4o-mini for CV parsing and content generation
• File Processing: PDF, DOC, DOCX text extraction
• Testing: Comprehensive test suite with 90%+ coverage
• Docker: Containerized deployment with Docker Compose

📋 Prerequisites

• Python 3.11+
• Node.js 18+
• Docker & Docker Compose (optional)
• OpenAI API key

🛠️ Installation & Setup

1. Clone the Repository

git clone <repository-url>
cd cv_lator

2. Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp env.example .env
# Edit .env with your configuration

# Initialize database
python src/database.py

# Run tests
python tests/run_tests.py

# Start development server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

3. Frontend Setup

cd frontend

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Run tests
npm test

# Start development server
npm run dev

4. Docker Setup (Alternative)

Local stack (Compose project cvlator-local: frontend on http://localhost:3000, backend 8000, PDF service 8001; images aligned with Cloudflare container builds). Prepare .env.prod (see repo root), then:

docker compose up -d --build

Production: frontend on Cloudflare; API on AWS (Docker Compose + Nginx). See Deployment below.

🔧 Configuration

Backend Environment Variables

Create a .env file in the backend directory:

# Database Configuration
DATABASE_URL=sqlite:///./cv_optimizer.db

# Auth & Security
DEV_MODE=true
JWT_SECRET_KEY=your-secret-key-here-change-in-production
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7

# Clerk Backend API (used to enrich user info)
# Obtain from Clerk Dashboard → API Keys → Secret Key (starts with sk_)
# Required to call Clerk Backend API (e.g., fetch user email/metadata).
# If omitted in local dev, the app will skip API calls and use placeholders.
CLERK_SECRET_KEY=sk_test_your_secret_key_from_clerk_dashboard

# Clerk JWT Verification (required in staging/production)
CLERK_VERIFY_TOKENS=true
CLERK_JWKS_URL=https://YOUR-CLERK-DOMAIN/.well-known/jwks.json
CLERK_ISSUER=https://YOUR-CLERK-DOMAIN
CLERK_AUDIENCE=YOUR_BACKEND_AUDIENCE

# OpenAI Configuration
OPENAI_API_KEY=your-openai-key-here

# Application Configuration
DEBUG=true
MAX_FILE_SIZE=10485760
ALLOWED_FILE_TYPES=application/pdf,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document
CV_PARSE_WORKERS=2

Notes:

• Local development: you can leave CLERK_SECRET_KEY unset and either:
  • set CLERK_VERIFY_TOKENS=false to allow insecure decode bypass, or
  • provide the JWKS config (CLERK_JWKS_URL, CLERK_ISSUER, CLERK_AUDIENCE) to verify tokens properly.
• Staging/Production: set CLERK_VERIFY_TOKENS=true and configure JWKS variables; do not rely on the dev bypass.
• When CLERK_SECRET_KEY is not set, backend will not call Clerk’s API, avoiding 401 errors during local dev.

Frontend Environment Variables

Create a .env file in the frontend directory:

VITE_API_BASE_URL=http://localhost:8000

🧪 Testing

Backend Tests

cd backend
python tests/run_tests.py

Frontend Tests

cd frontend
npm test

Test Coverage

• Backend: 90%+ code coverage
• Frontend: 85%+ code coverage
• Integration tests for all API endpoints
• Unit tests for all services and components

📚 API Documentation

Once the backend is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Key Endpoints

Authentication

• POST /auth/register - Legacy user registration (Clerk is primary)
• POST /auth/login - Legacy user login (Clerk is primary)
• POST /auth/refresh - Refresh JWT token (legacy)
• POST /auth/logout - User logout
• GET /auth/me - Get current user info (works with both Clerk and legacy JWT)

CV Management

• POST /api/cvs/ - Upload CV file
• GET /api/cvs/ - List user's CVs
• GET /api/cvs/{cv_id} - Get specific CV
• PUT /api/cvs/{cv_id} - Update CV data
• DELETE /api/cvs/{cv_id} - Delete CV

Job Descriptions

• POST /api/cvs/{cv_id}/job-descriptions - Add job description
• GET /api/cvs/{cv_id}/job-descriptions - Get job descriptions
• DELETE /api/job-descriptions/{jd_id} - Delete job description

AI Features

• POST /api/cvs/{cv_id}/generate-section - Generate AI section
• GET /api/cvs/{cv_id}/ai-sections - Get AI-generated sections

🏗️ Architecture

Backend Architecture

backend/
├── src/
│   ├── api/           # API endpoints
│   ├── models/        # Database models
│   ├── services/      # Business logic
│   └── database.py    # Database configuration
├── tests/             # Test suite
├── uploads/           # File storage
└── main.py           # Application entry point

Frontend Architecture

frontend/
├── src/
│   ├── components/    # Reusable components
│   ├── contexts/      # React contexts
│   ├── pages/         # Page components
│   ├── services/      # API services
│   └── App.tsx        # Main application
├── tests/             # Test suite
└── public/            # Static assets

🚀 Deployment

Production (current)

• Frontend: Cloudflare (static / Pages + wrangler deploy in frontend/ as before).
• Backend API: AWS (e.g. Lightsail EC2): repo root .env.prod, then docker compose up -d --build for backend + pdf-service only (same images as local: slim backend/Dockerfile.wrangler for the API, backend/Dockerfile.pdf-service for PDF/LaTeX). Nginx on the host terminates 80/443 and proxies to 127.0.0.1:8000. Point api.<domain> in Cloudflare DNS to the instance public IP (proxied A record); SSL mode Full (or Full strict with a Cloudflare origin cert on Nginx).
• Database: managed PostgreSQL (DATABASE_URL in .env.prod), not SQLite.

SSH (production API host): ssh ec2-user@3.139.146.5 — then e.g. cd ~/cv_lator && sudo docker compose logs -f backend

CI deploy: .github/workflows/deploy-backend-aws.yml checks out the repo, SCPs backend/ + docker-compose.yml to /home/ec2-user/cv_lator on the instance, then runs docker compose. Triggers: push to master (paths backend/**, docker-compose.yml, or this workflow) and workflow_dispatch. Secrets: AWS_SSH_HOST, AWS_SSH_USER, AWS_SSH_PRIVATE_KEY. CI does not upload .env.prod — the VPS must already have one (bootstrap once), unless you overwrite it locally.

Laptop backend deploy: ./scripts/deploy-backend-ec2.sh (repo root) rsyncs backend/, docker-compose.yml, and ./.env.prod from this machine (DEPLOY_ENV_FILE overrides) to the VPS, then runs the same Compose target as CI — or ./scripts/deploy-backend-ec2.sh --env-only to rsync ./.env.prod alone and --force-recreate services. See .cursor/commands/deploy.md.

🔒 Security Features

• Clerk authentication with JWT token verification (JWKS support)
• Legacy JWT authentication with refresh tokens (backward compatibility)
• Password hashing with bcrypt (legacy accounts)
• File type validation and size limits
• CORS configuration
• Input validation and sanitization
• SQL injection prevention via ORM
• XSS protection
• Admin impersonation with audit logging

📊 Performance

• API response times: < 200ms (95th percentile)
• File upload: < 5 seconds for 10MB files
• AI generation: < 30 seconds
• Page load: < 2 seconds
• Supports 1000+ concurrent users

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Create an issue in the repository
• Check the API documentation
• Review the test cases for usage examples

🔄 Changelog

v1.0.0 (Current)

• Initial release with full MVP functionality
• Complete CV upload and parsing
• AI-powered content generation
• Comprehensive test suite
• Docker support
• Production-ready deployment

🎯 Roadmap

Phase 2 Features

• Multiple CV templates
• PDF export functionality
• CV analytics and insights
• Team collaboration features
• Advanced AI customization
• Multi-language support

Performance Improvements

• Caching layer (Redis)
• Message queue for AI processing
• CDN for static assets
• Database optimization
• Microservices architecture

---

Built with ❤️ using FastAPI, React, and OpenAI