🎮 IFA SkillQuest

Gamified Cognitive Assessment Platform for Modern Hiring

🚀 Live Demo • 📖 Documentation • 🎯 Features • ⚡ Quick Start

🌟 Overview

IFA SkillQuest is a next-generation hiring assessment platform that transforms traditional candidate evaluation through gamified cognitive testing. Our platform delivers sequential, timed challenges that measure risk assessment, spatial reasoning, logical sequencing, and domain knowledge—providing recruiters with actionable insights into candidate capabilities.

Built with modern web technologies and deployed on Vercel, SkillQuest offers role-based dashboards, real-time leaderboards, and comprehensive analytics while maintaining an engaging user experience through anti-cheating mechanisms and progressive game unlocking.

Why This Platform?

Feature	Description
🎯 Science-Backed Assessments	Games designed to measure specific cognitive skills (risk assessment, planning, optimization)
🔓 Progressive Unlocking	Sequential gating ensures candidates complete challenges in order, preventing cherry-picking
⏱️ Timed Challenges	5-minute windows per game create standardized evaluation conditions
📊 Rich Analytics	Detailed metrics including completion rate, error tracking, move optimization, and time analysis
🏆 Instant Leaderboards	Real-time ranking with tie-breaker logic and sortable columns
🛡️ Anti-Cheating Measures	Tab-switch detection with 3-strike disqualification and submission locking
👥 Multi-Role System	Separate workflows for applicants (assessment) and admins (analytics)
🚀 Production Ready	Serverless deployment, MongoDB Atlas cloud database, OAuth authentication

⚡ Quick Start

# Clone repository
git clone https://github.com/yourusername/skillquest-platform.git
cd skillquest-platform

# Backend setup
cd backend
npm install
echo "MONGODB_URI=your_mongodb_uri\nPORT=5000" > .env
npm run dev

# Frontend setup (new terminal)
cd ../frontend
npm install
echo "VITE_API_URL=http://localhost:5000/api\nVITE_GOOGLE_CLIENT_ID=your_client_id" > .env
npm run dev

📘 For detailed setup instructions, see Installation Guide and Environment Variables

🎬 Demo

📸 Screenshots (Click to expand)

Screenshots coming soon! Add images to docs/screenshots/ folder.

🎯 Features

🎮 Gamified Assessment Suite

Minesweeper - Risk assessment & deductive logic
- Progressive difficulty levels
- Mine hit tracking
- Flood-fill algorithm
Unblock Me - Spatial reasoning & planning
- 6x6 sliding block puzzles
- Move optimization tracking
- Progressive complexity
Water Capacity - Logical sequencing
- Classic liquid transfer puzzles
- Step optimization metrics
- Visual feedback system
Quiz Module - Domain knowledge testing
- Image-based questions support
- Randomized question ordering
- Instant scoring

🔐 Authentication & Roles

Google OAuth 2.0 integration
JWT-based session management
Multi-role support:
- 👤 Applicant - Take assessments, view scores
- 👑 Admin - Manage candidates, view analytics
- 🔒 Employee/Client - Placeholder (future)
Secure route protection

📊 Admin Dashboard

Real-time candidate monitoring
Comprehensive scorecards
Filterable/searchable data tables
Individual game performance drill-down
Bulk operations support
Export capabilities

🏆 Scoring & Leaderboard

Weighted scoring algorithm:
- Minesweeper: score × 5
- Unblock Me: score × 6
- Water Capacity: score × 3
- Quiz: score × 10
Multi-criteria tie-breaker logic
Sortable by score, time, college
Medal indicators for top performers
Completion timestamp tracking

🛡️ Anti-Cheating Mechanisms

Tab switch detection
3-strike disqualification system
One-time assessment submission
Sequential game unlocking
Server-side score validation
Timestamp verification

🔓 Progressive Unlocking System

