README.md

AI-Powered Resume Screening System

A full-stack AI-powered application that automates resume screening using semantic search, vector embeddings, and LLM-based candidate scoring.

✨ Features

🎯 Core Features

• Resume Upload & Processing: Upload PDF/DOCX resumes with automatic text extraction
• AI-Powered Search: Semantic search using vector embeddings (not just keywords!)
• LLM Scoring: Automatic candidate scoring (1-10) with detailed reasoning
• Gmail Integration: Auto-fetch resumes from Gmail with OAuth 2.0
• Job Management: Create and manage job descriptions
• Vector Database: Store and search resumes using Pinecone

🔥 Advanced Features

• Semantic Search: Find candidates based on meaning, not just keywords
• Dual Search Modes: Search by text query or job description
• Similarity Scoring: Visual similarity scores for each candidate
• Batch Processing: Process multiple resumes from Gmail automatically
• Smart Deduplication: Prevents duplicate candidates
• Real-time Processing: Live progress indicators for all operations

🛠️ Tech Stack

Frontend

• React 18 - UI framework
• Tailwind CSS v4 - Styling
• React Router - Navigation
• Axios - HTTP client
• React Hot Toast - Notifications

Backend

• Node.js + Express - API server
• PostgreSQL - Relational database (Neon)
• Pinecone - Vector database for embeddings
• HuggingFace - AI embeddings & LLM scoring
• Gmail API - Email integration
• pdf-parse & mammoth - Document parsing

AI/ML

• Vector Embeddings - sentence-transformers/all-MiniLM-L6-v2 (768 dimensions)
• Semantic Search - Cosine similarity search
• LLM Scoring - HuggingFace Inference API
• RAG Architecture - Retrieval-Augmented Generation pattern

📋 Prerequisites

• Node.js 18+
• PostgreSQL database (or Neon account)
• Pinecone account (free tier)
• HuggingFace account (free)
• Google Cloud account (for Gmail API)

🚀 Installation

1. Clone Repository

git clone <your-repo-url>
cd ai-resume-screener

2. Backend Setup

cd backend
npm install

# Create .env file
cp .env.example .env

Configure .env:

PORT=5000
DATABASE_URL=your_neon_postgresql_url

PINECONE_API_KEY=your_pinecone_api_key
PINECONE_ENVIRONMENT=your_pinecone_environment
PINECONE_INDEX_NAME=resume-embeddings

HUGGINGFACE_API_KEY=your_huggingface_token

GMAIL_CLIENT_ID=your_google_client_id
GMAIL_CLIENT_SECRET=your_google_client_secret
GMAIL_REDIRECT_URI=http://localhost:5000/api/gmail/callback

FRONTEND_URL=http://localhost:5173

Initialize Database:

node config/setupDatabase.js

Start Backend:

npm run dev

3. Frontend Setup

cd frontend
npm install
npm run dev

Visit: http://localhost:5173

📖 Usage

1. Upload Resumes

• Navigate to Candidates page
• Click Upload Resume
• Fill candidate details and select PDF/DOCX file
• System automatically extracts text, generates embeddings, and stores in vector DB

2. Create Job Descriptions

• Go to Jobs page
• Click Create Job
• Add title, description, requirements
• Jobs are used for candidate matching and scoring

3. Search Candidates

• Search by Text: Enter requirements (e.g., "React developer with 5 years")
• Search by Job: Select a job description
• View ranked results with similarity scores
• Score candidates with AI (1-10 rating + reasoning)

4. Gmail Auto-Fetch

• Go to Search page
• Click Connect Gmail
• Authorize OAuth access
• Click Fetch Resumes from Gmail
• System automatically finds and processes resumes from emails

🏗️ Architecture

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   React     │─────▶│   Node.js    │─────▶│ PostgreSQL  │
│   Frontend  │      │   Express    │      │  (Neon)     │
└─────────────┘      └──────────────┘      └─────────────┘
                            │
                            ├──────────────▶ Pinecone (Vectors)
                            │
                            ├──────────────▶ HuggingFace (AI)
                            │
                            └──────────────▶ Gmail API

Data Flow

1. Resume Upload → Parse → Extract Text → Chunk → Generate Embeddings → Store in Pinecone + PostgreSQL
2. Search → Generate Query Embedding → Vector Similarity Search → Rank Results → Return Candidates
3. Scoring → Retrieve Resume + JD → Send to LLM → Parse Score + Reasoning → Store in DB

📊 Database Schema

candidates
  ├── id, name, email, phone
  ├── resume_text, resume_url
  └── created_at

job_descriptions
  ├── id, title, description
  ├── requirements, department
  └── status

applications (links candidates to jobs)
  ├── candidate_id, jd_id
  └── status

scores (AI scoring results)
  ├── application_id, score (1-10)
  └── reasoning

resume_chunks (for vector search)
  ├── candidate_id, chunk_text
  └── chunk_index, metadata

🎯 Key Features Explained

Semantic Search

• Converts resumes to 768-dimensional vectors
• Uses cosine similarity to find best matches
• Understands context, not just keywords
• Example: "JavaScript expert" matches "React developer"

AI Scoring

• LLM analyzes resume against job requirements
• Provides 1-10 score with detailed reasoning
• Fallback to keyword matching if LLM fails
• Considers skills, experience, education, potential

Gmail Integration

• Searches: has:attachment filename:(pdf OR docx) (resume OR cv)
• Extracts candidate info from email sender
• Auto-processes and adds to database
• Prevents duplicates by email

🔐 Security

• OAuth 2.0 for Gmail
• Environment variables for secrets
• Input validation on all endpoints
• CORS enabled for frontend
• File type validation (PDF/DOCX only)
• SQL injection protection (parameterized queries)

🚧 Future Enhancements

• User authentication (JWT)
• Role-based access control
• Advanced analytics dashboard
• Interview scheduling
• Email notifications
• Scheduled Gmail auto-fetch (cron job)
• Candidate comparison tool
• Export to CSV/Excel
• Multi-language support

📝 License

MIT License - feel free to use for your projects!

🙏 Acknowledgments

• HuggingFace for AI models
• Pinecone for vector database
• Neon for PostgreSQL hosting
• Google for Gmail API"# -AI-Powered-Resume-Screening-System"