HireLens AI — Backend

FastAPI backend powering HireLens AI — AI-powered resume screening, TF-IDF similarity scoring, and candidate ranking.

Live API: https://hirelens-backend-s2sg.onrender.com
Frontend Repo: hirelens-ai
API Docs: https://hirelens-backend-s2sg.onrender.com/docs

---

What It Does

Receives resumes (PDF/DOCX) and a job description, extracts text, performs TF-IDF similarity scoring, detects missing skills, and returns a ranked list of candidates with explainable scores.

---

API Endpoints

Method	Endpoint	Description
GET	/	Health check
POST	/screen	Screen and rank candidates

POST /screen

Request — multipart/form-data:

• resumes — one or more PDF/DOCX files
• job_description — string

Response:

{
  "candidates": [
    {
      "name": "John Smith",
      "score": 0.87,
      "matched_skills": ["python", "fastapi", "postgresql"],
      "missing_skills": ["docker", "kubernetes"],
      "explanation": "Strong match — 87% similarity. Notable gaps: docker, kubernetes."
    }
  ],
  "total": 1
}

---

Tech Stack

Layer	Technology
Framework	FastAPI
Language	Python 3.11
Scoring	TF-IDF Vectorization
Similarity	Cosine similarity via scikit-learn
Resume Parsing	pdfplumber + python-docx
Deployment	Render

---

Run Locally

# 1. Clone the repo
git clone https://github.com/Yusufcommit/hirelens-backend.git
cd hirelens-backend

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

# 3. Install dependencies
pip install -r requirements.txt

# 4. Start the server
uvicorn main:app --reload

API runs at http://localhost:8000
Swagger docs at http://localhost:8000/docs

---

Project Structure

hirelens-backend/
├── main.py            # FastAPI app, routes, scoring logic
├── requirements.txt
├── .python-version
├── .gitignore
└── README.md

---

How The Scoring Works

Resume (PDF/DOCX)
      │
      ▼
Text Extraction (pdfplumber / python-docx)
      │
      ▼
TF-IDF Vectorization
      │
      ▼
Cosine Similarity vs Job Description
      │
      ▼
Skill Extraction + Gap Analysis
      │
      ▼
Ranked Candidates + Explanations

---

Roadmap

• PDF and DOCX resume parsing
• TF-IDF similarity scoring
• Skill extraction and gap detection
• Score explainability
• Multi-resume batch processing
• Production deployment on Render
• PostgreSQL integration for session storage
• Authentication with JWT
• Docker + CI/CD pipeline
• Bias detection layer
• API versioning (/v1/screen)
• Upgrade to transformer-based embeddings on better infrastructure

---

Related

• Frontend: hirelens-ai
• Original prototype: ai-resume-screening-system

---

Built by Yusuf

Yusuf Abdirashid — AI Full Stack Developer
Building polished AI-powered tools for hiring and job applications.