Production-grade AI recruitment platform β automate resume screening, rank candidates with embeddings + LLM reranking, prioritize recruiter tasks with ML, and manage the entire hiring pipeline.
--- ## π 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](./docs/adr/) --- ## ποΈ 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 | Feature | Description | AI/ML Component | |---------|-------------|-----------------| | π€ **AI Task Prioritization** | Dynamically ranks recruiter tasks by urgency, deadline, candidate quality, and workload | LightGBM risk model + heuristic blend | | π **Resume Screening** | Upload PDFs, extract structured data (skills, experience, education) | unstructured.io + GPT-4o extraction | | π― **Smart Candidate Ranking** | Semantic similarity scoring + LLM reranking for precision | Sentence Transformers + GPT-4o | | π **Interview Scheduler** | Auto-manage slots, calendar sync, reminders, multi-stage workflow | Google Calendar API + BullMQ cron | | π **Recruitment Dashboard** | Pipeline analytics, hiring progress, task monitoring | PostgreSQL aggregations + Recharts | | βοΈ **AI Email Assistant** | Generate follow-ups, invites, rejections with human approval | GPT-4o with few-shot prompting | | π **Productivity Analytics** | Time-to-hire, conversion rates, recruiter efficiency, bottlenecks | Survival analysis + funnel metrics | | π **Notification System** | Smart alerts, deadline reminders, candidate inactivity | SSE + Redis Pub/Sub | --- ## π οΈ 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 ```bash git clone https://github.com/plplpl183/ai-powered-hr-task-optimizer.git cd ai-powered-hr-task-optimizer pnpm install ``` ### 2. Environment Setup ```bash # 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 ```bash # 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 ```bash # Unit tests pnpm test # Integration tests (requires local stack) pnpm test:integration # AI service tests pnpm test:ai ``` --- ## π Performance & Scale | Metric | Target | Implementation | |--------|--------|----------------| | Resume parsing | <5s per PDF | Async BullMQ worker + model singleton | | Candidate ranking | <200ms for top-20 | pgvector cosine similarity + LLM reranker | | Task prioritization | <100ms | LightGBM inference + Redis caching | | Dashboard load | <1s TTFB | Next.js Server Components + ISR | | Concurrent users | 1000+ | Horizontal scaling via K8s / Railway | --- ## π 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](./docs/adr/) - [001: Why PostgreSQL over MongoDB](./docs/adr/001-why-postgres.md) - [002: Why FastAPI for AI Service](./docs/adr/002-why-fastapi-for-ai.md) - [003: Task Prioritization Heuristic vs ML](./docs/adr/003-task-prioritization.md) - [API Documentation](https://api.hr-task-optimizer.dev/docs) (OpenAPI/Swagger) - [Contributing Guidelines](./CONTRIBUTING.md) --- ## π€ Contributing We use [Conventional Commits](https://www.conventionalcommits.org/): ```bash 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](./CONTRIBUTING.md) for details. --- ## π License MIT License β see [LICENSE](./LICENSE) for details. --- ## π Acknowledgments - [sentence-transformers](https://www.sbert.net/) for embedding models - [unstructured.io](https://unstructured.io/) for PDF parsing - [shadcn/ui](https://ui.shadcn.com/) for UI primitives - [BullMQ](https://docs.bullmq.io/) for job queues ---Built with β€οΈ by @plplpl183
## Generated by ML Intern This model repository was generated by [ML Intern](https://github.com/huggingface/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 ```python 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.