Streamline your recruitment process with AI-powered candidate evaluation and ranking
The Candidate Shortlisting Application is an intelligent HR tool that leverages AI to automate and optimize the candidate evaluation process. Upload job descriptions and candidate resumes, generate custom evaluation rubrics, and let AI rank candidates based on job fit—all in one seamless workflow.
- AI-Powered Rubric Generation: Automatically create evaluation criteria tailored to each job description
- Intelligent Candidate Matching: Score and rank candidates using customizable weighted rubrics
- Multi-Format Support: Process PDF and DOCX files for both job descriptions and resumes
- Session History: Track and review past evaluations with detailed scoring breakdowns
- Group Management: Organize candidates into custom groups for easier management
- Generate up to 3 custom evaluation rubrics per job description
- Edit and fine-tune rubric weightages and criteria
- Parallel processing of multiple candidates with real-time progress tracking
- Detailed scoring with AI-generated justifications for each criterion
- Upload and manage job descriptions in PDF or DOCX format
- Automatic content parsing and extraction
- Filter and search through your job description library
- View full JD content and metadata
- Upload candidate resumes (PDF/DOCX)
- Organize candidates into custom groups
- Extract key information: name, role, company, location, experience
- Bulk selection and group-based filtering
- Review previous evaluation sessions
- View top-ranked candidates for each session
- Access detailed scoring breakdowns
- Track evaluation history with timestamps
- Clean, intuitive interface built with Shadcn UI
- Dark/Light theme support
- Interactive guided tours for first-time users
- Responsive design for all screen sizes
- Node.js 20.x or higher
- MongoDB database (MongoDB Atlas recommended)
- Lyzr API Key with access to AI agents
- Clone the repository
git clone https://github.com/amitlyzr/candidate-shortlisting-agent-os.git
cd candidate-shortlisting-agent- Install dependencies
npm install- Configure environment variables
Create a .env.local file in the root directory:
# Database Configuration
MONGODB_URI=mongodb+srv://your-mongodb-connection-string
# Lyzr AI Configuration
LYZR_CANDIDATES_AGENT_ID=your-agent-id
LYZR_EVALUATE_CANDIDATES_AGENT_ID=your-agent-id
LYZR_RUBRICS_AGENT_ID=your-agent-idTip
You can obtain your Lyzr agent IDs from the [Lyzr Studio Dashboard]
- Initialize the database
npx prisma generate
npx prisma db push- Run the development server
npm run dev- Open your browser
Navigate to http://localhost:3000 to see the application.
Navigate to the JD Library and upload your job descriptions. The system supports PDF and DOCX formats and automatically extracts relevant content.
Go to the Candidate Database and upload candidate resumes. Organize them into groups for better management (e.g., by department, skill level, or recruitment campaign).
On the Shortlist page:
- Select a job description from your library
- Click "Generate Rubrics" to create AI-powered evaluation criteria
- Review the 3 generated rubrics (Basic, Intermediate, Advanced)
- Edit weightages and criteria as needed
- Confirm your preferred rubric
- Select candidates from your database (individual or group selection)
- Click "Match & Rank Candidates" to start the evaluation
- Monitor real-time progress as AI evaluates each candidate
- Review ranked results with detailed scores and justifications
Access the Sessions page to review past evaluations, compare candidates across different rubrics, and export results for your hiring team.
- Next.js 15 - React framework with App Router
- React 19 - UI library
- TypeScript - Type-safe development
- Tailwind CSS 4 - Utility-first styling
- Shadcn UI - Component library
- Next.js API Routes - Serverless API endpoints
- Prisma - Type-safe database ORM
- MongoDB - NoSQL database
- Lyzr Agent SDK - AI agent orchestration
- Mammoth.js - DOCX file parsing
- unpdf - PDF content extraction
- NextStepJS - Interactive user onboarding
- Recharts - Data visualization
- React Hook Form + Zod - Form management and validation
- Sonner - Toast notifications
candidate-shortlisting/
├── src/
│ ├── app/
│ │ ├── (app)/ # Protected app routes
│ │ │ ├── page.tsx # Main shortlisting page
│ │ │ ├── jd-library/ # Job description management
│ │ │ ├── candidate-database/ # Candidate management
│ │ │ └── sessions/ # Session history
│ │ ├── api/ # API routes
│ │ │ ├── candidates/ # Candidate CRUD
│ │ │ ├── job-descriptions/ # JD CRUD
│ │ │ ├── generate-rubrics/ # AI rubric generation
│ │ │ └── evaluate-candidates/ # AI candidate evaluation
│ │ └── layout.tsx # Root layout
│ ├── components/
│ │ ├── ui/ # Reusable UI components
│ │ └── providers/ # Context providers
│ ├── lib/
│ │ ├── auth.ts # Authentication utilities
│ │ ├── prisma.ts # Database client
│ │ └── file-parser.ts # Document parsing
│ └── hooks/ # Custom React hooks
├── prisma/
│ └── schema.prisma # Database schema
└── public/ # Static assets
The application uses a header-based authentication system where user credentials are passed via HTTP headers. Authentication is automatically handled by the AuthProvider and authFetch utility.
All API requests must include the following headers:
x-user-id- Unique user identifierx-email- User email addressx-org-id- Organization identifierx-token- Authentication token (used as Lyzr API key)
The user's authentication token (x-token) is directly used as the API key for all Lyzr AI agent calls. This provides:
- User-specific API access: Each user's token is tied to their Lyzr account
- Usage tracking: API calls are tracked per user for billing and analytics
- Security: No shared API keys; each user has isolated access
- Simplified setup: No separate Lyzr API key configuration needed
Important
Ensure that user tokens are valid Lyzr API keys. Users must authenticate through a system that provides Lyzr-compatible tokens.
GET /api/job-descriptions- List all job descriptionsPOST /api/job-descriptions- Upload new job descriptionDELETE /api/job-descriptions?id={id}- Delete job description
GET /api/candidates- List all candidatesPOST /api/candidates- Upload new candidatePATCH /api/candidates?id={id}- Update candidate groupDELETE /api/candidates?id={id}- Delete candidate
POST /api/generate-rubrics- Generate evaluation rubricsPOST /api/evaluate-candidates- Evaluate and rank candidates
GET /api/sessions- List evaluation sessionsGET /api/sessions/{sessionId}- Get session details
npm run lintnpm run build
npm start# Generate Prisma Client
npx prisma generate
# Push schema changes
npx prisma db push
# Open Prisma Studio
npx prisma studioThis application is optimized for deployment on Vercel, but can be deployed on any platform supporting Next.js.
- Push your code to GitHub
- Import the project in Vercel
- Configure environment variables
- Deploy
Important
Ensure your MongoDB database is accessible from your deployment environment and all environment variables are properly configured.
- Upload clear, well-formatted job descriptions for better rubric generation
- Organize candidates into logical groups before evaluation
- Review and adjust rubric weightages based on your hiring priorities
- Use the session history to compare different evaluation approaches
- Keep your candidate database up-to-date by removing outdated profiles
For issues, questions, or contributions:
- Documentation: Lyzr Documentation
- GitHub Issues: Report a bug
- Email: support@lyzr.ai