Feature: Complete Hiring Pipeline with Kanban Board, Scorecards & Email Notifications

.gitignore

@@ -6,3 +6,25 @@
 *.iml
 out
 gen
+
+# Dependencies
+node_modules/
+backend/node_modules/
+frontend/node_modules/
+
+# Environment variables
+.env
+backend/.env
+frontend/.env
+
+# Build outputs
+frontend/build/
+frontend/dist/
+
+# Logs
+*.log
+npm-debug.log*
+
+# OS files
+.DS_Store
+Thumbs.db

IMPLEMENTATION.md

@@ -0,0 +1,241 @@
+# Hiring Pipeline Feature - Implementation Summary
+
+## Overview
+
+This document summarizes the implementation of the hiring pipeline feature as specified in the GitHub issue.
+
+## What Was Implemented
+
+### Backend Changes
+
+#### 1. Extended Data Models
+
+**Application Model** (`backend/models/Application.js`)
+- ✅ Added `status` field with enum values: `applied`, `phone_screen`, `onsite`, `offer`, `hired`, `rejected`
+- ✅ Added `scorecard` object containing:
+  - `rating` (1-5 stars)
+  - `competencies` array (key, rating, notes)
+  - `summary` (overall feedback)
+  - `updatedAt` (timestamp)
+  - `updatedBy` (user reference for future use)
+- ✅ Added `stageHistory` array to track all stage transitions with:
+  - `from` and `to` stages
+  - `changedAt` timestamp
+  - `changedBy` (user reference for future use)
+  - `note` (optional comment)
+
+**Job Model** (`backend/models/Job.js`)
+- ✅ Added `stages` array with default pipeline stages
+- ✅ Added `emailTemplates` object for automated notifications with templates for:
+  - `phone_screen`
+  - `onsite`
+  - `offer`
+  - `rejected`
+
+#### 2. New API Endpoints
+
+**Applications Routes** (`backend/routes/applications.js`)
+- ✅ `GET /api/applications` - Enhanced with query filters:
+  - `jobId` - Filter by specific job
+  - `stage` - Filter by current status
+  - `q` - Search by candidate name or cover letter
+  - `minRating` - Filter by minimum scorecard rating
+- ✅ `GET /api/applications/:id` - Get single application details
+- ✅ `PATCH /api/applications/:id/status` - Update application stage
+  - Validates stage against job's allowed stages
+  - Records stage transition in history
+  - Sends email notification if template is enabled
+- ✅ `PATCH /api/applications/:id/scorecard` - Update application scorecard
+  - Saves rating, competencies, and summary
+  - Records update timestamp
+
+#### 3. Email Notification System
+
+**Email Utility** (`backend/utils/email.js`)
+- ✅ Nodemailer integration for SMTP email sending
+- ✅ Template variable replacement ({{candidateName}}, {{jobTitle}})
+- ✅ Configurable via environment variables
+- ✅ Graceful degradation when SMTP not configured
+
+**Environment Configuration** (`backend/.env.example`)
+- ✅ Added SMTP configuration variables:
+  - `SMTP_HOST`
+  - `SMTP_PORT`
+  - `SMTP_USER`
+  - `SMTP_PASS`
+
+### Frontend Changes
+
+#### 1. New Components
+
+**PipelineBoard** (`frontend/src/components/PipelineBoard.js`)
+- ✅ Kanban-style board with columns for each stage
+- ✅ Drag-and-drop functionality using @dnd-kit
+- ✅ Real-time search/filter by candidate name or email
+- ✅ Optimistic UI updates with error handling
+- ✅ Responsive grid layout
+
+**ApplicationCard** (`frontend/src/components/ApplicationCard.js`)
+- ✅ Compact card showing candidate info
+- ✅ Displays scorecard rating if available
+- ✅ Draggable using @dnd-kit/sortable
+- ✅ Click to open detail dialog
+
+**ApplicationDetailDialog** (`frontend/src/components/ApplicationDetailDialog.js`)
+- ✅ Modal dialog with three tabs:
+  - Overview: Candidate details, job info, cover letter
+  - Scorecard: Rating and evaluation form
+  - Timeline: Stage history visualization
+- ✅ Full-width responsive design
+
+**ScorecardForm** (`frontend/src/components/ScorecardForm.js`)
+- ✅ Overall rating (1-5 stars)
+- ✅ Four default competencies:
+  - Communication
+  - Problem-Solving
+  - Technical Skills
+  - Culture Fit
+- ✅ Individual ratings and notes for each competency
+- ✅ Overall summary text field
+- ✅ Save/Cancel actions
+
+**TimelineList** (`frontend/src/components/TimelineList.js`)
+- ✅ Visual timeline using @mui/lab Timeline components
+- ✅ Shows stage transitions with timestamps
+- ✅ Displays optional notes for each transition
+- ✅ Formatted stage names (e.g., "Phone Screen" instead of "phone_screen")
+
+**DroppableStage** (`frontend/src/components/DroppableStage.js`)
+- ✅ Droppable container for each pipeline stage
+- ✅ Visual feedback when hovering during drag
+- ✅ Contains sortable context for applications
+
+#### 2. Updated Components
+
+**App.js**
+- ✅ Added 'pipeline' view state
+- ✅ Added handleViewPipeline function
+- ✅ Integrated PipelineBoard component
+
+**JobList.js**
+- ✅ Added "Pipeline" button to each job card
+- ✅ Calls onViewPipeline callback
+
+#### 3. New Dependencies
+
+- ✅ @mui/lab - Timeline components
+- ✅ @mui/icons-material - Icons
+- ✅ @dnd-kit/core - Drag and drop core
+- ✅ @dnd-kit/sortable - Sortable items
+- ✅ @dnd-kit/utilities - Utility functions
+
+### Documentation
+
+#### 1. README Updates
+- ✅ Updated Features section with pipeline capabilities
+- ✅ Updated Technology Stack
+- ✅ Updated Directory Structure
+- ✅ Added API Documentation section with all endpoints
+- ✅ Added SMTP configuration instructions
+- ✅ Added Pipeline Stages documentation
+
+#### 2. Testing Guide
+- ✅ Created comprehensive TESTING.md
+- ✅ Backend API testing instructions with curl examples
+- ✅ Frontend testing checklist
+- ✅ Email notification testing guide
+- ✅ Troubleshooting section
+
+## Features Demonstrated
+
+### 1. Drag and Drop
+Users can drag application cards between pipeline stages, triggering automatic status updates and history recording.
+
+### 2. Scorecards
+Structured evaluation system with:
+- Overall rating
+- Individual competency ratings
+- Detailed notes per competency
+- Summary feedback
+- Timestamp tracking
+
+### 3. Timeline
+Complete audit trail of all stage transitions with:
+- Source and destination stages
+- Timestamps
+- Optional notes
+- Future support for user attribution
+
+### 4. Email Notifications
+Automated email sending when:
+- Application moves to a new stage
+- Email template is configured for that stage
+- Template is enabled
+- Candidate has email address
+
+### 5. Search and Filter
+Real-time filtering of applications by:
+- Candidate name
+- Email address
+- Current stage
+- Minimum rating
+
+## Testing Verification
+
+### Backend
+✅ All models compile without errors
+✅ All routes have proper error handling
+✅ Email utility handles missing configuration gracefully
+✅ API endpoints follow REST conventions
+
+### Frontend
+✅ Production build completes successfully
+✅ All components use proper TypeScript-compatible props
+✅ Material-UI components properly imported
+✅ Drag and drop integration complete
+✅ Responsive design implemented
+
+## Usage Instructions
+
+### For Recruiters
+
+1. **View Pipeline**: Click "Pipeline" on any job listing
+2. **Move Candidates**: Drag cards between stages
+3. **Add Scorecards**: Click a card → Scorecard tab → Fill and save
+4. **Review History**: Click a card → Timeline tab
+5. **Search**: Use search box to filter candidates
+
+### For Administrators
+
+1. **Configure Email**: Set SMTP credentials in backend/.env
+2. **Customize Stages**: Modify stages array in Job model
+3. **Create Templates**: Add email templates to job documents
+4. **Monitor Usage**: Check stage history for insights
+
+## Future Enhancements (Out of Scope)
+
+These features were marked as out of scope for v1 but could be added later:
+
+- Calendar booking UI with ICS invite generation
+- Multi-org/tenant separation
+- SSO integration
+- External HRIS sync
+- Bulk actions (email, stage move)
+- CSV export of pipeline data
+- Custom competency templates
+- Advanced analytics and reporting
+
+## Conclusion
+
+All features from the original GitHub issue have been successfully implemented:
+
+✅ Hiring pipeline with customizable stages
+✅ Drag-and-drop Kanban board
+✅ Scorecard system with ratings and feedback
+✅ Stage history timeline
+✅ Email notifications on stage changes
+✅ Search and filter functionality
+✅ Complete API documentation
+✅ Testing guide
+
+The implementation is production-ready and follows the existing codebase patterns and conventions.