🎯 Candidate Tracking System

An intelligent, fully-automated candidate screening system that processes job applicant emails from Wellfound, extracts candidate information using AI, scores candidates based on custom criteria, and stores everything in Airtable.

🌟 Overview

Built for hiring managers and recruiters, this system eliminates the manual work of screening candidate emails. It automatically:

Fetches unprocessed candidate emails from Gmail
Uses GPT-4 to extract candidate details from HTML emails
Scores candidates based on customizable criteria (0-100 scale)
Labels processed emails in Gmail
Stores structured candidate data in Airtable

Perfect for: Recruiters processing high volumes of candidate applications, hiring teams using Wellfound/AngelList, and anyone who wants to automate their hiring pipeline.

✨ Features

🤖 Fully Automated Workflow - Zero manual intervention required
🧠 AI-Powered Extraction - GPT-4.1 intelligently parses complex HTML emails
📊 Smart Scoring System - Customizable 100-point scoring criteria
📧 Gmail Integration - Automatic email labeling via Pica
📋 Airtable Storage - Structured candidate data management
🔄 Batch Processing - Handles 100+ emails per batch with pagination
💪 Retry Logic - Built-in 5-attempt retry for reliability
⚡ Real-Time UI - Live progress tracking and status updates
🛑 Manual Controls - Stop, retry, or skip emails as needed
🎨 Modern Interface - Clean, responsive UI built with React

🏗️ How It Works

1. Load Emails
   ↓
2. For Each Email:
   ├─ Fetch email content via Pica Gmail API
   ├─ Extract candidate details (Name, Email, Skills, etc.)
   ├─ Calculate score based on criteria (0-100)
   ├─ Label email as "Wellfound Candidate found"
   └─ Store candidate record in Airtable
   ↓
3. Move to Next Email (automatic)
   ↓
4. Complete! ✓

The system processes emails sequentially with a 2-second delay between each to avoid rate limits. It automatically continues until all emails are processed or an error occurs.

🛠️ Tech Stack

Technology	Purpose
Next.js 15.2.2	React framework (App Router)
TypeScript 5	Type-safe development
OpenAI GPT-4.1	AI model for extraction & scoring
Pica Toolkit	Integration orchestration layer
Vercel AI SDK	Streaming AI responses
Gmail API	Email fetching & labeling (via Pica)
Airtable API	Candidate data storage (via Pica)
Tailwind CSS 4	Modern styling
Radix UI	Accessible UI components

📋 Prerequisites

Before you begin, ensure you have:

Node.js 18.18+ installed (Download)
Pica Account - Sign up at picaos.com
Gmail Connection - Set up via Pica dashboard
Airtable Account - Set up via Pica dashboard with a prepared candidate tracking base
OpenAI API Key - For GPT-4 access

🚀 Installation & Setup

1. Clone the Repository

git clone <your-repo-url>
cd candidates-tracking

2. Install Dependencies

Using npm:

npm install

Or using pnpm:

pnpm install

3. Set Up Environment Variables

Create a .env.local file in the root directory:

cp .env.example .env.local

Fill in your environment variables:

# Pica API Configuration
PICA_SECRET_KEY=your_pica_secret_key_here

# OpenAI API Key
OPENAI_API_KEY=your_openai_api_key_here

# Gmail Connection (via Pica)
NEXT_PUBLIC_GMAIL_CONNECTION_KEY=your_gmail_connection_key_here

# Airtable Configuration (via Pica)
AIRTABLE_CONNECTION_KEY=your_airtable_connection_key_here
AIRTABLE_BASE_ID=your_airtable_base_id_here
AIRTABLE_TABLE_ID=your_airtable_table_id_here

📝 Environment Variables Explained

Variable	Description	Where to Find
`PICA_SECRET_KEY`	Your Pica API secret key	Pica Dashboard → Settings → API Keys
`OPENAI_API_KEY`	OpenAI API key for GPT-4	OpenAI Platform → API Keys
`NEXT_PUBLIC_GMAIL_CONNECTION_KEY`	Gmail connection identifier	Pica Dashboard → Connections → Gmail → Connection Key
`AIRTABLE_CONNECTION_KEY`	Airtable connection identifier	Pica Dashboard → Connections → Airtable → Connection Key
`AIRTABLE_BASE_ID`	Your Airtable base ID	Airtable base URL: `app{BASE_ID}`
`AIRTABLE_TABLE_ID`	Your Airtable table ID	Airtable table URL: `tbl{TABLE_ID}`

🔌 Pica Setup Guide

1. Create a Pica Account

