ResumeAI - AI-Powered Resume Builder

ResumeAI is a full-stack SaaS application that helps users create professional resumes with AI-powered enhancements. Build, customize, and export resumes in PDF format with job-specific tailoring.

Features

• 📝 Visual Resume Editor - User-friendly interface for editing resume content
• 🤖 AI-Powered Tailoring - Automatically customize resumes for specific job postings
• 📄 PDF Export - Generate professional PDF resumes
• 🎨 Template System - Multiple resume templates to choose from
• 💼 Job Applications - Track and manage job applications
• 📦 Resume Packages - Generate tailored resume packages

Architecture

ResumeAI consists of two main components:

Component	Technology	Description
Frontend	React 19 + TypeScript + Vite	Single Page Application
Backend	FastAPI + Python	REST API with resume generation

For detailed architecture documentation, see CLAUDE.md.

Prerequisites

Before running ResumeAI, ensure you have the following installed:

• Node.js (v18+) - Download
• Python: 3.11 or 3.12 (Python 3.14 is NOT supported due to PyMuPDF compatibility)
• LaTeX - Required for PDF generation
  • macOS: brew install texlive
  • Ubuntu: sudo apt-get install texlive-latex-base
  • Windows: TeX Live
• Docker (optional) - For containerized deployment

Installation

Frontend Setup

# Clone the repository
git clone https://github.com/anchapin/ResumeAI.git
cd ResumeAI

# Install dependencies
npm install

# Create local environment file
cp .env.example .env.local

# Configure environment variables
# Edit .env.local and add your API keys (see Configuration section)

# Start development server
npm run dev

The frontend will be available at http://localhost:5173

Backend Setup

# Navigate to API directory
cd resume-api

# Create virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

# Create environment file
cp .env.example .env

# Configure environment variables
# Edit .env and add your API keys

# Start the API server
python main.py

The API will be available at http://127.0.0.1:8000

Docker Setup

# Build and run the backend container
cd resume-api
docker-compose up

# Or build manually
docker build -t resume-api:latest .
docker run -p 8000:8000 resume-api:latest

Local Development with Docker Compose

ResumeAI provides a docker-compose.local.yml file for setting up local development services including PostgreSQL, Redis, and the API.

Prerequisites

• Docker installed and running
• Docker Compose installed

Quick Start

# Copy the example environment file
cp .env.local.example .env.local

# Start all local services (PostgreSQL, Redis, API)
docker-compose -f docker-compose.local.yml up -d

# View logs
docker-compose -f docker-compose.local.yml logs -f

# Stop all services
docker-compose -f docker-compose.local.yml down

Services

Service	Port	Description
PostgreSQL	5432	Local database
Redis	6379	Cache backend
API	8000	ResumeAI API
Frontend	5173	Vite dev server (optional)

Using the Frontend

To also run the frontend in the local stack:

# The frontend service is disabled by default
# To enable, edit docker-compose.local.yml and uncomment the frontend service

# Or run frontend locally with npm
npm run dev

Environment Variables

The .env.local.example file contains all required variables. Key settings:

• DATABASE_URL: PostgreSQL connection string
• REDIS_URL: Redis connection string
• CACHE_BACKEND: Set to redis to use Redis caching
• REQUIRE_API_KEY=false: Disable API key auth for local development

Configuration

Frontend (.env.local)

# API Configuration
VITE_API_URL=http://127.0.0.1:8000

# AI Provider (optional - uses default if not set)
GEMINI_API_KEY=your_gemini_api_key_here

Backend (resume-api/.env)

# AI Configuration
AI_PROVIDER=openai  # Options: openai, claude, gemini
AI_MODEL=gpt-4o
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-...
GEMINI_API_KEY=...

# API Authentication
MASTER_API_KEY=rai_your_master_api_key_here
REQUIRE_API_KEY=true  # Set to false for development

# GitHub OAuth Configuration (REQUIRED)
GITHUB_CLIENT_ID=your_github_client_id_here
GITHUB_CLIENT_SECRET=your_github_client_secret_here
GITHUB_REDIRECT_URI=http://localhost:5173/auth/github/callback