Game Sequence:
1. Minesweeper (unlocked by default)
2. Unblock Me (unlocks after Minesweeper)
3. Water Capacity (unlocks after Unblock Me)
Trial mode available post-completion
Visual lock indicators
Completion tracking

📈 Analytics & Insights

Completion rates per game
Average scores and time analysis
Error rate tracking
Move/step optimization metrics
College-wise performance comparison
Location-based filtering

🛠️ Tech Stack

Frontend

Backend

Authentication & APIs

Deployment & Tools

📦 Complete Technology Breakdown

Backend Dependencies

Package	Purpose
`express`	Web application framework
`mongoose`	MongoDB ODM
`cors`	Cross-origin resource sharing
`dotenv`	Environment variable management
`jsonwebtoken`	JWT authentication
`express-rate-limit`	API rate limiting
`multer`	File upload handling
`openai`	AI integration
`xlsx`	Excel file parsing
`pdf-parse`	PDF document parsing
`mammoth`	DOCX file parsing

Frontend Dependencies

Package	Purpose
`react`	UI library
`react-router-dom`	Client-side routing
`@react-oauth/google`	Google authentication
`framer-motion`	Animation library
`lucide-react`	Icon library
`sonner`	Toast notifications
`fuse.js`	Fuzzy search
`date-fns`	Date manipulation
`class-variance-authority`	Variant management
`tailwind-merge`	Tailwind class merging

DevOps & Development

Tool	Purpose
Vite	Build tool & dev server
ESLint	Code linting
TypeScript	Type safety
PostCSS	CSS processing
Vercel CLI	Deployment

🏗️ Architecture

graph TB
    subgraph "Client Layer"
        A[React SPA] --> B[Auth Context]
        A --> C[Game Engines]
        A --> D[Admin Dashboard]
    end
    
    subgraph "API Layer"
        E[Express Server] --> F[CORS Middleware]
        E --> G[Rate Limiter]
        E --> H[Error Handler]
    end
    
    subgraph "Business Logic"
        I[Authentication Controller]
        J[Assessment Controller]
        K[Leaderboard Controller]
        L[Profile Controller]
    end
    
    subgraph "Data Layer"
        M[(MongoDB Atlas)]
        N[User Collection]
        O[Profile Collection]
        P[Assessment Collection]
    end
    
    A -->|REST API| E
    F --> I
    F --> J
    F --> K
    F --> L
    I --> M
    J --> M
    K --> M
    L --> M
    M --> N
    M --> O
    M --> P
    
    style A fill:#61DAFB
    style E fill:#339933
    style M fill:#47A248

Design Patterns

Pattern	Implementation	Benefit
MVC	Controllers handle business logic, Models define schemas, Views (React) render UI	Clear separation of concerns
Repository	Mongoose models abstract database operations	Database-agnostic business logic
Middleware Chain	CORS → Rate Limit → Auth → Routes → Error Handler	Modular request processing
Context API	AuthContext manages global user state	Avoid prop drilling
HOC Pattern	Route protection with authentication wrappers	Reusable auth logic
Serverless	Stateless API handlers compatible with Vercel	Horizontal scalability

📥 Installation

Prerequisites

Node.js 18+ (Download)
MongoDB Atlas Account (Sign up)
Google OAuth Credentials (Console)
Git (Download)

1️⃣ Clone Repository

git clone https://github.com/yourusername/skillquest-platform.git
cd skillquest-platform

2️⃣ Backend Setup

cd backend
npm install

Create .env file:

MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/ifahiring
VITE_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
PORT=5000
NODE_ENV=development
FRONTEND_URL=http://localhost:5173

Start backend:

npm run dev

Backend running at http://localhost:5000 ✅

3️⃣ Frontend Setup

cd ../frontend
npm install

Create .env file:

VITE_API_URL=http://localhost:5000/api
VITE_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com

Start frontend:

npm run dev

Frontend running at http://localhost:5173 ✅

🐳 Docker Setup (Optional)

# Build images
docker-compose build

# Start containers
docker-compose up -d

