🏗️ 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:

1. Parses their CV using Gemini AI
2. Generates embeddings for skills, experience, and overall profile
3. Searches for similar open positions using pgvector
4. Consolidates and ranks matches
5. 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

1. Create a new project at supabase.com
2. Run the migration from supabase-migration.sql in the SQL Editor
3. 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           

...