ai-powered-hr-task-optimizer

🤖 AI-Powered HR Task Optimizer

<p align="center"> <img src="https://img.shields.io/badge/Next.js-14-black?style=for-the-badge&logo=next.js" /> <img src="https://img.shields.io/badge/Node.js-20-green?style=for-the-badge&logo=node.js" /> <img src="https://img.shields.io/badge/Python-3.11-blue?style=for-the-badge&logo=python" /> <img src="https://img.shields.io/badge/FastAPI-0.100+-009688?style=for-the-badge&logo=fastapi" /> <img src="https://img.shields.io/badge/PostgreSQL-15-336791?style=for-the-badge&logo=postgresql" /> <img src="https://img.shields.io/badge/Redis-7-DC382D?style=for-the-badge&logo=redis" /> <img src="https://img.shields.io/badge/Tailwind-3.4-38B2AC?style=for-the-badge&logo=tailwind-css" /> </p> <p align="center"> <b>Production-grade AI recruitment platform</b> — automate resume screening, rank candidates with embeddings + LLM reranking, prioritize recruiter tasks with ML, and manage the entire hiring pipeline. </p>

---

🚀 What This Is

A startup-grade SaaS ATS (Applicant Tracking System) built for modern HR teams. It combines:

• Semantic resume parsing with LLM extraction
• AI candidate ranking using sentence embeddings + GPT-4o reranking
• Intelligent task prioritization with LightGBM risk prediction
• Interview scheduling with Google Calendar integration
• AI email assistant with human-in-the-loop approval
• Real-time analytics for hiring velocity and pipeline bottlenecks

