Upload README.md

README.md

@@ -1,26 +1,290 @@
+# 🤖 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](./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
+```
+
 ---
-tags:
-- ml-intern
+
+## 📊 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 |
+
 ---
 
-# plplpl183/ai-powered-hr-task-optimizer
+## 🔐 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
 
-<!-- ml-intern-provenance -->
-## Generated by ML Intern
+---
+
+## �� Documentation
 
-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.
+- [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)
 
-- Try ML Intern: https://smolagents-ml-intern.hf.space
-- Source code: https://github.com/huggingface/ml-intern
+---
 
-## Usage
+## 🤝 Contributing
 
-```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
+We use [Conventional Commits](https://www.conventionalcommits.org/):
 
-model_id = "plplpl183/ai-powered-hr-task-optimizer"
-tokenizer = AutoTokenizer.from_pretrained(model_id)
-model = AutoModelForCausalLM.from_pretrained(model_id)
+```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
 ```
 
-For non-causal architectures, replace `AutoModelForCausalLM` with the appropriate `AutoModel` class.
+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
+
+---
+
+<p align="center">
+  Built with ❤️ by <a href="https://github.com/plplpl183">@plplpl183</a>
+</p>