feat(matching): Rebuild Tailored Job Matching Engine, Zero-Hallucination Seniority Protection, and Explainable Recommendations

[superezzdev]

Summary

This pull request completely rebuilds the job recommendation and matching engine to strictly tailor jobs to the user's verified profile data (verified experience, skills, education, projects, and employment preferences), replacing the naive keyword search and artificial baseline scoring (score = 55, Math.max(72, ...)).

Recommendations now strictly adhere to the principle: "Rank jobs based on what this specific user can realistically apply for, using verified profile/resume information."

---

Key Architectural Changes

1. Database Schema & Invalidation Cache (20260907_tailored_job_matching_system.sql):

   • Added profile_version, preferred_roles, preferred_locations, remote_preference, and employment_preferences to public.profiles.
   • Added not_relevant, hidden, and feedback_reason to public.user_job_interactions.
   • Added normalized_job_data JSONB column to public.canonical_jobs.
   • Created public.job_matches table with unique constraint (user_id, job_id), indexing, and RLS policies.
   • Updated src/lib/resume/profile-sync.ts to increment profile_version and purge stale cached matches whenever a user updates or reparses their resume.

2. Verified User Career Profile Builder (src/lib/matching/career-profile-builder.ts):

   • Parses duration into verified months (e.g., 7 verified months for early-career profiles).
   • Derives candidate seniority strictly from verified experience (ENTRY_LEVEL for $< 24$ months).
   • Enforces strict separation: project experience $\neq$ professional employment experience.
   • Categorizes skills cleanly into technical skills, frameworks, databases, and developer tools without hallucinating unverified technologies.

3. Job Normalization Engine (src/lib/matching/job-normalizer.ts):

   • Segregates required skills from preferred skills.
   • Parses experience requirements and seniority (INTERN, ENTRY_LEVEL, MID, SENIOR, LEAD, etc.).
   • Classifies role families, including non-engineering families (finance_accounting, marketing_sales, hr_recruiting, operations_support, ui_ux_design) to prevent keyword bleed.

4. Multi-Stage Deterministic Matcher (src/lib/matching/matcher.ts):

   • Hard Filters:
     • Seniority protection: blocks early-career candidates from Senior/Lead/Staff/Manager roles and roles requiring $\ge 36$ months.
     • Role family isolation: software engineering candidates are blocked from irrelevant non-tech roles (Financial Analyst, Marketing Manager).
     • User feedback: suppresses jobs marked not_relevant or hidden.
   • Weighted Scoring:
     • Required Skills (50%)
     • Role & Title Alignment (20%)
     • Preferred Skills (15% — missing preferred skills does not heavily penalize)
     • Experience Alignment (10%)
     • Education Alignment (5%)
     • Project stack relevance (+5 pts) and freshness (+1 to +3 pts) bonuses.
   • Quality Threshold: Jobs scoring $< 45$ or failing hard filters are excluded from the primary recommendation feed.
   • Company Diversity: Caps top recommendations to a maximum of 4 jobs per company.

5. Search Query Generation & AI Semantic Reranker (query-generator.ts, ai-reranker.ts):

   • Generates high-signal queries ("entry level full stack developer", "junior software engineer react node", "MERN developer") from verified signals instead of isolated weak keywords.
   • Optional AI reranker operates under strict negative constraints with deterministic fallback.

6. UI & User Feedback Enhancements (job-card.tsx, job-list.tsx, jobs-dashboard.tsx, /api/jobs):

   • Added "Why recommended" banner with human-readable rationale citing verified skills.
   • Added verified matched skills (emerald pills with checkmarks) and missing requirements (amber pills).
   • Added "Not Relevant" action button that updates user interactions and removes the role from recommendations.
   • Updated empty state to display: "We couldn't find enough strong matches yet. Our recommendation engine prioritizes precision over raw quantity..."

---

Verification & Test Suite

• Benchmark Evaluation Suite (tests/matching/job-matching.test.ts):
  • Full Stack MERN Developer $\rightarrow$ 89% (Excellent Match) ✓
  • Junior React Developer $\rightarrow$ 78% (Strong Match) ✓
  • Software Engineer (React, Node) $\rightarrow$ 79% (Strong Match) ✓
  • Entry-Level Node Developer $\rightarrow$ 72% (Strong Match) ✓
  • Senior Java Backend Engineer $\rightarrow$ Excluded (Seniority Protection) ✓
  • Data Scientist (Python, ML) $\rightarrow$ Excluded (Missing Stack, 39%) ✓
  • Marketing Manager & Financial Analyst $\rightarrow$ Excluded (Role Family Filter, 15%) ✓
  • DevOps (Kubernetes, Terraform) & UI/UX Designer $\rightarrow$ Excluded ($< 45$ Threshold) ✓
  • Golden Rule Ranking & Company Diversity $\rightarrow$ Passed ✓
• Type Checking (npx tsc --noEmit): 0 errors ✓
• Full Integration Suite (npm test): 29 test files passed, 211 tests passed, 0 failures ✓

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
openned	Ready	Preview	Sep 1, 2026 7:19pm UTC

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 69f22f5e-0a65-428b-a504-78708cf1aada

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}