Technical Document (LLD/HLD)

HireGenius- AI-Powered Recruitment Automation System

📘 Table of Contents

1. System Overview
2. Module Breakdown
3. API Design
4. Database Design
5. Business Workflow
6. System Architecture
7. Sequence Diagram
8. Flow Diagram

1. System Overview

1.1 🎯 Purpose

Automate the recruitment pipeline from resume ingestion to candidate ranking using NLP-based parsing, vector embeddings, and AI-powered re-ranking.

1.2 ⚙️ Key Capabilities

• Incremental Resume Ingestion: Fetch new resumes from Gmail on schedule
• Automated Resume Parsing: Extract structured data (skills, experience, education, contact)
• Semantic Matching: Use embeddings to find similar candidates to job descriptions
• AI Re-Ranking: Re-rank top candidates using GPT-4o-mini for better precision
• Dashboard: HR views ranked candidates with explainability

1.3 🧰 Technology Stack

2. Module Breakdown

Module 1: Gmail Module

Responsibility: Email integration and resume fetching

Functions:

• Authenticate with Gmail API using OAuth 2.0
• Fetch emails with attachments based on filters (date, keywords, labels)
• Download resume attachments (PDF, DOCX)
• Track last fetch timestamp for incremental processing

Key Operations:

• fetchNewEmails(afterDate, filters) → Returns array of email objects with attachments
• downloadAttachment(messageId, attachmentId) → Returns file buffer
• getLastFetchTime(jobId) → Returns timestamp of last successful fetch

External Dependencies: Gmail API, Google OAuth 2.0

Module 2: Resume Parser Module

Responsibility: Extract structured data from resume text

Parsing Strategy: Rule-based NLP with regex patterns

Name Extraction: First line heuristics, capitalization patterns
Email Extraction: Regex pattern [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}
Phone Extraction: Regex for various formats (+1-XXX-XXX-XXXX, (XXX) XXX-XXXX)
Skills Extraction: Keyword matching against predefined skill database
Experience Parsing: Section detection (keywords: "experience", "work history") + date parsing
Education Parsing: Section detection + degree/institution extraction

Functions:

• extractText(fileBuffer, format) → Returns plain text from PDF/DOCX
• parseResume(resumeText) → Returns structured JSON object
• validateParsedData(data) → Returns boolean + error messages
• normalizeSkills(skillArray) → Returns deduplicated, lowercase skills

Output Format (JSON):

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1-555-0123",
  "skills": ["javascript", "python", "sql"],
  "experience": [
    {
      "title": "Software Engineer",
      "company": "Tech Corp",
      "duration": "2020-2023",
      "description": "Built REST APIs..."
    }
  ],
  "education": [
    {
      "degree": "B.S. Computer Science",
      "institution": "MIT",
      "year": 2018
    }
  ],
  "total_experience_years": 5
}

Alternative AI Approach (Optional Enhancement)

Instead of rule-based parsing, use GPT-4o-mini with structured JSON output. The flow would be: extract plain text -> send it to GPT-4o-mini with a schema-enforced prompt -> receive structured JSON (name, email, phone, skills, experience, education, total years).

Pros:

• Much higher accuracy across different resume formats and layouts
• Handles inconsistent structures, missing sections, and varied wording
• Reduces need for complex regex/heuristics

Cons:

• Incur API usage costs
• Slightly higher latency (~2–5 seconds per resume, depending on length)
• Requires API reliability and internet access

Module 3: Embedding Module

Responsibility: Generate vector embeddings for semantic search

Embedding Strategy:

• Use OpenAI text-embedding-3-small model (1536 dimensions)
• Embed full resume text (truncated to 8000 chars if needed)
• Embed JD text once per job creation
• Store vectors in PostgreSQL pgvector columns

Functions:

• generateEmbedding(text) -> Returns 1536-dimensional float array
• batchGenerateEmbeddings(textArray) -> Returns array of vectors (for efficiency)
• calculateCosineSimilarity(vec1, vec2) -> Returns similarity score (0-1)

Caching Strategy:

• Cache JD embeddings in memory (job lifecycle)
• Resume embeddings stored permanently in database

