CV Analyzer

A full-stack application that matches candidate CVs (PDF or TXT) to job vacancy descriptions using LLM-powered summaries and ratings.

Application Overview

Backend: Spring Boot REST API with OpenAI integration
Frontend: React web application with modern UI
Features: CV analysis, candidate matching, and rating system

Features

Backend Features

Upload CVs as .pdf or .txt files to backend/src/main/resources/cvs/
REST API to find the best-matching candidates for a job description
Uses OpenAI (or compatible) LLM to generate fit summaries and ratings
Externalized prompt templates with System/User roles for robust, tunable inference
Simplified error handling with user-friendly messages
Proper AI service error classification (rate limits, authentication, etc.)
Clean validation error messages without technical details
GenAI metrics exposed via Spring Boot Actuator endpoints for LLM usage monitoring
Real-time cost tracking with actual token usage via Aspect-Oriented Programming (AOP)
Configurable OpenAI pricing with automatic cost calculation
Health monitoring and system metrics via Spring Boot Actuator
Admin-only prompt management with secure REST API endpoints

Frontend Features

Modern React web interface with Chakra UI components
Responsive sidebar navigation with collapsible menu
Dark/Light theme toggle with persistent user preference
Upload and manage CV files
Submit job descriptions for candidate matching
Visual candidate ratings with circular progress gauges
Candidate sorting from best match to worst
Enhanced error handling with user-friendly messages
Real-time Health & Metrics dashboard with auto-refresh
GenAI cost tracking and token usage visualization
System health monitoring with detailed component status
Drag & Drop Health Cards: Customizable metric card layout with persistent user preferences
Admin Panel with tabbed interface for system and prompt management
Secure prompt management with view, edit, reset, and refresh capabilities
Responsive design for desktop, tablet, and mobile

Prerequisites

Option 1: Local Development

Java 17+
Maven 3.8+
Node.js 18+ (for frontend)
An OpenAI API key (or compatible endpoint)

Option 2: Docker (Recommended)

Docker
Docker Compose
An OpenAI API key (or compatible endpoint)

Setup

Clone the repository

git clone <your-repo-url>
cd cv-analyzer

Add your OpenAI API key

Create a .env file in the project root:

OPENAI_API_KEY=sk-...your-key...

Optional: Configure OpenAI pricing (defaults to GPT-4o pricing)

OPENAI_PRICING_INPUT=0.1
OPENAI_PRICING_OUTPUT=0.4
OPENAI_PRICING_CURRENCY=USD

Add candidate CVs

Place .pdf and/or .txt files in:

backend/src/main/resources/cvs/

Each file should represent one candidate's resume.

Running the Application

Option 1: Using Docker (Recommended)

The easiest way to run the application is using Docker Compose:

# Start all services
docker-compose up -d

# Or use the management script
./docker-scripts.sh start

The application will be available at:

Frontend: http://localhost:3000
Backend API: http://localhost:8080
Health & Metrics Dashboard: http://localhost:3000/health
Admin Panel: http://localhost:3000/admin

Other useful Docker commands:

# Check service status
./docker-scripts.sh status

# View logs
./docker-scripts.sh logs

# Stop services
./docker-scripts.sh stop

# Development mode with hot reloading
./docker-scripts.sh dev

Selecting an AI profile (OpenAI vs Groq)

The backend supports multiple Spring profiles to switch AI providers:

main (default) – OpenAI-compatible settings from application.properties
groq – Uses application-groq.properties (Groq's OpenAI-compatible endpoint)
dev – Development profile used by docker-compose.dev.yml

Use any of the following methods to select a profile:

With the management script:

# OpenAI (default)
./docker-scripts.sh start

# Explicit OpenAI
./docker-scripts.sh start main

# Groq profile
./docker-scripts.sh start groq

# Development with Groq
./docker-scripts.sh dev groq

With Docker Compose directly:

# Production stack with Groq
SPRING_PROFILES_ACTIVE=groq docker-compose up -d

# Development stack with Groq (overrides default dev)
SPRING_PROFILES_ACTIVE=groq docker-compose -f docker-compose.dev.yml up --build

Running locally (without Docker):

cd backend
./mvnw spring-boot:run -Dspring-boot.run.profiles=groq

Notes:

Set OPENAI_API_KEY to your Groq API key when using the groq profile.
Groq profile uses base URL https://api.groq.com/openai and model gemma2-9b-it by default.

Option 2: Local Development

If you prefer to run the services locally:

Backend:

cd backend
./mvnw clean package
./mvnw spring-boot:run

Frontend:

cd frontend
npm install
npm start

The backend will start on http://localhost:8080 and the frontend on http://localhost:3000.

Project Structure

cv-analyzer/
├── backend/                 # Spring Boot application
│   ├── src/main/java/      # Java source code
│   │   ├── aspect/         # AOP aspects for cross-cutting concerns
│   │   ├── config/         # Spring configuration classes
│   │   ├── controller/     # REST controllers
│   │   ├── dto/           # Data Transfer Objects
│   │   ├── exception/     # Custom exception classes
│   │   ├── model/         # Domain models and internal data structures
│   │   └── service/       # Business logic services
│   ├── src/main/resources/ # Configuration and resources
│   │   ├── cvs/           # CV files directory
│   │   ├── prompts/       # AI prompt templates
│   │   └── application.properties # Application configuration
│   └── Dockerfile         # Backend Docker configuration
├── frontend/               # React application
│   ├── src/               # React source code
│   │   ├── components/    # Reusable UI components
│   │   ├── pages/         # Page components
│   │   └── App.js         # Main application component
│   ├── public/            # Static assets
│   └── Dockerfile         # Frontend Docker configuration
├── docker-compose.yml     # Production Docker setup
├── docker-compose.dev.yml # Development Docker setup
├── docker-scripts.sh      # Docker management script
└── .env                   # Environment variables

API Usage

Match Candidates Endpoint

POST /api/candidate-matcher/match

Request Body:

{
  "vacancyDescription": "Looking for a Java developer with Spring Boot and PDF processing experience."
}

Response:

[
  {
    "name": "John Doe",
    "filename": "john_doe.pdf",
    "summary": "John has extensive experience in Java and Spring Boot, as well as hands-on PDF processing. This makes him an excellent fit for the role described.",
    "rating": 85,
    "minRating": 1,
    "maxRating": 100
  },
  ...
]

Example cURL

curl -X POST http://localhost:8080/api/candidate-matcher/match \
  -H "Content-Type: application/json" \
  -d '{"vacancyDescription": "Looking for a Java developer with Spring Boot and PDF processing experience."}'

Error Handling Examples

The API now provides clean, user-friendly error messages:

Validation Error (Short Description):

{
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed: Vacancy description must be between 10 and 10000 characters"
}

Rate Limit Error:

{
  "status": 429,
  "error": "Too Many Requests",
  "message": "AI service rate limit exceeded. Please try again later."
}

Authentication Error:

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid API key. Please check your configuration."
}

Cost Metrics Endpoint

GET /api/cost/metrics

Response:

{
  "totalCost": 0.0045,
  "totalInputTokens": 1360,
  "totalOutputTokens": 114,
  "pricing": {
    "inputTokensPerMillion": 0.1,
    "outputTokensPerMillion": 0.4,
    "currency": "USD"
  }
}

Pricing Information Endpoint

GET /api/cost/pricing

Response:

{
  "inputTokensPerMillion": 0.1,
  "outputTokensPerMillion": 0.4,
  "currency": "USD"
}