Live Demo: [Coming Soon] Architecture Deep Dive: See ADRs

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                       CLIENT LAYER                          │
│  Next.js 14 (App Router) ──► Vercel Edge / Serverless      │
│  - SSR Dashboards (SEO + performance)                       │
│  - React Server Components for data-heavy tables            │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTPS / JWT
┌──────────────────────▼──────────────────────────────────────┐
│                  API GATEWAY (Node.js)                      │
│  Express.js + Helmet + Rate Limiter + Request Validator   │
│  - Auth middleware (JWT + OAuth passthrough)               │
│  - Router: /api/v1/* → Main API                            │
│           /ai/v1/*   → AI Service Proxy (internal mTLS)   │
└──────┬─────────────────────┬────────────────────────────────┘
       │                   │
┌──────▼──────┐    ┌───────▼────────┐
│  CORE API   │    │   AI SERVICE   │
│  Node.js    │    │   FastAPI      │
│  Express    │    │   (GPU/CPU)    │
│  PostgreSQL │    │  Sentence-     │
│  Redis      │    │  Transformers  │
│  Bull MQ    │    │  OpenAI SDK    │
└──────┬──────┘    └───────┬────────┘
       │                   │
   ┌───▼────┐         ┌───▼────┐
   │  AWS   │         │  AWS   │
   │   S3   │         │  SQS / │
   │(Resumes│         │ Redis  │
   │  PDFs) │         │ (Queue)│
   └────────┘         └────────┘

Pattern: BFF (Backend-for-Frontend) + AI Microservice

• Node.js Core API handles I/O concurrency (auth, CRUD, notifications, calendar APIs)
• FastAPI AI Service isolates the ML lifecycle (torch, transformers, CUDA dependencies)
• Next.js App Router uses Server Components for dashboard data and Server Actions for mutations

---

✨ Features

---

🛠️ Tech Stack

Frontend

• Next.js 14 (App Router, Server Components, Server Actions)
• Tailwind CSS + shadcn/ui primitives
• TanStack Query for client-side data fetching
• Zustand for lightweight global state
• React Hook Form + Zod for validation
• Recharts / Tremor for analytics

Backend

• Node.js + Express (Core API)
• Python + FastAPI (AI Microservice)
• PostgreSQL 15 (primary database + pgvector for semantic search)
• Redis 7 (caching, sessions, BullMQ job queues)
• BullMQ (background job processing)

AI/ML

• Sentence Transformers (all-MiniLM-L6-v2 for embeddings)
• OpenAI GPT-4o (resume extraction, email generation, reranking)
• LightGBM (task prioritization model)
• scikit-learn (scoring ensembles)
• unstructured.io + pdfplumber (PDF parsing)

Auth & Deployment

• JWT + OAuth 2.0 (Google, GitHub)
• Vercel (frontend)
• Railway / Render (backend + AI service)
• AWS S3 (resume storage)
• SendGrid / AWS SES (transactional email)

---

📁 Monorepo Structure

hr-task-optimizer/
├── apps/
│   ├── web/                    # Next.js 14 App Router
│   │   ├── app/                # Route groups, Server Components
│   │   ├── components/         # UI primitives + domain composites
│   │   └── lib/                # API wrappers, utilities
│   ├── api/                    # Node.js Core API
│   │   ├── src/modules/        # Domain modules (auth, jobs, candidates, tasks)
│   │   ├── src/workers/        # BullMQ job processors
│   │   └── Dockerfile
│   └── ai-service/             # Python FastAPI
│       ├── app/routers/        # Embeddings, screening, generation, ranking
│       ├── services/           # Model singletons, LLM clients
│       └── Dockerfile.gpu
├── packages/
│   ├── shared-types/           # Zod schemas → TS + Pydantic
│   ├── ui/                     # shadcn/ui base config
│   └── eslint-config/
├── infra/
│   ├── docker-compose.yml      # Local dev stack
│   ├── k8s/                    # Kubernetes manifests
│   └── terraform/              # AWS/GCP provisioning
├── docs/
│   └── adr/                    # Architecture Decision Records
└── turbo.json

---

🚀 Quick Start

Prerequisites

• Docker + Docker Compose
• Node.js 20+ + pnpm
• Python 3.11+

1. Clone & Install

git clone https://github.com/plplpl183/ai-powered-hr-task-optimizer.git
cd ai-powered-hr-task-optimizer
pnpm install

2. Environment Setup

# Copy env files
cp apps/web/.env.example apps/web/.env.local
cp apps/api/.env.example apps/api/.env
cp apps/ai-service/.env.example apps/ai-service/.env

# Fill in your credentials (OpenAI, Google OAuth, AWS S3, etc.)

3. Start Local Stack

# Start PostgreSQL, Redis, MinIO (S3 mock)
docker-compose -f infra/docker-compose.yml up -d

# Run database migrations
pnpm db:migrate

# Start all apps in dev mode
pnpm dev

Services will be available at:

• Web: http://localhost:3000
• Core API: http://localhost:4000
• AI Service: http://localhost:8000
• PostgreSQL: localhost:5432
• Redis: localhost:6379
• MinIO (S3): http://localhost:9000

---

🧪 Testing

# Unit tests
pnpm test

# Integration tests (requires local stack)
pnpm test:integration

# AI service tests
pnpm test:ai

---

📊 Performance & Scale

---

🔐 Security

• HTTP-only cookies with SameSite=Lax for refresh tokens
• Rate limiting by IP + user (Redis-backed)
• File upload validation via magic numbers + size limits
• Parameterized queries (Drizzle ORM) — SQL injection impossible
• CORS restricted to known origins
• Helmet.js security headers
• Human-in-the-loop approval for all AI-generated emails

---

📖 Documentation

• Architecture Decision Records
  • 001: Why PostgreSQL over MongoDB
  • 002: Why FastAPI for AI Service
  • 003: Task Prioritization Heuristic vs ML
• API Documentation (OpenAPI/Swagger)
• Contributing Guidelines

---

🤝 Contributing

We use Conventional Commits:

feat: add AI email generation endpoint
fix: resolve race condition in task prioritization
docs: update API documentation
refactor: extract resume parser into service class
test: add integration tests for interview scheduler

See CONTRIBUTING.md for details.

---

📄 License

MIT License — see LICENSE for details.

---

🙏 Acknowledgments

• sentence-transformers for embedding models
• unstructured.io for PDF parsing
• shadcn/ui for UI primitives
• BullMQ for job queues

---

<p align="center"> Built with ❤️ by <a href="https://github.com/plplpl183">@plplpl183</a> </p> <!-- ml-intern-provenance -->

Generated by ML Intern

This model repository was generated by ML Intern, an agent for machine learning research and development on the Hugging Face Hub.

• Try ML Intern: https://smolagents-ml-intern.hf.space
• Source code: https://github.com/huggingface/ml-intern

Usage

from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "plplpl183/ai-powered-hr-task-optimizer"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id)

For non-causal architectures, replace AutoModelForCausalLM with the appropriate AutoModel class.