Module 4: Database Module

Responsibility: Data persistence and vector operations

Core Operations:

• CRUD for all entities (users, jobs, candidates, communications)
• Vector similarity search using pgvector
• Transaction management for atomic operations
• Query optimization with proper indexing

Key Functions:

• storeCandidate(candidateData) -> Returns candidateId
• findSimilarCandidates(jdEmbedding, topK) -> Returns top-K candidate IDs by cosine similarity
• updateCandidateScore(candidateId, score) -> Updates match score
• getCandidatesByJob(jobId, filters) -> Returns paginated candidate list

Vector Search Query (Conceptual):

• Use pgvector's <=> operator for cosine distance
• Order by 1 - (jd_embedding <=> resume_embedding) for similarity
• Apply filters (status, score range) after vector search

Module 5: Job Description Module

Responsibility: JD lifecycle management and candidate retrieval

Functions:

• createJob(jobData) -> Validates input, generates embedding, stores in DB
• getActiveJobs() -> Returns list of jobs with status='active'
• findTopCandidates(jobId, topK) -> Queries DB for top-K similar candidates
• closeJob(jobId) -> Updates status, stops scheduled tasks

JD Processing Flow:

• HR submits JD text via UI
• Validate JD (length, required fields)
• Generate embedding for JD text
• Store job with embedding in database
• Schedule resume ingestion task (cron)
• Return job ID to frontend

Embedding Generation:

• Extract key requirements from JD text
• Generate single embedding vector (1536-dim)
• Store in jobs.jd_embedding column

Module 6: Ranking Module

Responsibility: AI-powered re-ranking of top candidates

Two-Stage Ranking:

Stage 1: Vector Similarity (Fast)

• Use pgvector to retrieve top-50 candidates by cosine similarity
• Initial filter based on semantic matching
• Execution time: <100ms

Stage 2: AI Re-Ranking (Precise)

• Use GPT-4o-mini to re-rank top-50 -> top-10
• Provide full context: JD text + parsed resume data
• AI considers: skill match, experience relevance, education fit
• Execution time: 2-3 seconds

Functions:

• getTopKSimilar(jobId, k) -> Returns top-K candidates from vector search
• reRankWithAI(candidates, jdText) -> Returns re-ranked list with scores and reasoning
• calculateFinalScore(candidate, job) -> Combines vector similarity + AI score

AI Re-Ranking Prompt Structure:
System: You are an expert technical recruiter evaluating candidate fit.

Input:

• Job Description: [JD text]
• Candidates: [Array of parsed resume data]

Task:
Rank these candidates from best to worst fit. For each, provide:

1. Rank position (1-N)
2. Fit score (0-1)
3. Brief reasoning (2-3 sentences)

Consider:

• Skill alignment with required skills
• Experience level match
• Domain relevance
• Education requirements

Output Format: JSON array ordered by rank

Scoring Algorithm:

• Initial Vector Similarity: S_vec (from pgvector)
• AI Re-Ranking Score: S_ai (from GPT-4o-mini)

Final Score: Final Score = 0.4 × S_vec + 0.6 × S_ai

Reasoning: Vector similarity provides broad semantic match, AI re-ranking adds nuanced understanding of requirements.

Module 7: Application Controller

Responsibility: Orchestrate workflow across modules

Core Workflows:

Resume Processing Workflow

• Trigger: Cron job (every 4 hours)
• Steps: Fetch emails → Extract text → Parse → Embed → Store

Candidate Ranking Workflow

• Trigger: HR requests candidates for a job
• Steps: Vector search → AI re-rank → Return ranked list

Deduplication Workflow

• Trigger: Before storing new candidate
• Steps: Hash resume text → Check DB → Skip if exists

Functions:

• processNewResumes(jobId) -> Orchestrates resume processing
• getRankedCandidates(jobId) -> Orchestrates ranking workflow
• handleDuplication(resumeHash) -> Checks and logs duplicates

Error Handling:

• Retry logic for API failures (3 attempts with exponential backoff)
• Log all errors with context (job ID, resume ID, error message)
• Continue processing remaining resumes on individual failures

Module 8: HR UI Module

