🏗️ Talent Matcher Agent

AI-powered system for automatically matching rejected candidates to alternative open positions.

🎯 Overview

When a candidate is rejected for a position, this system automatically:

Parses their CV using Gemini AI
Generates embeddings for skills, experience, and overall profile
Searches for similar open positions using pgvector
Consolidates and ranks matches
Generates a detailed analysis memo for recruiters

🚀 Tech Stack

Frontend: Next.js 14 (App Router), TypeScript, Tailwind CSS
Backend: Next.js API Routes, BullMQ workers
Database: Supabase (PostgreSQL + pgvector)
AI: Google Gemini 2.0 (CV parsing, embeddings, analysis)
Workflow: LangGraph (parallel execution orchestration)
Queue: BullMQ + Redis (background job processing)

📋 Prerequisites

Node.js 18+ and npm
Docker (for Redis)
Supabase account
Google Gemini API key

🛠️ Setup

1. Install Dependencies

npm install

2. Setup Supabase

Create a new project at supabase.com
Run the migration from supabase-migration.sql in the SQL Editor
Note your Project URL, anon key, and service_role key

3. Configure Environment Variables

Copy .env.example to .env.local:

cp .env.example .env.local

Fill in your credentials:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Gemini
GEMINI_API_KEY=your-gemini-api-key

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=development

4. Start Redis

docker-compose up -d

5. Start Development Services

Quick Start (Recommended):

npm run dev:concurrent  # Starts all services at once with color-coded output

Individual Services:

# Terminal 1: Next.js server
npm run dev

# Terminal 2: Workflow worker
npm run worker:workflow

# Terminal 3: Job indexing worker
npm run worker:indexing

Visit http://localhost:3000

6. Setup Claude Code Infrastructure (Optional but Recommended)

The project includes comprehensive Claude Code development tools:

# Initialize project management
/pm:init

# List available commands
/pm:help

# Show current development status
/pm:status

For detailed setup, see the Developer Guide.

📡 API Endpoints

Reject Candidate & Trigger Matching

POST /api/candidates/reject
Content-Type: application/json

{
  "candidate_id": "uuid",
  "application_id": "uuid",
  "rejection_reason": "Not enough experience" 
}

Check Workflow Status

GET /api/workflow/status/[workflow_execution_id]

Index Jobs for Vector Search

POST /api/jobs/index
Content-Type: application/json

{
  "company_id": "uuid",
  "job_ids": ["uuid1", "uuid2"] // optional, indexes all active jobs if omitted
}

🔄 Workflow Architecture

The matching workflow uses LangGraph for orchestration:

START
  ↓
Parse CV (Gemini)
  ↓
  ├── Retrieve by Skills (parallel)
  ├── Retrieve by Experience (parallel)
  └── Retrieve by Profile (parallel)
  ↓
Consolidate Matches (weighted scoring)
  ↓
Generate Analysis (Gemini)
  ↓
END

Key Features:

Parallel Execution: Skills, experience, and profile searches run simultaneously
Weighted Scoring: Skills (40%), Experience (35%), Profile (25%)
Multi-source Boost: Jobs matching multiple criteria get a 5% boost per source
Graceful Degradation: Workflow continues even if some retrievers fail

📊 Database Schema

Key tables:

companies - Company information
jobs - Job postings
job_embeddings - Vector embeddings for semantic search
candidates - Candidate profiles
parsed_cvs - Structured CV data
applications - Job applications
workflow_executions - LangGraph workflow runs
match_results - Matched jobs with scores

🤖 Claude Code Development Infrastructure

This project includes a comprehensive Claude Code development ecosystem with specialized agents and tools.

Key Features

9 Specialized Agents: Code analysis, testing, documentation, design review, and more
50+ Project Management Commands: Epic/issue tracking, PRD management, workflow automation
Automated Testing: Comprehensive test execution with real services (no mocking)
Smart Documentation: Auto-generated and updated documentation
Epic-Based Development: Organize work around large features rather than individual issues

Quick Commands

# Project Management
/pm:init                    # Initialize new epic
/pm:status                 # Show current work status
/pm:next                   # Get next task
/pm:standup                # Generate standup report

# Development Workflow
/review                    # Code review mode
/testing:run               # Run tests with analysis
/commit                    # Smart commit with validation
/prompt <task>             # Get AI assistance

# Get Help
/pm:help                   # List all available commands

Agent Coordination

For complex tasks, agents work together automatically:

# Example: Add new feature
Task agent_type="workflow-orchestrator" description="Add user authentication"

This will coordinate multiple agents to:

Analyze requirements
Create implementation plan
Build the feature
Write tests
Update documentation
Perform code review

For complete documentation, see the Developer Guide.

🧪 Testing

Automated Testing with Claude Code

Use the specialized test-runner agent for comprehensive testing:

# Run all tests with analysis
Task agent_type="test-runner" description="Run full test suite"

# Test specific functionality
Task agent_type="test-runner" description="Test authentication endpoints"

Manual Testing

To test the workflow manually:

First, index some jobs:

curl -X POST http://localhost:3000/api/jobs/index
  -H "Content-Type: application/json"
  -d '{"company_id": "00000000-0000-0000-0000-000000000001"}'

Create a candidate and application (via Supabase dashboard or API)
Reject the candidate to trigger matching:

curl -X POST http://localhost:3000/api/candidates/reject
  -H "Content-Type: application/json"
  -d '{
    "candidate_id": "your-candidate-uuid",
    "application_id": "your-application-uuid",
    "rejection_reason": "Overqualified"
  }'

Check the workflow status:

curl http://localhost:3000/api/workflow/status/[workflow_id]

📈 Performance

CV Parsing: ~2-4 seconds
Embedding Generation: ~1 second per type (3 parallel)
Vector Search: <100ms per query (with HNSW index)
Match Consolidation: <50ms
Analysis Generation: ~3-5 seconds
Total Workflow: ~10-15 seconds

💰 Cost Estimates

Per candidate workflow:

Gemini Parsing: ~$0.02
Embeddings (3 types): ~$0.06
Vector Search: ~$0.01
Analysis: ~$0.03
Total: ~$0.12 per candidate

🛡️ Production Checklist

[ ] Set up proper authentication
[ ] Configure Row Level Security (RLS) in Supabase
[ ] Set up monitoring and alerting
[ ] Configure rate limiting
[ ] Set up error tracking (e.g., Sentry)
[ ] Deploy workers to production (e.g., Railway, Render)
[ ] Set up CI/CD pipeline
[ ] Configure backup strategy
[ ] Set up log aggregation
[ ] Performance testing

📚 Documentation

API Documentation - Complete API reference with validation rules
Developer Guide - Development workflow and Claude Code infrastructure
Error Handling Guide - Common errors and troubleshooting
Error Notes - Recent fixes and resolved issues

📝 License

MIT

🤝 Contributing

We use epic-based development with Claude Code infrastructure:

Initialize Epic: Use /pm:init to start new features
Follow Patterns: See Developer Guide for workflow
Use Agents: Leverage specialized agents for code quality and testing
Smart Commits: Use /commit for validated commits

Contributions welcome! Please open an issue or PR.

📧 Support

For questions or issues:

Debug with Claude Code: Use Task agent_type="code-analyzer" description="Investigate issue"
Check Documentation: Review Error Handling Guide
GitHub Issues: Open an issue for bugs or feature requests
Developer Help: Use /pm:help for command assistance

shadcn-ui-expert