# Stop containers
docker-compose down

docker-compose.yml coming soon!

📋 Detailed Setup Instructions

MongoDB Atlas Configuration

Create cluster at MongoDB Atlas
Add IP whitelist: 0.0.0.0/0 (for development)
Create database user with read/write permissions
Copy connection string to MONGODB_URI

Google OAuth Setup

Go to Google Cloud Console
Create new project → Enable Google+ API
Create OAuth 2.0 credentials
Add authorized redirect URIs:
- http://localhost:5173
- https://your-frontend-domain.vercel.app
Copy Client ID to .env files

Verify Installation

# Backend health check
curl http://localhost:5000/api/health

# Expected response: {"status":"ok"}

⚠️ Common Issues & Fixes

Issue	Solution
Port already in use	Change `PORT` in backend `.env` or kill process: `lsof -ti:5000 \| xargs kill`
MongoDB connection failed	Verify whitelist IPs and connection string format
OAuth error	Ensure redirect URIs match exactly (including http vs https)
CORS errors	Check `FRONTEND_URL` in backend `.env` matches frontend URL
Module not found	Delete `node_modules` and `package-lock.json`, run `npm install` again

See docs/SETUP.md for comprehensive troubleshooting.

🎮 Usage

User Workflow

flowchart LR
    A[Visit Platform] --> B{Select Role}
    B -->|Applicant| C[Google OAuth Login]
    B -->|Admin| D[Google OAuth Login]
    C --> E[Complete Profile]
    E --> F[Start Minesweeper]
    F --> G{Completed?}
    G -->|Yes| H[Unlock Unblock Me]
    G -->|No| F
    H --> I[Complete Unblock Me]
    I --> J{Completed?}
    J -->|Yes| K[Unlock Water Capacity]
    J -->|No| I
    K --> L[View Scores]
    D --> M[Admin Dashboard]
    M --> N[View Leaderboard]
    M --> O[Manage Candidates]
    M --> P[Export Data]
    
    style C fill:#4285F4
    style F fill:#FF6B6B
    style H fill:#4ECDC4
    style K fill:#95E1D3

1️⃣ Applicant Journey

Sign Up & Profile Creation

Navigate to platform homepage
Click "Get Started as Applicant"
Authenticate with Google account
Complete profile form:
- Personal details (Name, Email, Phone)
- Academic info (College, CGPA)
- Career preferences (Location, Interested Roles)
- Upload resume (PDF/DOC)
- Provide Telegram ID
Receive unique Candidate ID (e.g., IFA-1738272315-A3B7)

Taking Assessments

Access applicant dashboard showing 3 game cards
Start with Minesweeper (only unlocked game initially)
Read game instructions in trial mode (optional)
Click "Start Challenge" to begin 5-minute timed assessment
Complete as many levels/puzzles as possible
Auto-submission when timer expires
Next game unlocks automatically
Repeat for Unblock Me and Water Capacity

View Results

Navigate to "My Scores" section
See individual game scores and total assessment score
Compare performance via leaderboard ranking

2️⃣ Admin Operations

Candidate Management

Login as Admin via Google OAuth
Access admin dashboard
View all registered candidates in filterable table
Search by name, college, location
Click candidate row for detailed scorecard
Export data to CSV/Excel (coming soon)

Leaderboard Analysis

View real-time leaderboard sorted by total score
Apply filters: College, Location, Completion Status
Sort by individual game scores or total assessment
Identify top performers with medal indicators

System Configuration

Adjust scoring multipliers (requires code change)
Manage question banks for quiz module
Upload new game puzzles

Configuration Parameters

Parameter	Type	Default	Description
`GAME_DURATION`	Integer	`300` (seconds)	Time limit per game
`TAB_SWITCH_LIMIT`	Integer	`3`	Maximum allowed tab switches
`MINESWEEPER_MULTIPLIER`	Float	`5.0`	Score weight for Minesweeper
`UNBLOCK_ME_MULTIPLIER`	Float	`6.0`	Score weight for Unblock Me
`WATER_CAPACITY_MULTIPLIER`	Float	`3.0`	Score weight for Water Capacity
`QUIZ_MULTIPLIER`	Float	`10.0`	Score weight for Quiz

