RecruitAI

An AI-powered recruitment platform that streamlines the hiring process with intelligent candidate sourcing, automated screening, and comprehensive evaluation tools. Built with modern web technologies and designed for recruiters and HR professionals.

🚀 Features

Core Functionality

• Smart Job Management: Create, edit, and manage job postings with intelligent edit limits
• AI-Powered Candidate Sourcing: Automatically fetch and evaluate candidates from LinkedIn and external sources
• Real-time Analysis: Live candidate processing with progress tracking via Socket.IO
• Comprehensive Scoring: Multi-dimensional AI evaluation (form, voice, total scores) with detailed explanations
• Email Enrichment: Automatic email discovery for candidates using Apollo API
• Experience Matching: Smart filtering based on job requirements and candidate experience levels

User Experience

• Multi-language Support: Full English and Thai language support
• Role-based Access: Separate dashboards for recruiters and administrators
• Real-time Updates: Live notifications and progress tracking
• Responsive Design: Mobile-friendly interface with modern UI/UX
• Subscription Management: Integrated Stripe billing with plan management

Advanced Features

• Edit Limit System: Prevents excessive job modifications with visual indicators
• Candidate Filtering: Filter by source, score range, and job requirements
• Export Capabilities: CSV and PDF export functionality
• Analytics Dashboard: Comprehensive reporting and statistics
• LinkedIn Integration: Direct profile access and connection tools

🛠 Tech Stack

Frontend

• Framework: Next.js 15.3.5 (App Router)
• UI Library: React 19.1.0
• Styling: Tailwind CSS 4.x
• Icons: Lucide React
• State Management: React Hooks
• HTTP Client: Axios
• Real-time: Socket.IO Client
• Notifications: React Hot Toast
• PDF Generation: jsPDF with AutoTable

Backend

• Runtime: Node.js with ES Modules
• Framework: Express.js 5.1.0
• Database: PostgreSQL with Prisma ORM 6.16.2
• Authentication: Supabase Auth with JWT middleware
• Real-time: Socket.IO 4.8.1
• AI Integration: OpenAI GPT-4o-mini
• External APIs: Unipile (LinkedIn), Apollo (Email discovery)
• Payments: Stripe 18.3.0

Infrastructure

• Database: PostgreSQL
• Authentication: Supabase
• Payments: Stripe
• Deployment: Netlify (Frontend), Vercel/Heroku (Backend)
• File Storage: Supabase Storage

📁 Project Structure

RecruitAI/
├── backend/                    # Express.js API server
│   ├── lib/                   # Core libraries
│   │   ├── prisma.js         # Database client
│   │   └── supabase.js       # Auth client
│   ├── routes/               # API endpoints
│   │   ├── auth.js          # Authentication routes
│   │   ├── recruiter.js     # Recruiter-specific routes
│   │   ├── admin.js         # Admin dashboard routes
│   │   └── stripe.js        # Payment processing
│   ├── utils/               # Utility functions
│   │   └── ai-evaluation.js # AI scoring logic
│   ├── scripts/             # Utility scripts
│   │   ├── add-plans.js     # Subscription plans setup
│   │   ├── check-openai.js  # OpenAI API testing
│   │   └── test-script.js   # LinkedIn profile fetching
│   ├── prisma/              # Database schema
│   │   └── schema.prisma    # Prisma schema definition
│   └── server.js            # Main server file
├── frontend/                 # Next.js application
│   ├── src/app/             # App Router pages
│   │   ├── components/      # Reusable components
│   │   │   ├── Recruiter/   # Recruiter-specific components
│   │   │   │   ├── JobCard.jsx
│   │   │   │   ├── JobForm.jsx
│   │   │   │   ├── CandidateList.jsx
│   │   │   │   └── ...
│   │   │   ├── RecruitersTable.jsx
│   │   │   ├── SubscriptionsTable.jsx
│   │   │   └── ...
│   │   ├── recruiter-dashboard/ # Recruiter dashboard
│   │   ├── admin-dashboard/     # Admin dashboard
│   │   ├── login/              # Authentication pages
│   │   ├── signup/
│   │   ├── pricing/           # Subscription plans
│   │   └── utils/             # Frontend utilities
│   │       ├── api.js         # API client
│   │       ├── http.js        # HTTP utilities
│   │       └── validation.js  # Form validation
│   └── out/                   # Static export
└── README.md

🚀 Quick Start

Prerequisites

• Node.js 18+
• PostgreSQL database
• Supabase account
• OpenAI API key
• Stripe account (for payments)
• Unipile account (for LinkedIn data)
• Apollo account (for email discovery)

1. Backend Setup

cd backend
npm install

# Create environment file
cp .env.example .env  # or create .env manually

Configure your .env file:

# Database
DATABASE_URL=postgresql://user:pass@host:5432/dbname
DIRECT_URL=postgresql://user:pass@host:5432/dbname

# Authentication
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your_supabase_anon_key
JWT_SECRET=your_jwt_secret

# AI Services
OPENAI_API_KEY=sk-your_openai_key

# External APIs
UNIPILE_API_KEY=your_unipile_key
UNIPILE_SUBDOMAIN=https://api19.unipile.com:14971
UNIPILE_ACCOUNT_ID=your_account_id

# Payments
STRIPE_SECRET_KEY=sk_test_your_stripe_key
STRIPE_SUCCESS_URL=http://localhost:3000/stripe-success
STRIPE_FAILURE_URL=http://localhost:3000/stripe-error