# Server
HOST=0.0.0.0
PORT=8000
DEBUG=false

GitHub OAuth Setup

1. Register a GitHub OAuth App:

   • Go to https://github.com/settings/developers
   • Click "New OAuth App"
   • Fill in the application details:
     • Application name: ResumeAI
     • Homepage URL: http://localhost:5173 (for development)
     • Application description: Resume builder with GitHub integration
     • Authorization callback URL: http://localhost:8000/github/callback
   • Copy the Client ID and Client Secret

2. Configure Environment Variables:

   • Add GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET to your .env file
   • Set GITHUB_REDIRECT_URI to match your deployment environment

3. Frontend OAuth Configuration (.env.local):

   # Backend API URL
   VITE_API_URL=http://127.0.0.1:8000

GitHub Integration

ResumeAI uses GitHub OAuth for secure authentication and integration:

OAuth Flow

1. User clicks "Connect GitHub" in the settings or sync dialog
2. Frontend requests OAuth URL from backend (GET /github/connect)
3. User is redirected to GitHub to authorize the application
4. GitHub redirects back to the callback endpoint with authorization code
5. Backend exchanges code for access token (GET /github/callback)
6. Token is encrypted and stored in the database
7. User can now sync GitHub projects and manage their repositories

API Endpoints

• GET /github/connect - Initiate OAuth authorization flow
• GET /github/callback - Handle OAuth callback from GitHub
• GET /github/status - Check current GitHub connection status
• GET /github/repositories - Fetch user's GitHub repositories
• DELETE /github/disconnect - Disconnect GitHub account and revoke token

For detailed API documentation, see API_DOCUMENTATION.md.

API Documentation

Once the backend is running:

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

For detailed API documentation, see API_DOCUMENTATION.md.

Testing

ResumeAI maintains 60% minimum code coverage for both frontend and backend. Coverage is automatically checked on all PRs.

Running Tests

# Frontend tests
npm test                    # Run tests in watch mode
npm run test:coverage       # Run tests with coverage report

# Backend tests (from project root)
cd resume-api
python -m pytest                                    # Run all tests
python -m pytest --cov=resume-api --cov-report=html  # Run with coverage

For detailed coverage information and how to improve test coverage, see COVERAGE_GUIDE.md.

Development Commands

Frontend

Command	Description
npm run dev	Start development server
npm run build	Build for production
npm run preview	Preview production build
npm test	Run tests
npm run test:coverage	Run tests with coverage report
npm run docs	Generate TypeScript documentation

Backend

cd resume-api

# Run development server
python main.py

# Run tests
pytest

# Test specific module
python -m pytest tests/test_validation.py

Deployment

Frontend (Vercel)

The frontend is deployed to Vercel. See VERCEL_DEPLOYMENT.md for detailed instructions.

Quick deploy:

npm install -g vercel
vercel --prod

Backend (Google Cloud Run)

The backend can be deployed to Google Cloud Run. See resume-api/CLOUDRUN_DEPLOYMENT.md for instructions.

Project Structure

ResumeAI/
├── src/                    # React frontend
│   ├── components/         # Reusable UI components
│   ├── pages/             # Page components
│   ├── hooks/             # Custom React hooks
│   ├── utils/             # Utility functions
│   ├── types.ts           # TypeScript types
│   └── App.tsx            # Main app component
├── resume-api/            # FastAPI backend
│   ├── api/               # API routes and models
│   ├── config/            # Configuration
│   ├── lib/               # CLI integration
│   ├── templates/         # Resume templates
│   ├── main.py            # FastAPI entry point
│   └── Dockerfile         # Container configuration
├── tests/                 # Frontend tests
├── docs/                  # Generated documentation
├── CLAUDE.md              # Developer documentation
└── package.json           # Node.js configuration

Contributing

1. Create a feature branch: git checkout -b feature/your-feature
2. Make your changes and commit them
3. Push to the branch: git push origin feature/your-feature
4. Create a Pull Request

See CLAUDE.md for detailed Git workflow guidelines.

Development Environment

Using Dev Container (Recommended)

ResumeAI includes a devcontainer configuration for reproducible development environments. This is the recommended way to develop as it sets up all dependencies automatically.