⚙️ Advanced Configuration Options

Game Difficulty Tuning

Edit game configuration files:

frontend/src/components/games/Minesweeper.tsx (grid size, mine density)
frontend/src/components/games/UnblockMe.tsx (puzzle complexity)
frontend/src/components/games/WaterCapacity.tsx (jug capacity ranges)

Rate Limiting

Configure in backend/server.js:

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per windowMs
});

Database Indexing

Add indexes for performance:

// In respective model files
candidateIdIndex: true,
emailIndex: true,
googleIdIndex: true

📁 Project Structure

skillquest-platform/
│
├── backend/                        # Node.js Express backend
│   ├── server.js                   # Main entry point, server configuration
│   ├── package.json                # Backend dependencies
│   ├── vercel.json                 # Vercel deployment config
│   │
│   ├── server/
│   │   ├── config/
│   │   │   └── db.js              # MongoDB connection logic
│   │   │
│   │   ├── controllers/           # Business logic layer
│   │   │   ├── assessmentController.js      # Score submission & retrieval
│   │   │   ├── leaderboardController.js     # Ranking & tie-breaker logic
│   │   │   ├── profileController.js         # CRUD for candidate profiles
│   │   │   ├── userController.js            # User authentication & management
│   │   │   └── settingsController.js        # Admin configuration
│   │   │
│   │   ├── middleware/
│   │   │   └── errorHandler.js    # Global error handling middleware
│   │   │
│   │   ├── models/                # Mongoose schemas
│   │   │   ├── User.js            # User accounts (auth)
│   │   │   ├── Profile.js         # Candidate profiles
│   │   │   ├── Assessment.js      # Game scores
│   │   │   ├── QuestionBank.js    # Quiz questions repository
│   │   │   ├── QuestionGame.js    # Quiz game records
│   │   │   └── Settings.js        # Application settings
│   │   │
│   │   ├── routes/                # API endpoints
│   │   │   ├── users.js           # /api/users
│   │   │   ├── profiles.js        # /api/profiles
│   │   │   ├── assessments.js     # /api/assessments
│   │   │   ├── leaderboard.js     # /api/leaderboard
│   │   │   ├── questionBank.js    # /api/question-bank
│   │   │   ├── questionGame.js    # /api/question-game
│   │   │   └── settings.js        # /api/settings
│   │   │
│   │   └── services/
│   │       └── questionGenerator.js  # AI question generation service
│   │
│   └── scripts/                   # Utility scripts
│       ├── migrateImagesToBase64.js        # Image migration
│       ├── cleanupDatabase.js              # Database maintenance
│       └── extractExcelImages.js           # Excel image extraction
│
├── frontend/                       # React + TypeScript frontend
│   ├── index.html                  # Entry HTML file
│   ├── package.json                # Frontend dependencies
│   ├── vite.config.ts              # Vite build configuration
│   ├── tsconfig.json               # TypeScript configuration
│   ├── tailwind.config.js          # Tailwind CSS configuration
│   ├── vercel.json                 # Vercel deployment config
│   │
│   └── src/
│       ├── main.tsx                # React app entry point
│       ├── App.tsx                 # Root component with routing
│       ├── index.css               # Global styles
│       │
│       ├── components/
│       │   ├── auth/               # Authentication components
│       │   │   ├── Login.tsx
│       │   │   ├── RoleSelection.tsx
│       │   │   └── ProtectedRoute.tsx
│       │   │
│       │   ├── applicant/          # Applicant-facing components
│       │   │   ├── Dashboard.tsx
│       │   │   ├── ProfileForm.tsx
│       │   │   └── ScoreView.tsx
│       │   │
│       │   ├── admin/              # Admin dashboard components
│       │   │   ├── AdminDashboard.tsx       # Main admin view
│       │   │   ├── DashboardOverview.tsx    # Statistics overview
│       │   │   ├── CandidateInsights.tsx    # Candidate details
│       │   │   ├── QuestionBankManager.tsx  # Quiz management
│       │   │   ├── QuestionBankEdit.tsx     # Quiz editing
│       │   │   ├── QuestionBankUpload.tsx   # Bulk quiz upload
│       │   │   └── ManualQuizCreator.tsx    # Manual quiz creation
│       │   │
│       │   ├── games/              # Game engine components
│       │   │   ├── Minesweeper.tsx          # Minesweeper implementation
│       │   │   ├── UnblockMe.tsx            # Sliding block puzzle
│       │   │   ├── WaterCapacity.tsx        # Liquid transfer puzzle
│       │   │   └── QuestionGame.tsx         # Quiz game
│       │   │
│       │   └── ui/                 # Reusable UI components
│       │       ├── Button.tsx
│       │       ├── Card.tsx
│       │       ├── Modal.tsx
│       │       └── Spinner.tsx
│       │
│       ├── contexts/
│       │   └── AuthContext.tsx     # Global authentication state
│       │
│       ├── hooks/
│       │   └── useTabSwitchDetection.ts  # Anti-cheating hook
│       │
│       ├── lib/                    # Utility functions
│       │   ├── api.ts              # API client
│       │   ├── utils.ts            # Helper functions (scoring, etc.)
│       │   ├── chatbot-ai.ts       # AI chatbot integration
│       │   ├── fuzzy-search.ts     # Search utilities
│       │   └── storage.ts          # LocalStorage wrapper
│       │
│       ├── types/
│       │   └── index.ts            # TypeScript interfaces
│       │
│       └── config/
│           └── api.ts              # API configuration
│
├── docs/                           # Documentation
│   ├── DESIGN_DOCUMENT.md          # Comprehensive technical design
│   ├── PROJECT_SUMMARY.md          # Feature overview
│   ├── SETUP.md                    # Development setup guide
│   ├── SCORING_SYSTEM.md           # Detailed scoring algorithms
│   ├── GAME_UNLOCKING_FLOW.md      # Game progression logic
│   ├── VERCEL_DEPLOYMENT_GUIDE.md  # Deployment instructions
│   ├── ENV_VARIABLES_QUICK_REFERENCE.md  # Environment config
│   ├── QUESTION_BANK_GUIDE.md      # Quiz management guide
│   └── MOBILE_FULLSCREEN_FIX.md    # Mobile optimization notes
│
├── .gitignore                      # Git ignore patterns
├── LICENSE                         # MIT License
└── README.md                       # This file