Responsibility: Provide API endpoints for frontend dashboard

API Endpoints: Detailed in Section 3

Dashboard Views:

• Job listing with candidate counts
• Candidate pipeline (New, Contacted, Replied, Interviewed)
• Candidate detail with parsed data and match score
• Communication history per candidate

3. API Design

3.1 Authentication Endpoints

Authentication Flow:

• User submits credentials
• Server validates against database (bcrypt password comparison)
• Generate JWT with 24-hour expiry
• Return token to client
• Client includes token in all subsequent requests

3.2 Job Management Endpoints

Request Example (POST /api/jobs):

{
  "title": "Senior Full Stack Developer",
  "jd_text": "We are seeking an experienced full stack developer with 5+ years of experience in React, Node.js, and PostgreSQL. The ideal candidate will have strong problem-solving skills and experience with microservices architecture...",
  "start_date": "2025-10-01",
  "end_date": "2025-12-31",
  "min_score": 0.70
}

Response Example:

{
  "job_id": "uuid-123",
  "title": "Senior Full Stack Developer",
  "jd_embedding": [0.123, -0.456, ...], // 1536 dimensions
  "status": "active",
  "created_at": "2025-10-02T10:00:00Z"
}

3.3 Candidate Retrieval Endpoints

Request Example (GET /api/jobs/:jobId/candidates):

{
  "job_id": "uuid-123",
  "status": "new",
  "sort": "score",
  "page": 1,
  "limit": 20
}

Response Example:

{
  "candidates": [
    {
      "candidate_id": "uuid-456",
      "full_name": "John Doe",
      "email": "john@example.com",
      "match_score": 0.87,
      "status": "new",
      "parsed_data": {
        "skills": ["javascript", "react", "node.js", "postgresql"],
        "total_experience_years": 6
      },
      "ai_reasoning": "Strong technical alignment with 5/6 required skills. Experience exceeds minimum requirement.",
      "created_at": "2025-10-02T12:30:00Z"
    }
  ],
  "total": 45,
  "page": 1,
  "limit": 20
}

3.4 Resume Processing Endpoints (Internal)

3.5 Dashboard & Analytics Endpoints

Response Example (GET /api/dashboard/stats/:jobId):

{
  "total_candidates": 120,
  "by_status": {
    "new": 45,
    "contacted": 50,
    "replied": 20,
    "interviewed": 3,
    "rejected": 2
  },
  "avg_match_score": 0.74,
  "top_skills": ["javascript", "python", "react"],
  "last_updated": "2025-10-02T14:00:00Z"
}

4. Database Design

4.1 Entity Relationship Diagram (ERD)

4.2 Table Specifications

Table: users

Purpose: Store HR user accounts

Indexes:

• idx_users_email on email (for login queries)

Table: jobs

Purpose: Store job descriptions and automation settings

Indexes:

• idx_jobs_status on status (filter active jobs)
• idx_jobs_dates on (start_date, end_date) (date range queries)
• idx_jd_embedding on jd_embedding USING hnsw (vector_cosine_ops) (fast similarity search)

Constraints:

• CHECK (end_date >= start_date) (valid date range)

Table: candidates

Purpose: Store candidate resumes and parsed data

Indexes:

• idx_candidates_job on job_id (fetch candidates by job)
• idx_candidates_job_score on (job_id, match_score DESC) (ranked retrieval)
• idx_candidates_status on status (filter by status)
• idx_candidates_email on email (find by email)
• idx_candidates_hash on resume_hash (deduplication check)
• idx_resume_embedding on resume_embedding USING hnsw (vector_cosine_ops) (vector search)

JSONB Structure (parsed_data):

{
  "skills": ["javascript", "python", "react"],
  "experience": [
    {
      "title": "Software Engineer",
      "company": "Tech Corp",
      "duration": "2020-2023",
      "description": "Built microservices..."
    }
  ],
  "education": [
    {
      "degree": "B.S. Computer Science",
      "institution": "MIT",
      "year": 2018
    }
  ],
  "total_experience_years": 5
}

4.2 Table Specifications (continued)

Table: communication

Purpose: Log all email communications

Indexes:

