Home A - Z
Page Index

Commit 291453

2025-10-07 10:48:54 Vinay Deokar: All modules are added
Projects/HireGenius/LLD.md ..
@@ 115,3 115,164 @@
- 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
+
+ ---
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9