📡 API Documentation

Base URL

Development: http://localhost:5000/api
Production: https://your-backend.vercel.app/api

Authentication

All protected endpoints require JWT token in headers:

Authorization: Bearer <token>

User Management

Endpoint	Method	Description
`/users/auth/google`	POST	Google OAuth authentication
`/users/:id`	GET	Get user by ID
`/users/:id`	PUT	Update user details
`/users/:id`	DELETE	Delete user account

Profile Management

Endpoint	Method	Description
`/profiles`	POST	Create candidate profile
`/profiles/:userId`	GET	Get profile by user ID
`/profiles/:userId`	PUT	Update profile
`/profiles`	GET	List all profiles (admin)

Assessment & Scoring

Endpoint	Method	Description
`/assessments`	POST	Submit game score
`/assessments/:userId`	GET	Get user's assessment
`/assessments/:userId/game/:gameName`	PUT	Update specific game score

Leaderboard

Endpoint	Method	Description
`/leaderboard`	GET	Get global leaderboard
`/leaderboard/top/:limit`	GET	Get top N performers
`/leaderboard/stats`	GET	Get aggregate statistics

Question Bank

Endpoint	Method	Description
`/question-bank`	POST	Create question
`/question-bank`	GET	List all questions
`/question-bank/:id`	PUT	Update question
`/question-bank/:id`	DELETE	Delete question
`/question-bank/upload`	POST	Bulk upload (Excel)