# URLs
BACKEND_URL=http://localhost:3001
FRONTEND_URL=http://localhost:3000
RESET_REDIRECT_URL=http://localhost:3000/reset-password

Initialize database:

npx prisma generate
npx prisma migrate dev --name init

Start the server:

npm start  # Runs on port 3001

2. Frontend Setup

cd frontend
npm install

# Create environment file
cp .env.example .env.local  # or create .env.local manually

Configure your .env.local file:

NEXT_PUBLIC_BACKEND_BASE_URL=http://localhost:3001
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

Start the development server:

npm run dev  # Runs on port 3000

3. Initial Setup

1. Create Subscription Plans: Run the script to set up default plans

   cd backend
   node scripts/add-plans.js

2. Test OpenAI Integration: Verify your API key works

   node scripts/check-openai.js

3. Access the Application:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:3001

📚 API Documentation

Authentication Endpoints

• POST /auth/signup - User registration
• POST /auth/login - User login
• POST /auth/forgot-password - Password reset request
• POST /auth/reset-password - Password reset confirmation
• POST /auth/change-password - Change password (authenticated)

Recruiter Endpoints

• GET /recruiter/profile - Get recruiter profile
• PUT /recruiter/profile - Update recruiter profile
• GET /recruiter/subscription - Get subscription details
• POST /recruiter/jobs - Create new job posting
• GET /recruiter/recuriter-jobs - List recruiter's jobs
• PUT /recruiter/jobs/:jobId - Update job (with edit limits)
• DELETE /recruiter/jobs/:jobId - Delete job
• GET /recruiter/jobs/:jobId/candidates - Get job candidates
• GET /recruiter/jobs/:jobId/edit-status - Check edit status
• GET /recruiter/candidates - Get all candidates
• POST /recruiter/candidate-ai-evaluation - Trigger AI evaluation

Admin Endpoints

• GET /admin/summary - Dashboard summary
• GET /admin/jobs - All jobs with filters
• GET /admin/recruiters - All recruiters
• GET /admin/subscriptions - All subscriptions
• POST /admin/add-recruiter - Add new recruiter

Payment Endpoints

• POST /stripe/create-checkout-session - Create payment session
• POST /stripe/create-portal-session - Manage subscription
• POST /stripe/webhook - Handle Stripe webhooks

🗄 Database Schema

Key Models

Recruiter

• User profile information
• Subscription details
• Job limits and permissions

Job

• Job posting details
• Edit tracking and limits
• Status and metadata

Candidate

• Profile information
• AI evaluation scores
• Source tracking
• Email and contact details

SubscriptionPlan

• Available plans
• Pricing and limits
• Stripe integration

UserSubscription

• Active subscriptions
• Billing information
• Plan associations

🔧 Development

Available Scripts

Backend:

• npm start - Start development server with nodemon
• npm test - Run tests (if configured)

Frontend:

• npm run dev - Start development server with Turbopack
• npm run build - Build for production
• npm run start - Start production server
• npm run lint - Run ESLint
• npm run export - Export static site

Development Tips

1. Real-time Features: The app uses Socket.IO for real-time candidate analysis updates
2. Edit Limits: Jobs have a maximum edit limit (default: 1) to prevent abuse
3. AI Evaluation: Candidates are automatically scored using OpenAI GPT-4o-mini
4. Email Discovery: Apollo API is used to find candidate email addresses
5. LinkedIn Integration: Unipile API provides LinkedIn profile data

Environment Variables

Backend Required:

• DATABASE_URL - PostgreSQL connection string
• SUPABASE_URL - Supabase project URL
• SUPABASE_ANON_KEY - Supabase anonymous key
• OPENAI_API_KEY - OpenAI API key
• STRIPE_SECRET_KEY - Stripe secret key
• UNIPILE_API_KEY - Unipile API key

Frontend Required:

• NEXT_PUBLIC_BACKEND_BASE_URL - Backend API URL
• NEXT_PUBLIC_SUPABASE_URL - Supabase project URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY - Supabase anonymous key

🚀 Deployment

Frontend (Netlify)

1. Build the project: npm run build && npm run export
2. Deploy the out folder to Netlify
3. Configure environment variables in Netlify dashboard

Backend (Vercel/Heroku)

1. Set up environment variables
2. Deploy using your preferred platform
3. Update frontend environment variables with production URLs

🔒 Security Features

• JWT-based authentication with role enforcement
• Supabase Auth integration
• CORS configuration
• Input validation and sanitization
• Rate limiting (recommended for production)
• Secure API key management

📊 Monitoring & Analytics

• Real-time job analysis tracking
• Candidate scoring and evaluation metrics
• Subscription and billing analytics
• User activity monitoring
• Performance metrics

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• Use ESLint configuration provided
• Follow existing code patterns
• Add comments for complex logic
• Update documentation for new features

📄 License

This project is proprietary software. All rights reserved.

🆘 Support

For support and questions:

• Create an issue in the repository
• Check the documentation
• Review the API endpoints

🗺 Roadmap

Upcoming Features

• Background job queue (Redis + BullMQ)
• Advanced analytics and reporting
• Mobile application
• Enhanced AI evaluation criteria
• Multi-tenant architecture
• Advanced candidate matching algorithms
• Integration with more job boards
• Video interview capabilities
• Automated reference checking
• Advanced reporting and insights

Technical Improvements

• Performance optimization
• Enhanced error handling
• Comprehensive testing suite
• API rate limiting
• Caching implementation
• Database optimization
• Security enhancements