Go to picaos.com and sign up
Navigate to your dashboard

2. Connect Gmail

Click "Connections" → "Add Connection"
Select Gmail
Authenticate with your Google account
Copy the Connection Key

3. Connect Airtable

Click "Connections" → "Add Connection"
Select Airtable
Authenticate with your Airtable account
Copy the Connection Key

4. Get Your API Key

Go to Settings → API Keys
Create a new API key
Copy your Pica Secret Key

📊 Airtable Setup

1. Create a Base

Create a new Airtable base called "Candidate Tracking" (or any name you prefer).

2. Create a Table with These Fields

Your Airtable table must have these fields (exact names required):

Field Name	Type	Description
`Name`	Single line text	Candidate's full name
`Email`	Email	Candidate's email address
`Location`	Single line text	Candidate's location
`Current Company`	Single line text	Current employer
`Current Title`	Single line text	Current job title
`School`	Single line text	Educational institution
`Degree`	Single line text	Degree obtained
`Skills`	Long text	Comma-separated skills
`Job Search Status`	Single line text	Job search status from email
`Years of Experience`	Single line text	Years of experience (optional)
`Score`	Number	Calculated score (0-100)
`Score Reasoning`	Long text	Detailed scoring explanation

3. Get Your Base ID and Table ID

Base ID:

Open your Airtable base
Look at the URL: https://airtable.com/app{YOUR_BASE_ID}/...
Copy app{YOUR_BASE_ID} (e.g., appXYZ123)

Table ID:

Click on any table in your base
Look at the URL: https://airtable.com/app.../tbl{YOUR_TABLE_ID}/...
Copy tbl{YOUR_TABLE_ID} (e.g., tblABC456)

🎮 Running the Application

Development Mode

npm run dev

The application will start at http://localhost:3000

Production Build

npm run build
npm start

Linting

npm run lint

📖 Usage Guide

Step-by-Step Workflow

Open the Application
- Navigate to http://localhost:3000
- You'll see the Candidate Hiring dashboard
Load Emails
- Click the "Load Emails" button
- The system fetches up to 100 unprocessed emails matching the criteria
- Currently searches for: subject:"is interested in Software Engineer (Integrations) at Pica" -label:"Wellfound Candidate found"
Automatic Processing Begins
- The system automatically processes each email:
  - ✅ Fetches email content
  - ✅ Extracts candidate information
  - ✅ Calculates score
  - ✅ Labels email in Gmail
  - ✅ Stores data in Airtable
- Progress bar updates in real-time
- 2-second delay between emails
Monitor Progress
- Progress Bar - Shows completion percentage
- Status Badge - "Processing", "Error", "Complete"
- Message View - Real-time AI processing logs
- Current Email - Shows which email is being processed
Handle Errors (if any)
- If an error occurs, the system stops automatically
- You'll see an error toast with details
- Options available:
  - Retry - Reprocess the failed email
  - Skip - Move to the next email
Manual Controls
- Stop Processing - Stops the current workflow
- Useful if you need to pause or review
Completion
- Once all emails are processed, you'll see a success message
- All candidate data is now in your Airtable base
- Processed emails are labeled in Gmail

🎯 Scoring Criteria

Candidates are scored out of 100 points based on the following criteria:

Criterion	Points	Description
AI/LLM Experience	30	Experience with LLM, LangChain, CrewAI, Generative AI, or similar
Python Experience	20	Has Python in their skills
Additional Languages	20	Experience with Rust or Scala
TypeScript Experience	10	Has TypeScript in their skills
Years of Experience	20	More than 3 years of software development experience

Total: 100 points

Example Scoring

Candidate A:

✅ Has LangChain experience (30 points)
✅ Python developer (20 points)
❌ No Rust/Scala (0 points)
✅ TypeScript skills (10 points)
✅ 5 years experience (20 points)
Total: 80/100

Score Reasoning (stored in Airtable):

"Scored 80/100: Candidate has strong AI experience (30 points) with LangChain and LLM development, Python skills (20 points), TypeScript experience (10 points), and 5 years of professional experience (20 points). However, lacks Rust/Scala experience (0 points)."

📁 Project Structure