Example Requests

POST /assessments - Submit Score

// Request
POST /api/assessments
Content-Type: application/json
Authorization: Bearer <token>

{
  "userId": "user_12345",
  "gameName": "minesweeper",
  "score": 8,
  "timeSpent": 285,
  "metadata": {
    "levelsCompleted": 8,
    "minesHit": 2
  }
}

// Response
{
  "success": true,
  "assessment": {
    "userId": "user_12345",
    "minesweeper": { "score": 8, "timeSpent": 285 },
    "totalScore": 40,
    "updatedAt": "2026-01-30T10:30:00.000Z"
  }
}

GET /leaderboard - Fetch Rankings

// Request
GET /api/leaderboard?sortBy=totalScore&order=desc&limit=10

// Response
{
  "leaderboard": [
    {
      "rank": 1,
      "candidateId": "IFA-1738272315-A3B7",
      "name": "John Doe",
      "totalScore": 245,
      "collegeName": "MIT",
      "scores": {
        "minesweeper": 12,
        "unblockMe": 9,
        "waterCapacity": 15,
        "quiz": 8
      },
      "completedAt": "2026-01-30T12:45:00.000Z"
    }
    // ... more entries
  ],
  "total": 150
}

🚀 Deployment

Quick Deployment Options

🎯 Vercel (Recommended) - Detailed Guide
🐳 Docker - Containerized deployment (Docker Compose config coming soon)
☁️ AWS/GCP - Serverless functions or EC2/Compute Engine
🌐 Heroku - Traditional platform deployment

Vercel Deployment (Recommended)

1️⃣ Backend Deployment

cd backend
vercel --prod

Copy backend URL: https://your-backend.vercel.app

2️⃣ Frontend Deployment

cd frontend
vercel --prod

Copy frontend URL: https://your-frontend.vercel.app

3️⃣ Update Environment Variables

Backend (Vercel Dashboard):

MONGODB_URI=<your-mongodb-uri>
VITE_GOOGLE_CLIENT_ID=<your-client-id>
PORT=5000
NODE_ENV=production
FRONTEND_URL=https://your-frontend.vercel.app

Frontend (Vercel Dashboard):

VITE_API_URL=https://your-backend.vercel.app/api
VITE_GOOGLE_CLIENT_ID=<your-client-id>

4️⃣ Redeploy Backend (to apply FRONTEND_URL change)

cd backend
vercel --prod

5️⃣ Update Google OAuth Console

Add https://your-frontend.vercel.app to Authorized JavaScript Origins
Add https://your-frontend.vercel.app to Authorized Redirect URIs

Environment Variables

📋 Complete Environment Variable List

Backend (.env)

Variable	Required	Description	Example
`MONGODB_URI`	✅	MongoDB connection string	`mongodb+srv://user:pass@cluster.mongodb.net/db`
`VITE_GOOGLE_CLIENT_ID`	✅	Google OAuth Client ID	`123456-abc.apps.googleusercontent.com`
`PORT`	❌	Server port	`5000`
`NODE_ENV`	❌	Environment mode	`development` or `production`
`FRONTEND_URL`	✅	Frontend URL for CORS	`http://localhost:5173`
`JWT_SECRET`	❌	JWT signing secret	Auto-generated if not provided

Frontend (.env)

Variable	Required	Description	Example
`VITE_API_URL`	✅	Backend API base URL	`http://localhost:5000/api`
`VITE_GOOGLE_CLIENT_ID`	✅	Google OAuth Client ID	`123456-abc.apps.googleusercontent.com`

🧪 Testing

Backend Tests

cd backend
npm test                    # Run all tests
npm run test:watch          # Watch mode
npm run test:coverage       # Coverage report

Frontend Tests

