🚀 AI Resume Screening & Job Ranking Platform

A full-stack web application that uses AI to automatically screen resumes, match candidates to jobs, and rank applicants based on their fit.

🎯 Features

For Candidates:

• Browse active job postings
• Submit resume (PDF) with application
• Automatic AI resume analysis
• Instant application confirmation

For Recruiters:

• Secure authentication system
• Create and manage job postings
• View AI-ranked applications by match score
• Detailed candidate analysis with:
  • Match score (0-100%)
  • AI-generated feedback
  • Skill matching analysis
  • Skill gap identification
• Update application statuses

🛠️ Tech Stack

• Frontend: React + Vite
• Backend: Python + FastAPI
• Database: MongoDB
• AI: OpenRouter API (Free tier)
• Styling: Tailwind CSS

---

📦 Installation Guide

Prerequisites

• Python 3.8+
• Node.js 16+
• MongoDB (local or cloud)
• OpenRouter API key (free at https://openrouter.ai)

---

🔧 Backend Setup

Step 1: Navigate to Backend Directory

cd backend

Step 2: Create Virtual Environment

# Windows
python -m venv venv
venv\Scripts\activate

# Mac/Linux
python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Configure Environment Variables

Create a .env file in the backend directory:

# MongoDB Configuration
MONGODB_URL=mongodb://localhost:27017
DATABASE_NAME=ai_resume_screening

# OpenRouter API (Get free key from https://openrouter.ai)
OPENROUTER_API_KEY=your_api_key_here
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

# JWT Secret (Change this!)
JWT_SECRET_KEY=your_super_secret_key_here_change_this
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440

# CORS
FRONTEND_URL=http://localhost:5173

# Server
BACKEND_PORT=8000

Step 5: Start MongoDB

# If using local MongoDB
mongod

# Or use MongoDB Atlas (cloud) and update MONGODB_URL in .env

Step 6: Run Backend Server

cd app
python main.py

# Or use uvicorn directly
uvicorn app.main:app --reload --port 8000

Backend will run at: http://localhost:8000 API Docs at: http://localhost:8000/docs

---

🎨 Frontend Setup

Step 1: Navigate to Frontend Directory

cd frontend

Step 2: Install Dependencies

npm install

Step 3: Install Tailwind CSS

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Step 4: Start Development Server

npm run dev

Frontend will run at: http://localhost:5173

---

🚀 Getting Your OpenRouter API Key

1. Visit https://openrouter.ai
2. Sign up for a free account
3. Go to Keys section
4. Create a new API key
5. Copy and paste it into your .env file

Free tier includes:

• Meta-Llama-3.2-3B-Instruct (used in this project)
• No credit card required
• Generous free tier limits

---

📝 Usage Guide

For Candidates:

1. Browse Jobs

   • Open http://localhost:5173
   • View all active job postings
   • Click on any job to view details

2. Apply for a Job

   • Click "Apply Now" on any job
   • Fill in your name and email
   • Upload your resume (PDF only, max 5MB)
   • Submit application
   • AI will automatically analyze your resume!

For Recruiters:

1. Register/Login

   • Click "Recruiter Login" button
   • Create an account or sign in
   • You'll be redirected to the dashboard

2. Create a Job

   • Click "Create New Job" button
   • Fill in job details
   • Add required skills
   • Submit to make it live

3. Review Applications

   • Click on any job in your dashboard
   • View AI-ranked applications (highest match first)
   • Click on an application to see:
     • AI match score
     • Detailed feedback
     • Matching skills
     • Skill gaps
   • Update application status

---

🔄 How It Works

Application Flow:

1. Candidate Submits Resume

   • PDF is uploaded
   • Text is extracted using PyPDF2

2. AI Processing

   • Skills are extracted from resume
   • Semantic similarity calculated (TF-IDF)
   • Skill matching performed
   • Match score computed (60% semantic + 40% skills)

3. AI Feedback Generation

   • OpenRouter API analyzes fit
   • Generates personalized feedback
   • Identifies strengths and gaps

4. Recruiter Dashboard

   • Applications automatically ranked
   • Highest scoring candidates appear first
   • Real-time updates as new applications arrive

---

🗂️ Project Structure

ai-resume-screening/
│
├── backend/
│   ├── app/
│   │   ├── models/          # Data models
│   │   ├── routes/          # API endpoints
│   │   ├── services/        # Business logic
│   │   ├── config.py        # Configuration
│   │   ├── database.py      # MongoDB connection
│   │   └── main.py          # FastAPI app
│   ├── requirements.txt
│   └── .env
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── candidate/   # Candidate UI
│   │   │   └── recruiter/   # Recruiter UI
│   │   ├── services/        # API calls
│   │   ├── App.jsx          # Main component
│   │   └── main.jsx         # Entry point
│   ├── package.json
│   └── vite.config.js
│
└── README.md

---

🧪 Testing the Application

Test Candidate Flow:

1. Start both servers
2. Browse jobs at http://localhost:5173
3. Upload a sample resume PDF
4. Check application confirmation

Test Recruiter Flow:

1. Register as recruiter
2. Create a test job with skills like "Python, React, MongoDB"
3. Apply as candidate with matching resume
4. Check recruiter dashboard for ranked applications
5. View detailed AI analysis

---

🐛 Troubleshooting

MongoDB Connection Issues:

# Check if MongoDB is running
mongosh

# If not, start it
mongod

Port Already in Use:

# Backend
# Change BACKEND_PORT in .env

# Frontend
# Change port in vite.config.js

API Key Issues:

• Verify your OpenRouter API key is correct
• Check you have free tier credits remaining
• Ensure OPENROUTER_API_KEY is set in .env

PDF Upload Errors:

• Ensure PDF is valid and under 5MB
• Check PyPDF2 is installed correctly
• Verify file permissions

---

🌟 Key Features Explained

AI Matching Algorithm:

• Semantic Similarity (60%): Compares overall resume content to job description
• Skill Matching (40%): Matches specific required skills
• Final Score: Weighted average of both metrics

Resume Parsing:

• Extracts text from PDF
• Identifies 100+ technical skills
• Extracts email and phone (optional use)

Ranking System:

• Real-time ranking updates
• Automatic sorting by match score
• No manual intervention required

---

📚 API Endpoints

Public Endpoints:

• GET /api/jobs/ - Get all active jobs
• GET /api/jobs/{job_id} - Get job details
• POST /api/applications/ - Submit application

Recruiter Endpoints (Auth Required):

• POST /api/recruiters/register - Register
• POST /api/recruiters/login - Login
• GET /api/recruiters/me - Get profile
• POST /api/jobs/ - Create job
• GET /api/jobs/my-jobs - Get recruiter's jobs
• GET /api/applications/job/{job_id} - Get ranked applications

---

🔐 Security Notes

• JWT tokens expire after 24 hours
• Passwords are hashed with bcrypt
• CORS properly configured
• Input validation on all endpoints

---

💡 Future Enhancements

• Email notifications
• Interview scheduling
• Advanced analytics dashboard
• Resume download functionality
• Batch application processing
• Video interview integration

---

📄 License

This project is open source and available for educational purposes.

---

🤝 Contributing

Feel free to fork, improve, and create pull requests!

---

📧 Support

For issues or questions, please create an issue in the repository.

---

Built with ❤️ using React, FastAPI, MongoDB, and OpenRouter AI