This project is a full-stack application designed to help a solo founder hire a diverse team of 5 people from a large pool of applicants. The application provides tools to filter, rank, and manage candidates, making the hiring process more efficient and data-driven.
This README outlines the application's architecture, features, setup instructions, and potential future improvements.
The application follows a decoupled frontend/backend architecture, which allows for independent development and scaling of the two components.
- Frontend: A responsive web interface built with React and TypeScript, using Bootstrap for styling. It provides a user-friendly dashboard for interacting with the candidate data.
- Backend: A high-performance REST API built with FastAPI (Python). It handles data processing, filtering, and serves the data to the frontend.
- Database: A SQLite database (
recruitment.db) is used to store and manage the candidate data. This provides a significant performance improvement over reading from a JSON file on every request.
+-----------------+ +-----------------+ +-----------------+
| React App |----->| FastAPI |----->| SQLite DB |
| (Filters, Views)| | (REST API) | | (recruitment.db)|
+-----------------+ +-----------------+ +-----------------+
^
| (one-time)
+-----------------+
| seed.py |
| (Data Ingestion)|
+-----------------+
^
|
+-----------------+
| form-submissions|
| .json |
+-----------------+
- Data Ingestion: A one-time script (
backend/app/seed.py) reads the raw applicant data fromform-submissions.json. - Data Cleaning & Transformation: The script cleans the data (e.g., normalizes salary formats, standardizes location names) and loads it into the SQLite database.
- API Interaction: The React frontend makes API calls to the FastAPI backend to fetch and filter candidate data.
- Database Query: The FastAPI backend queries the SQLite database to retrieve the requested data and returns it to the frontend.
- Advanced Filtering: A comprehensive filtering system that allows the user to search for candidates based on various criteria, including:
- Name, email, or phone number
- Skills, Role, Company, Course (multi-select)
- Minimum experience, work availability, max salary
- Highest degree, location, and top university rankings (Top 25/50).
- Dynamic UI: The filter interface is designed to be user-friendly and dynamically adjusts to prevent clutter.
- Candidate Profiles: A card-based view of candidates, showing their key information at a glance.
To evolve this application from a simple filter tool to a powerful hiring platform, the following features are proposed:
-
Candidate Scoring & Ranking:
- Concept: Automatically score and rank candidates based on a set of predefined criteria (e.g., years of experience, skill relevance, education level). This would help the hiring manager quickly identify the most promising candidates.
- Implementation: The backend would calculate a
scorefor each candidate based on a weighted average of their attributes. The frontend would then display this score and allow sorting by rank.
-
Hiring Pipeline Management:
- Concept: A Kanban-style board to manage the hiring pipeline. Candidates could be moved through different stages (e.g., "Applied", "Shortlisted", "Interviewing", "Offered", "Hired").
- Implementation: The database would be updated to include a
statusfield for each candidate. The frontend would feature a drag-and-drop interface to update the candidate's status.
-
Diversity & Inclusion Dashboard:
- Concept: To help build a diverse team, this dashboard would provide visualizations of the applicant pool's diversity across various dimensions (e.g., location, educational background, previous companies).
- Implementation: The backend would provide aggregated data, and the frontend would use a charting library (like Chart.js or D3.js) to create interactive charts and graphs.
-
Candidate Comparison View:
- Concept: A side-by-side view to compare the profiles of two or more candidates. This would make it easier to make fine-grained decisions between top contenders.
- Implementation: The frontend would allow the user to select multiple candidates and display their information in a structured, comparable format.
-
Notes & Collaboration:
- Concept: A feature to add notes and comments to a candidate's profile. This would be useful for keeping track of interview feedback and other thoughts.
- Implementation: A new
notestable in the database, linked to thesubmissionstable. The frontend would provide a text area to add and view notes on each candidate card.
- Node.js and npm
- Python 3.8+
-
Backend:
cd backend pip install -r requirements.txt python app/seed.py # To populate the database uvicorn app.main:app --reload
-
Frontend:
cd frontend npm install npm start
GET /submissions: Fetches a list of candidates. Supports all the filtering parameters mentioned above.GET /skills,/roles,/companies,/courses,/locations: Fetches a list of unique values for the filter dropdowns.
The total score is a sum of three components: Experience, Skills, and Education.
The experience score is designed to value the quality and seniority of a candidate's work history, not just the quantity of jobs they've had.
-
Role Standardization: First, each role name from a candidate's work experience is standardized. For example, "Senior Software Engineer" and "Lead Developer" are both mapped to a standardized role like
senior_individual_contributor. -
Role Scoring: Each standardized role is assigned a point value based on a predefined hierarchy:
- Executive Level (e.g., CTO, CEO): 10 points
- Senior Management (e.g., VP, Director): 8 points
- Middle Management (e.g., Engineering Manager, Project Manager): 6 points
- Senior Individual Contributor (e.g., Senior Engineer, Scientist, Tech Lead): 5 points
- Junior Management: 4 points
- Junior Individual Contributor (e.g., Software Engineer, Full Stack Developer): 3 points
- Intern: 1 point
-
Calculation: The system sums the points for every role in a candidate's work history. For instance, a candidate with one "Project Manager" role (6 points) and two "Software Engineer" roles (3 points each) would have an experience score of
6 + 3 + 3 = 12. -
Cap: This total is capped at a maximum of 45 points.
This score is straightforward and is only applied when you are actively filtering by skills.
- Matching: The system counts how many of the candidate's listed skills match the skills you have selected in the "Skills" filter.
- Calculation: Each match is worth 5 points.
- Cap: The total score for skills is capped at 25 points (so, a maximum of 5 matching skills will be counted).
This is the most detailed calculation, with several factors contributing to the score for each degree a candidate has.
For each degree, the score is calculated as follows:
-
Base Score Calculation:
- Subject Score: The degree's subject is scored based on its relevance, with the score divided by 2. For example:
- Computer Science: 5 points
- Engineering: 4 points
- Mathematics: 3.5 points
- Degree Level Score: The level of the degree is scored and weighted (multiplied by 1.5):
- Doctorate: 6 points
- Master's Degree: 4.5 points
- Bachelor's Degree: 3 points
- Associate's Degree: 1.5 points
- GPA Score: A high GPA in a top-tier degree (Master's or Doctorate) provides a small bonus:
- GPA 4.0: 3 points
- GPA 3.5+: 2 points
- The initial score for the degree is the sum of the Subject Score, Degree Level Score, and GPA Score.
- Subject Score: The degree's subject is scored based on its relevance, with the score divided by 2. For example:
-
University Tier Bonus: This initial score is then multiplied by a bonus if the university is highly ranked:
- Top 25 University: The score for that degree is multiplied by 1.5 (a 50% bonus).
- Top 50 University: The score for that degree is multiplied by 1.25 (a 25% bonus).
- A high GPA (3.5+) at a Top 25 or Top 50 school gets an additional 2-point bonus.
-
Diminishing Returns for Multiple Degrees: To reward diverse educational backgrounds, the system applies a diminishing return for multiple degrees of the same type.
- The first degree of a certain level (e.g., a candidate's first Bachelor's) receives 100% of its calculated score.
- A second degree of the same level (e.g., a second Bachelor's) receives 35% of its calculated score.
- Any subsequent degree of the same level receives 10% of its calculated score.
-
Final Calculation: The final scores for each degree are summed up, and this total is capped at a maximum of 30 points.
The candidate's final score is the sum of the capped scores from these three categories: Experience + Skills + Education.
This application can be used to strategically select a diverse and high-performing team. Here’s a suggested workflow:
- Define Core Roles: Identify the 3-4 essential roles for your founding team (e.g., Lead Engineer, Product Manager, UI/UX Designer).
- Initial Filtering: Use the filters to narrow down the applicant pool for each role. Focus on key skills, experience, and availability.
- Scoring & Ranking: Use the (proposed) scoring feature to rank the filtered candidates and identify the top 5-10 for each role.
- Diversity Check: Use the (proposed) diversity dashboard to ensure your shortlist is balanced. If it's not, adjust your filters or scoring criteria to surface a more diverse set of candidates.
- In-depth Review & Comparison: Use the candidate comparison view to do a deep dive on the top candidates. Add notes and feedback during this stage.
- Final Selection: Based on the data and your intuition, move your final 5 candidates to the "Hired" stage in the pipeline management board.
By following this data-driven approach, you can ensure you're making informed, unbiased hiring decisions and building the best possible team.