cd frontend
npm test                    # Run all tests
npm run test:ui             # UI test runner
npm run test:coverage       # Coverage report

End-to-End Tests

npm run test:e2e            # Cypress E2E tests (coming soon)

📚 Documentation

Comprehensive guides available in docs/ folder:

Design Document - Complete technical architecture and system design
Project Summary - Feature overview and implementation status
Setup Guide - Step-by-step development environment setup
Scoring System - Detailed scoring algorithms and tie-breaker logic
Game Unlocking Flow - Progressive unlocking mechanism
Vercel Deployment - Production deployment instructions
Environment Variables - Configuration reference
Question Bank Guide - Quiz management documentation
Mobile Optimization - Mobile UI fixes

🗺️ Roadmap

✅ Completed Features

🚧 In Progress

Advanced analytics dashboard with charts
Email notification system
CSV/Excel export functionality
Docker containerization
Automated testing suite (unit + E2E)
Performance optimization (lazy loading, caching)

📅 Planned Features

AI-Powered Features
- AI-generated quiz questions
- Adaptive difficulty adjustment
- Candidate skill prediction
Enhanced Gaming
- Additional game types (Sudoku, Chess Puzzles)
- Multiplayer competitive mode
- Custom puzzle creation interface
Enterprise Features
- SSO integration (Okta, Auth0)
- White-label customization
- Multi-language support
- Advanced role management
Mobile App
- React Native mobile application
- Offline mode support
- Push notifications
Integration
- ATS system integrations (Greenhouse, Lever)
- Slack/Teams notifications
- Calendar scheduling
- Video interview integration

💡 Have a feature request? Open an issue with the feature-request label!

🤝 Contributing

We welcome contributions from the community! Whether it's bug fixes, new features, or documentation improvements, your input is valued.

How to Contribute

1️⃣ Fork the Repository

# Click "Fork" button on GitHub, then:
git clone https://github.com/YOUR_USERNAME/skillquest-platform.git
cd skillquest-platform

2️⃣ Create a Feature Branch

git checkout -b feature/amazing-feature

3️⃣ Make Your Changes

Write clean, documented code
Follow existing code style
Add tests for new features
Update documentation as needed

4️⃣ Commit Your Changes

git add .
git commit -m "feat: add amazing feature"

5️⃣ Push and Create PR

git push origin feature/amazing-feature
# Open Pull Request on GitHub

Contribution Guidelines

✅ Do's

Follow TypeScript best practices
Write meaningful commit messages
Add JSDoc comments for functions
Update relevant documentation
Test your changes locally
Keep PRs focused and atomic
Respond to review feedback promptly

❌ Don'ts

Commit directly to main branch
Include unrelated changes in PR
Submit incomplete features
Break existing functionality
Ignore linting errors
Add dependencies without justification
Push sensitive data (keys, tokens)

Development Setup

# Install dependencies
npm run install:all        # Install both frontend & backend

# Run in development
npm run dev:backend        # Start backend on :5000
npm run dev:frontend       # Start frontend on :5173

# Run concurrently (requires concurrently package)
npm run dev                # Start both servers

# Linting
npm run lint               # Check code style
npm run lint:fix           # Auto-fix issues

# Type checking
npm run type-check         # TypeScript validation

Commit Message Convention

We follow Conventional Commits:

feat: add new game type
fix: resolve scoring calculation bug
docs: update API documentation
style: format code with prettier
refactor: simplify leaderboard logic
test: add unit tests for assessment controller
chore: update dependencies

💬 Support

📖 Documentation - Check docs/ folder for comprehensive guides
🐛 Issues - Report bugs via GitHub Issues

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by the SkillQuest Team

⬆ Back to Top

Name		Name	Last commit message	Last commit date
.claude		.claude
backend		backend
docs		docs
frontend		frontend
.DS_Store		.DS_Store
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
test-quiz-content.txt		test-quiz-content.txt

Latest commit

History

Folders and files

Repository files navigation