SmartRecruit: Intelligent Recruitment System with Explainable Candidate Scoring
Client
Mousam Yadav
Year
2025
Tech stack
Python, FastAPI, SQLAlchemy, PostgreSQL, Alembic, JWT, scikit-learn, XGBoost, SVM, SHAP, imbalanced-learn (SMOTE), pandas, NumPy, Jupyter Notebook, React 18, Vite, Recharts, CSS Modules, Axios
About
SmartRecruit is a web based hiring tool that scores every job applicant with a machine learning model and explains the score in plain terms. People apply online, and HR teams get a ranked list of candidates with the reasons behind each fit score, so decisions stay fast and fair.
The Problem
Hiring teams get more applications than they can read properly. Sorting through them by hand takes days, and two recruiters looking at the same CV often reach different conclusions. Many companies try to fix this with scoring tools, but most of those tools act like a black box. They hand over a number with no explanation, so recruiters cannot tell if the score is sensible or if it is quietly biased. That makes the tool hard to trust and hard to defend if a candidate ever asks why they were turned down. The gap is a screening system that is both quick and open about its reasoning.
What I Built
I built a full recruitment platform that takes an applicant from the moment they apply to the final hire or no hire decision, with a machine learning model doing the first pass of screening. Every candidate gets a fit score out of 100, and next to that score the system lists the specific factors that pushed it up or down. There is a public application page for candidates, a dashboard for HR managers to post jobs and review people, and an admin area to manage staff accounts. The model was trained and compared in a Jupyter notebook using the IBM HR Analytics dataset, and the best performing model is served live through the backend API.
Key Features
Public job application page that candidates fill in without needing an account
Machine learning fit score from 0 to 100 calculated the moment an application is submitted
Plain language explanation for each score using SHAP, showing which details helped or hurt
Job vacancy management where HR managers create, edit, and close openings
Candidate pipeline with clear stages: received, shortlisted, interview, rejected, hired, not hired
Colour coded fit badges (high, medium, low) so strong applicants stand out at a glance
Role based access with separate views for Admin, HR Manager, and Recruiter
Admin user management to create accounts, change roles, and activate or deactivate staff
Audit log that records who did what and when across jobs, candidates, and users
Standalone prediction endpoint so a profile can be scored on its own without saving it
Project Details
What it needs
The system runs on Python 3.11+, Node.js 20+, and a local PostgreSQL database. The machine learning side needs its own set of Python packages and a one time notebook run that trains the model and saves the model files. Once the database is migrated, the admin user is seeded, and the model files exist, the backend and frontend start with a single command each.
How it works through the main features
The flow starts with a job vacancy. An HR Manager logs in and creates an opening with the title, department, location, required education, skills, salary range, and other details. Open jobs are the only ones that show up on the public side.
A candidate then visits the public application page and fills in a form. This is open to anyone, no login required. The form collects the usual contact details plus the profile fields the model needs, things like total years of experience, number of companies worked at, education level, monthly income expectation, job satisfaction, and work life balance. When they hit submit, the application is saved and linked to that job.
Straight after saving, the backend runs the machine learning prediction. The applicant's answers are mapped to the format the model expects, categories are one hot encoded, numeric fields are scaled, and the model returns a probability. That probability becomes the fit score out of 100. If the model files are missing for some reason, the application is still saved so no one is blocked.
The system does not stop at a number. It also calculates SHAP values for that single prediction, which measure how much each input moved the score away from the average. The top ten factors are stored and shown to the recruiter, for example "high total working years raised this score" or "frequent job changes lowered it". This is what makes the screening explainable rather than a guess.
HR Managers and Recruiters see all of this in the candidate dashboard. Candidates for a job appear in a table with their fit badge, and clicking one opens a full profile with the score breakdown and a small chart of the SHAP factors. From there a Recruiter moves the candidate through the pipeline stages, and an HR Manager records the final hire or not hire decision, which is timestamped and attributed to them.
Running alongside everything, the admin area lets an administrator create HR Manager and Recruiter accounts, switch someone's role, or disable an account. Every meaningful action across the app is written to an audit log, so there is a record of who created a job, who scored a candidate, and who made the call.
Summary
SmartRecruit is a working example of putting a machine learning model into a real product responsibly. It handles the whole hiring loop, applying, screening, shortlisting, and deciding, and at each screening step it is honest about how it reached its answer. The result is a tool a recruiter can actually lean on, because they can see the reasoning and overrule it when their judgement says otherwise.
Screenshots
The Result
The finished system scores a new applicant in seconds and presents both the score and its reasons in one view, which removes the slow first read of every CV and gives every candidate the same yardstick. In model testing the chosen SVM model reached an F1 score of about 0.69 and an AUC of about 0.75 on held out data, trained on 21 pre-hire features with class imbalance handled by SMOTE and results checked with 5 fold cross validation. More importantly, because every prediction ships with a SHAP explanation, HR staff can sanity check the model, spot a factor that looks unfair, and make the final decision themselves. It shows that automated screening and transparency can sit in the same tool.