This project is officially registered under nexus spring of code 2026.

SkillSphere AI

SkillSphere AI is an AI-powered full-stack platform that connects learning, skill evaluation, and career readiness in one ecosystem.

It helps:

• Students learn, practice, and become job-ready
• Tutors run live, interactive classes
• Recruiters discover skilled and better-matched candidates

The platform combines live classroom experiences with AI/ML-driven career tools such as resume analysis, job matching, interview practice, and performance tracking.

---

Project Vision

SkillSphere AI aims to simplify the path from learning to hiring by giving users practical, actionable insights at every stage:

• Learn skills in real-time
• Measure progress through dashboards
• Improve career assets (resume and interview performance)
• Connect capabilities to hiring needs

---

Core Features

1. Live Interactive Classrooms
   Real-time learning sessions with video, chat, and collaboration.

2. AI Resume Analyzer
   Resume scoring with improvement suggestions. (Route: /resume-analyzer)

   • Drag & Drop / clipboard paste upload
   • ATS score with detailed analysis dashboard
   • Missing keyword identification
   • Live PDF document preview

3. Resume vs Job Description Matcher
   ML-assisted comparison between candidate profile and role requirements.

   • Semantic Resume vs Job Description Matching — Embedding-based semantic similarity scoring using Hugging Face Inference API (all-MiniLM-L6-v2, free tier)
   • Complements keyword overlap with contextual alignment detection
   • Cosine similarity comparison for conceptually related phrases (e.g., "workflow orchestration" vs "pipeline automation")

4. AI Mock Interview System
   Interview practice with structured feedback for improvement.

5. Skill Tracking Dashboard
   Performance insights to help students and tutors track growth.

6. Secure Authentication & Email Verification
   OTP-based registration and password recovery system.

   • 6-digit email OTP verification
   • Secure Password Reset (Forgot Password) flow
   • Protection against user enumeration
   • OTP attempt limiting for security

---

Target Users

• Students: build skills, improve resumes, and prepare for jobs
• Tutors: teach and manage live learning experiences
• Recruiters: identify skilled candidates more efficiently

---

Project Goals

• Simplify the journey from learning to getting hired
• Provide AI-powered guidance for career growth
• Enable meaningful collaboration between learners and educators
• Keep the platform modular, scalable, and open-source friendly

---

Tech Stack

• Frontend: React.js
• Backend: Node.js + Express.js
• Database: MongoDB
• Intelligence Layer: AI/ML for resume analysis, matching, and recommendations

---

⚡ Quick Start (Unified Setup)

To simplify setup, you can now run the entire project using root-level scripts.

Install all dependencies

npm run install-all

Run the project (client + server together)

npm run dev

This will start:

• Frontend (client)
• Backend (server)

⚠️ Backend requires environment variables to run properly. Refer to the Environment Setup section below.

Scalable Folder Structure

The following structure keeps the project modular and easy to scale for new contributors:

SkillSphere-AI/
├── client/                          # React frontend (Vite)
│   ├── src/
│   │   ├── modules/                 # Feature-based modules (Auth, Resumes, etc.)
│   │   ├── shared/                  # Reusable UI components
│   │   └── services/                # API service layer
├── server/                          # Express backend
│   ├── src/
│   │   ├── modules/                 # Backend business logic by domain
│   │   ├── database/                # Mongoose models and connection
│   │   └── middleware/              # Auth, RBAC, and Upload handlers
├── ai-ml/                           # AI/ML intelligence layer
│   ├── evaluators/                  # Skill, Keyword, and Experience matchers
│   └── pipeline/                    # Unified analysis pipeline
├── docs/                            # Project documentation
└── ...                              # Configuration and root files

API Endpoints (Implemented)

• GET /health

• POST /api/auth/register (v2: now includes OTP verification)

• POST /api/auth/verify-email

• POST /api/auth/resend-otp

• POST /api/auth/forgot-password

• POST /api/auth/reset-password

• POST /api/auth/login

• POST /api/auth/logout

• GET /api/auth/me

• POST /api/resume/upload

• POST /api/resume/analyze (v2: uses latest-only upsert flow)

• GET /api/resume/me/latest: fetch user's latest parsed resume (no raw resumeText)

• GET /api/resume/result/:id

• GET /uploads/:filename

• POST /api/jobs: create a new job (Recruiter only)

• GET /api/jobs: list all published jobs (supports designation, minSalary, maxSalary, postedWithin filters)

• GET /api/jobs/recruiter: list jobs posted by the authenticated recruiter

• GET /api/jobs/:id: get job details

Why this structure works

• Feature-first design: Easier to assign and scale work across teams
• Clear boundaries: Frontend, backend, and AI/ML concerns are separated
• Contributor-friendly: New developers can quickly find where to work
• Future-ready: Supports adding new learning/career modules without major rewrites

---

## For Open-Source Contributors

If you want to contribute, start by understanding:

1. Which user group your change helps (student, tutor, recruiter)
2. Which module it belongs to (classrooms, resumes, matching, interviews, dashboard)
3. Whether the change impacts frontend, backend, AI/ML, or multiple layers

This approach keeps contributions focused, reviewable, and scalable.

---

## Contributor Resources

- Contribution Guide: `CONTRIBUTING.md`
- Code of Conduct: `CODE_OF_CONDUCT.md`
- Security Policy: `SECURITY.md`
- PR Template: `.github/PULL_REQUEST_TEMPLATE.md`
- Issue Templates: `.github/ISSUE_TEMPLATE/`
- Detailed Structure Notes: `docs/PROJECT_STRUCTURE.md`
- PR Quality Gates: `docs/QUALITY_GATES.md`

## PR Checks and Code Review Safety

Automated checks run on pull requests to `main` through:

- `.github/workflows/pr-quality-checks.yml`

These checks validate docs/workflows and, once app code is added, automatically run lint/test/build for `client`, `server`, and `ai-ml` when their dependency manifests exist.

## 🚀 Running the Project (Manual Setup)

### Client

```bash
cd client
npm install
npm run dev

Server

cd server
npm install
npm run dev

🔐 Environment Variables Setup

⚠️ The backend will not start without configuring the required environment variables.

Server

1. Copy example file:

cd server
cp .env.example .env

2. Update required values in server/.env:

• MONGO_URI
• JWT_SECRET
• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET

AI/ML Configuration (Required for semantic matching — free tier)

HF_API_TOKEN=your_hugging_face_token

🔐 Google OAuth Setup

• EMAIL_SERVICE_MODE=console (Use "smtp" for real emails)
• EMAIL_HOST=smtp.gmail.com
• EMAIL_PORT=587
• EMAIL_USER=your-email@gmail.com
• EMAIL_PASS=your-app-password
• EMAIL_FROM="SkillsSphere AI" <your-email@gmail.com>

Evaluator toggles and weights (optional)

EVALUATOR_SKILL_MATCH_ENABLED=true EVALUATOR_KEYWORD_MATCH_ENABLED=true EVALUATOR_EXPERIENCE_MATCH_ENABLED=true EVALUATOR_SKILL_MATCH_WEIGHT=1 EVALUATOR_KEYWORD_MATCH_WEIGHT=0.2 EVALUATOR_EXPERIENCE_MATCH_WEIGHT=0.2

Client

1. Copy example file:

cd client
cp .env.example .env

2. For local development, keep:

• MONGO_URI or MONGODB_URI
• PORT (backend default: 5000)
• JWT_SECRET (required for JWT registration)
• JWT_EXPIRES_IN (optional, default is 7d)
• HF_API_TOKEN (free — required for semantic resume-to-job-description matching, get at https://huggingface.co/settings/tokens)
• VITE_API_URL=http://localhost:5000

🔐 Google OAuth Setup

• JWT_SECRET=skillsphere_dev_jwt_secret_1234567890abcdef
• JWT_EXPIRES_IN=7d
• EMAIL_SERVICE_MODE=console (Use "smtp" for real emails)
• EMAIL_HOST=smtp.mailtrap.io
• EMAIL_PORT=2525
• EMAIL_USER=your_smtp_username
• EMAIL_PASS=your_smtp_password
• HF_API_TOKEN=hf_... (Free — required for semantic resume matching)

1. Open Google Cloud Console.
2. Create/select your project.
3. Configure OAuth consent screen.
4. Go to Credentials and create OAuth 2.0 Client ID (Web application).
5. Add Authorized redirect URI exactly as:

http://localhost:5000/api/auth/google/callback

6. Copy Client ID and Client Secret into server/.env:

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_CALLBACK_URL=http://localhost:5000/api/auth/google/callback
FRONTEND_URL=http://localhost:5174

7. Restart both backend and frontend after updating env files.

OAuth flow summary:

• Frontend starts OAuth from /api/auth/google.
• Google redirects to backend callback (GOOGLE_CALLBACK_URL).
• Backend creates JWT and redirects to frontend callback (FRONTEND_URL/auth/callback).

📧 Email SMTP Setup (Gmail)

To use real email notifications (OTP verification, password reset) via Gmail, follow these steps:

1. Enable 2-Step Verification: Go to your Google Account Security and ensure 2-Step Verification is ON.
2. Generate App Password:
   • Search for "App Passwords" in your Google Account search bar.
   • Enter a name (e.g., "SkillsSphere AI").
   • Click Create.
   • Copy the 16-character code (e.g., abcd efgh ijkl mnop).
3. Update server/.env:

   EMAIL_SERVICE_MODE=smtp
   EMAIL_HOST=smtp.gmail.com
   EMAIL_PORT=587
   EMAIL_USER=your-email@gmail.com
   EMAIL_PASS=abcd efgh ijkl mnop
   EMAIL_FROM="SkillsSphere AI" <your-email@gmail.com>

4. Restart the server to apply changes.