This project is a sophisticated, production-ready Candidate Filtering & Ranking System designed to streamline the recruitment process. Leveraging Next.js 14 and TypeScript, it automates the evaluation of candidates against Job Descriptions (JDs) using a weighted algorithm that considers hard constraints (Experience, Location, Salary) and soft semantic matching (Skills, Resume Similarity).
The system features a highly responsive "Glassmorphism" UI, real-time filtering, and a modular backend architecture that ensures scalability and maintainability.
- Frontend: React 18, Next.js 14 (App Router), Tailwind CSS (Glassmorphism Design).
- Backend: Next.js API Routes (Serverless functions).
- Language: strict TypeScript for type safety.
- Logic Layers:
jobParser.ts: NLP-based keyword extraction engine.filterEngine.ts: Hard constraint gatekeeper (with Fuzzy Location Matching).scoringEngine.ts: Multi-factor weighted scoring algorithm.similarity.ts: Vector-based Bag-of-Words Cosine Similarity model.
- Data: Local JSON dataset (Mock DB) with script-generated realistic candidates.
- Intelligent JD Parsing: Automatically extracts
Required Skills,Experience, andLocationfrom raw JD text. - Hybrid Filtering:
- Hard Filters: Strict gatekeeping for Budget, Minimum Experience, and Location (supports typos via Levenshtein Distance).
- Soft Scoring: Weighted ranking based on skill matches (Required vs Preferred) and semantic texture.
- Explainable AI (XAI): Every score of
1.00or0.85is fully transparent. The UI breaks down exactly why a candidate was ranked (e.g., "+0.20 for Experience Match", "+0.05 for Semantic Similarity"). - Performance: Optimized for speed with client-side state management and server-side processing separation.
- Node.js v18+
- npm
# Clone the repository
git clone <repo-url>
cd ranking_system
# Install dependencies
npm install
# Generate Mock Data (Optional - creates 500 candidates)
npm run dev # The script scripts/generateData.js can be run manually if needednpm run devOpen http://localhost:3000 to view the application.
The system implements a multi-stage funnel methodology:
- Stage 1 (Hard Filtering): Eliminates unqualified candidates immediately (e.g., "Must be in Bangalore", "Max Budget 20LPA"). We implemented Fuzzy Matching (Levenshtein Distance) to ensure candidates aren't rejected due to recruiter typos (e.g., "Banglore" matches "Bangalore").
- Stage 2 (Weighted Scoring): Candidates are scored on a curve. A candidate with 8/10 skills ranks higher than one with 5/10.
- Stage 3 (Normalization): Scores are normalized (0 to 1) relative to the best candidate in the pool, providing immediate context on relative quality.
The codebase follows Clean Architecture principles:
- Separation of Concerns: UI components (
/components) are strictly separated from business logic (/lib). - Type Safety: TypeScript interfaces (
types.ts) are shared across Frontend and Backend, ensuring 0 runtime data mismatches. - Modular Logic: The scoring engine, parsing logic, and similarity algorithms are isolated modules, making them testable and replaceable without affecting the UI.
- Frontend: Handles User Interaction, State Management (Filters), and Presentation. It treats the rankings as a pure data payload.
- Backend (
/api/rank): Stateless API endpoint. It accepts a Job Description + Filters + Candidate Pool and returns a sorted, scored list. This decoupling allows the backend to be easily swapped for a real database or a Python microservice in the future without touching the frontend.
Unlike "Black Box" AI models, this system prioritizes Transparency:
- The
Score Breakdownfeature in the UI explicitly lists the contribution of each factor (Skills, Experience, Salary Match, Semantic Fit). - Recruiters can see exactly which skills matched and which were missing, eliminating "trust issues" with the ranking.