Prerequisites

• Docker installed and running
• Visual Studio Code installed
• Dev Containers extension installed

Setup

1. Open in VS Code: Open the project in VS Code
2. Reopen in Container: Click "Reopen in Container" when prompted (or press F1 and select "Dev Containers: Reopen in Container")
3. Wait for Setup: The container will install all dependencies automatically:
   • Node.js 20 with npm
   • Python 3.11 with pip
   • GitHub CLI
   • All required VS Code extensions

Features

The devcontainer provides:

• Debugging Configurations:

  • React frontend debugging (Chrome, Firefox)
  • FastAPI backend debugging with hot reload
  • Frontend and backend unit test debugging
  • E2E test debugging with Playwright
  • Full-stack combined debugging

• VS Code Extensions:

  • ESLint & Prettier for code quality
  • Tailwind CSS support
  • Python (Pylance, Black, Flake8, Pytest)
  • Docker support
  • GitLens for version control

• Pre-configured Settings:

  • Format on save enabled
  • ESLint auto-fix on save
  • Python testing with pytest
  • Organized imports on save

Available Debug Targets

Target	Description
React: Chrome	Debug frontend in Chrome
React: Firefox	Debug frontend in Firefox
Python: FastAPI (ResumeAPI)	Debug backend with hot reload
Python: Current File	Debug currently open Python file
Python: Pytest	Debug pytest tests
Debug Tests	Debug frontend vitest tests
Debug Current Test File	Debug current test file
E2E Tests	Run Playwright E2E tests
Full Stack Debug	Debug both frontend and backend together

Running Both Services

To run both frontend and backend:

1. Start the backend using Python: FastAPI (ResumeAPI) debug configuration
2. Start the frontend using React: Chrome debug configuration
3. Or use the Full Stack Debug compound configuration to run both at once

Ports

• 5173: Frontend (Vite dev server)
• 8000: Backend (FastAPI)

The devcontainer automatically forwards these ports and notifies you when they're available.

Manual Setup

If you prefer to develop locally without containers, follow the manual setup instructions in the Installation section above.

Troubleshooting

Dev Container (Recommended)

ResumeAI includes a devcontainer configuration for reproducible development environments:

1. Open in VS Code: Open the project in VS Code
2. Reopen in Container: Click "Reopen in Container" when prompted (or press F1 and select "Dev Containers: Reopen in Container")
3. Wait for Setup: The container will install all dependencies automatically

The devcontainer includes:

• Node.js 20 with npm
• GitHub CLI
• All required VS Code extensions (ESLint, Prettier, Python, Docker)
• Pre-configured linting and formatting on save

GitHub Connection Issues

1. Verify GitHub OAuth App credentials:

   • Check that GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are correctly set
   • Ensure your OAuth App exists at https://github.com/settings/developers

2. Check callback URL:

   • Make sure GITHUB_REDIRECT_URI in backend .env matches the authorization callback URL in your GitHub OAuth App

3. Clear browser session:

   • Clear browser cookies and localStorage
   • Try connecting again

4. Check backend logs for detailed error messages:

   docker logs <container_id>

PDF Generation Fails

Ensure LaTeX is installed:

# macOS
brew install texlive

# Ubuntu
sudo apt-get install texlive-latex-base

API Connection Issues

1. Verify the backend is running: curl http://127.0.0.1:8000/health
2. Check CORS settings in backend
3. Ensure VITE_API_URL is correct in frontend .env.local

Build Errors

# Clear node_modules and reinstall
rm -rf node_modules
npm install

# Clear cache
rm -rf dist
npm run build

CLI Authentication (Deprecated)

⚠️ DEPRECATED: The GitHub CLI authentication mode has been deprecated and will be removed in a future version. Please use OAuth instead.

If you see warnings about CLI mode:

1. Update to the latest version
2. Use OAuth for authentication
3. See the GitHub Integration section above for setup instructions

License

MIT License - See LICENSE for details.

Resources

• CLAUDE.md - Detailed developer documentation
• VERCEL_DEPLOYMENT.md - Frontend deployment guide
• API_DOCUMENTATION.md - API reference
• resume-api/README.md - Backend documentation