• idx_comm_candidate on candidate_id (fetch communication history)
• idx_comm_type on type (filter by type)

Table: processing_logs

Purpose: Audit trail for resume processing

Indexes:

• idx_logs_job on job_id (fetch logs by job)
• idx_logs_hash on resume_hash (deduplication check)
• idx_logs_status on status (filter by status)

Purpose of Deduplication:

• Prevent reprocessing same resume across multiple jobs
• Track which resumes have been processed
• Maintain audit trail

Table: scheduled_tasks

Purpose: Manage cron jobs and scheduled tasks

Indexes:

• idx_tasks_job on job_id (fetch tasks by job)
• idx_tasks_status on status (find pending tasks)
• idx_tasks_scheduled on scheduled_time (time-based queries)

4.3 Database Relationships

Cascade Deletion Logic:

• When a job is deleted, all associated candidates, logs, and tasks are deleted
• When a candidate is deleted, all associated communications are deleted
• When a user is deleted, their jobs remain but created_by is set to NULL

4.4 pgvector Configuration

Extension Setup:

CREATE EXTENSION IF NOT EXISTS vector;

5. Business Workflow

PHASE 1: JOB CREATION

• HR User opens Dashboard → Create Job Form
  • Input: Title, JD Text, Dates, Min Score
• POST /api/jobs
  • Validate input (dates, text length)
  • Generate JD embedding (OpenAI API)
  • Store in database
  • Schedule cron job (resume ingestion every 4 hours)
• Job Created ✅
  • Status: Active

PHASE 2: RESUME INGESTION (Automated - Every 4 hours)

• Cron Trigger → Application Controller
• Gmail Module:
  • Fetch emails with attachments
  • Filter: after last fetch, keywords (resume, application)
  • Download attachments (PDF/DOCX)
• Resume Parser Module:
  • Extract text from PDF/DOCX
  • Generate SHA-256 hash
  • Check deduplication (processing_logs)
  • If duplicate → skip & log as 'duplicate'
  • If new → continue processing
• Parse Resume (Rule-based NLP):
  • Extract: Name, Email, Phone
  • Extract: Skills
  • Extract: Experience
  • Extract: Education
  • Calculate total experience years
• Structured JSON created: {name, email, skills[], experience[], education[], total_years}
• Embedding Module:
  • Generate embedding (1536-dim vector)
• Database Module:
  • Store candidate record:
    • parsed_data (JSONB)
    • resume_embedding
    • resume_hash
    • status: 'new'
  • Log processing in processing_logs:
    • status: 'success'
    • processing_time_ms
• Candidate Stored ✅

PHASE 3: CANDIDATE RANKING (On-Demand)

• HR User → Dashboard → View Job → Click "View Candidates"
• GET /api/jobs/:jobId/candidates
• Application Controller:
  • Ranking Module (Stage 1: Vector Search):
    • Fetch job.jd_embedding
    • Query top-50 candidates by cosine similarity
  • Ranking Module (Stage 2: AI Re-Ranking):
    • Prepare AI context (JD text + top-50 candidates)
    • Call GPT-4o-mini:
      • Rank candidates (1-50)
      • Fit score (0-1)
      • Brief reasoning
    • Calculate final_score = 0.4 × vector_sim + 0.6 × AI_score
    • Update candidates.match_score and ai_reasoning in DB
• Return Ranked Candidates → Frontend
• HR Dashboard displays Top-10 candidates:
  • Name, Email, Match Score
  • AI reasoning
  • Parsed Data (skills, experience)
  • Actions: View Details, Contact, Reject

PHASE 4: CANDIDATE INTERACTION (Manual)

• HR selects candidate → Actions:
  • View full resume
  • Update status ('contacted', 'replied', 'interviewed')
  • Add notes (stored in notes table)
  • Send email (logged in communication table)
• Status updated in database
• Dashboard reflects new status

PHASE 5: JOB CLOSURE

• HR closes job → DELETE /api/jobs/:jobId
  • Update job.status = 'closed'
  • Stop all scheduled tasks
  • Archive candidates (records remain in DB)
• Job Closed ✅

6. System Architecture

7. Sequence Diagram

8. Flow Diagram