candidates-tracking/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── chat/
│   │   │   │   └── route.ts          # AI chat endpoint (GPT-4 streaming)
│   │   │   └── load-emails/
│   │   │       └── route.ts          # Gmail email fetching API
│   │   ├── page.tsx                  # Main UI component
│   │   ├── layout.tsx                # App layout
│   │   └── globals.css               # Global styles
│   ├── components/
│   │   ├── ai-elements/              # AI UI components
│   │   ├── ui/                       # Reusable UI components
│   │   ├── OptimizedMessage.tsx      # Message rendering
│   │   └── VirtualizedMessageList.tsx # Efficient message list
│   └── lib/
│       ├── prompts/
│       │   └── candidate-tracking.ts # System prompt & instructions
│       ├── tools/
│       │   ├── gmail-tools.ts        # Gmail labeling tool
│       │   └── airtable-tools.ts     # Airtable insertion tool
│       └── utils.ts                  # Utility functions
├── public/                           # Static assets
├── .env.local                        # Environment variables (create this)
├── .env.example                      # Environment template
├── package.json                      # Dependencies
├── next.config.ts                    # Next.js configuration
├── tsconfig.json                     # TypeScript configuration
└── README.md                         # This file

Key Files to Modify

File	Purpose	Customize For
`src/lib/prompts/candidate-tracking.ts`	System prompt, job description, scoring criteria	Different roles, scoring systems
`src/app/page.tsx` (line 143)	Email search query	Different email subjects/filters
`src/app/api/load-emails/route.ts`	Gmail API query parameters, max results	Email filtering, pagination settings
`src/lib/tools/gmail-tools.ts`	Gmail label name, retry logic	Custom label names, retry behavior
`src/lib/tools/airtable-tools.ts`	Airtable field mapping	Custom Airtable schema

🎨 Customization Guide

Change the Job Description

Edit src/lib/prompts/candidate-tracking.ts:

// Update lines 13-41 with your job description
Job Title: Your Job Title Here
Location: Your Location
Company: Your Company
...

Modify Scoring Criteria

Edit src/lib/prompts/candidate-tracking.ts:

// Update lines 44-86 with your scoring criteria
1. Criterion One (XX points):
   - Description
   ...

Change Email Filter

Edit src/app/page.tsx (line 143):

query: 'subject:"your email subject here" -label:"your label here"'

Gmail Query Syntax:

subject:"text" - Emails with specific subject
-label:"name" - Exclude emails with label
from:[email protected] - From specific sender
after:2025/01/01 - After specific date
Combine with spaces (AND logic)

Adjust Retry Logic

Edit tool files to change retry attempts:

// In src/lib/tools/gmail-tools.ts or airtable-tools.ts
const MAX_RETRIES = 5; // Change this number

🐛 Troubleshooting

Common Issues

❌ "Missing PICA_SECRET_KEY" Error

Ensure all environment variables are set in .env.local
Restart the development server after adding variables
Check for typos in variable names

❌ "Failed to fetch Gmail emails"

Verify your Gmail connection is active in Pica dashboard
Check NEXT_PUBLIC_GMAIL_CONNECTION_KEY is correct
Ensure Gmail API is enabled for your Pica account

❌ "Failed to add candidate to Airtable"

Verify Airtable field names match exactly (case-sensitive)
Check AIRTABLE_BASE_ID and AIRTABLE_TABLE_ID are correct
Ensure Airtable connection has write permissions

❌ "No emails found"

Check your Gmail query syntax
Verify emails exist matching the criteria
Ensure emails aren't already labeled

❌ Processing stops unexpectedly

Check browser console for errors
Look for error toasts in the UI
Verify OpenAI API key has sufficient credits
Check if you hit Pica rate limits

Debug Mode

Enable detailed logging:

# In browser console
localStorage.setItem('debug', 'true')

Check server logs:

# Terminal where dev server is running
# All API calls and tool executions are logged with prefixes:
# 📧 [GMAIL-TOOL]
# 🔵 [AIRTABLE-TOOL]
# 🔄 [STREAM]

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch
```
git checkout -b feature/amazing-feature
```
Make your changes
- Write clean, commented code
- Follow existing code style
- Test thoroughly
Commit your changes
```
git commit -m "Add amazing feature"
```
Push to your branch
```
git push origin feature/amazing-feature
```
Open a Pull Request

Code Style Guidelines

Use TypeScript for all new code
Follow existing naming conventions
Add comments for complex logic
Use descriptive variable names
Keep functions focused and small

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Pica - Integration orchestration platform
Vercel AI SDK - AI streaming framework
OpenAI - GPT-4 language model
shadcn/ui - UI component inspiration

📧 Support

Issues: Open an issue
Discussions: Join discussions
Pica Documentation: picaos.com/docs

Built with ❤️ for recruiters and hiring teams

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
public		public
src		src
.gitignore		.gitignore
README.md		README.md
components.json		components.json
env.example		env.example
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

picahq/hiring

Folders and files

Latest commit

History

Repository files navigation