PREPLENS 🎓

A comprehensive interview preparation platform built with FastAPI and PostgreSQL, featuring AI-powered resume analysis, MCQ-based assessments, and mock interviews.

🌟 Features

1. User Authentication & Authorization

Secure JWT-based authentication
User registration and login
Password hashing with bcrypt
Token-based session management

2. MCQ Quiz System

Generate random quizzes with 10 questions from database
Multiple difficulty levels (Easy, Medium, Hard)
Category-based questions
Instant scoring and detailed feedback
Shows explanations for wrong answers
Stores results for progress tracking

3. AI-Powered Resume Analysis

Upload PDF resumes
Powered by Google Gemini AI (gemini-2.5-flash)
ATS (Applicant Tracking System) score calculation
Professional summary generation
Personalized improvement suggestions
Job-specific analysis

4. Interview Sessions

Mock interview tracking
Performance scoring
Session summaries

5. AI Voice Interview System

Real-time voice-based mock interviews
AI agent powered by OpenAI GPT-4
Dynamic question generation based on job role
Speech-to-text and text-to-speech integration
Natural conversation flow
Instant feedback and evaluation
Professional interview simulation

🛠️ Tech Stack

Backend

Framework: FastAPI
Database: PostgreSQL
ORM: SQLAlchemy 2.0
Authentication: JWT (python-jose), OAuth2, Passlib
Session Management: Redis (Token blacklisting for logout)
AI Integration:
- Google Generative AI (Gemini) for resume analysis
- OpenAI GPT-4 for voice interview agent
Voice Processing: OpenAI Whisper (Speech-to-Text), TTS (Text-to-Speech)
PDF Processing: pypdf
Environment: python-dotenv

Frontend

Framework: React 18
Build Tool: Vite
Styling: Tailwind CSS v4 with custom theme
HTTP Client: Axios
Routing: React Router DOM
State Management: React Context API

Database Schema

Users
MCQs (Multiple Choice Questions)
Results
Resume Analysis
Interview Sessions

📋 Prerequisites

Python 3.13+
Node.js 18+ and npm
PostgreSQL
Redis Server
Google Gemini API Key
OpenAI API Key (for voice interview feature)

🚀 Installation & Setup

Backend Setup

1. Clone the Repository

git clone https://github.com/abuzerexe/PREPLENS.git
cd PREPLENS

2. Set Up Virtual Environment

cd backend
python -m venv venv

# Activate virtual environment
# Windows:
.\venv\Scripts\Activate.ps1

# Linux/Mac:
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

Or install individually:

pip install fastapi
pip install uvicorn[standard]
pip install sqlalchemy>=2.0
pip install psycopg2-binary
pip install pydantic
pip install passlib
pip install bcrypt==4.0.1
pip install python-jose[cryptography]
pip install python-multipart
pip install google-generativeai
pip install pypdf
pip install python-dotenv
pip install redis
pip install openai
pip install swarm-ai

4. Configure Environment Variables

Create a .env file in the backend directory:

# Database Configuration
SQLALCHEMY_DATABASE_URL=postgresql://postgres:your_password@localhost:5432/preplens

# JWT Configuration
SECRET_KEY=your_secret_key_here
ALGORITHM=HS256

# Google Gemini API
GEMINI_API_KEY=your_gemini_api_key_here

# OpenAI API (for voice interview)
OPENAI_API_KEY=your_openai_api_key_here

To generate a SECRET_KEY:

python -c "import secrets; print(secrets.token_hex(32))"

Get Gemini API Key: Visit Google AI Studio to get your free API key.

Get OpenAI API Key: Visit OpenAI Platform to get your API key.

5. Set Up Redis

Make sure Redis is installed and running on your system:

Windows: Download and install from Redis Windows or use WSL

Linux/Mac:

# Install Redis
sudo apt-get install redis-server  # Ubuntu/Debian
brew install redis                  # macOS

# Start Redis
redis-server

Verify Redis is running:

redis-cli ping
# Should return: PONG

6. Set Up Database

Make sure PostgreSQL is running and create the database:

CREATE DATABASE preplens;

The application will automatically create tables on first run.

7. Run the Backend Server

cd backend
.\venv\Scripts\Activate.ps1
uvicorn main:app --reload

The API will be available at:

API: http://127.0.0.1:8000
Interactive Docs (Swagger): http://127.0.0.1:8000/docs
Alternative Docs (ReDoc): http://127.0.0.1:8000/redoc

Frontend Setup

1. Navigate to Frontend Directory

cd frontend

2. Install Dependencies

npm install

3. Configure Environment Variables (Optional)

Create a .env file in the frontend directory if you need to override the default API URL:

VITE_API_URL=http://localhost:8000

4. Run the Development Server

npm run dev

The frontend will be available at:

Frontend: http://localhost:5173 (or next available port)

🎨 Frontend Styling with Tailwind CSS

The frontend uses Tailwind CSS v4 with a custom design system. The styling approach includes:

Custom Theme Configuration

All custom colors and design tokens are defined using the @theme directive in src/App.css:

@theme {
  /* Primary Colors */
  --color-primary: #ff6b35;
  --color-primary-light: #ff8555;
  --color-primary-dark: #ff5015;
  
  /* Background Colors */
  --color-background: #fef7f4;
  --color-card: #fff9f6;
  
  /* Accent Colors */
  --color-purple: #8b5cf6;
  --color-purple-light: #a78bfa;
  
  /* Text Colors */
  --color-text-primary: #2d3748;
  --color-text-secondary: #718096;
  
  /* Custom Shadows */
  --shadow-warm: 0 4px 6px rgba(255, 107, 53, 0.1);
  --shadow-card: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
}

Key Features

Utility-First: All components use Tailwind utility classes
Custom Color Palette: Warm color scheme with orange primary (#ff6b35) and purple accents
Responsive Design: Mobile-first approach with responsive breakpoints
No External CSS Files: All styling handled through Tailwind utilities
Consistent Shadows: Custom shadow variables for depth and visual hierarchy

Development Notes

Uses @tailwindcss/vite plugin for optimal build performance
Tailwind v4 uses the @theme directive instead of tailwind.config.js
All color references use CSS custom properties (e.g., bg-primary, text-text-primary)
Components are fully styled with inline Tailwind classes

📚 API Endpoints

Authentication (`/auth`)

Register User

POST /auth/signup
Content-Type: application/json

{
  "username": "johndoe",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "password": "securepassword123"
}

Login

POST /auth/login
Content-Type: application/x-www-form-urlencoded

username=johndoe
password=securepassword123

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Logout

POST /auth/logout
Authorization: Bearer {token}

Response:

{
  "message": "Logged out successfully"
}

MCQ Quiz (`/user`)

Generate Quiz

POST /user/mcq
Authorization: Bearer {token}

Response:

{
  "questions": [
    {
      "id": 1,
      "question_text": "What is a primary key?",
      "options": ["Option A", "Option B", "Option C", "Option D"]
    },
    // ... 9 more questions
  ]
}

Submit Quiz

POST /user/submit
Authorization: Bearer {token}
Content-Type: application/json

{
  "answers": [
    {"mcq_id": 1, "selected_option_index": 2},
    {"mcq_id": 2, "selected_option_index": 0},
    // ... remaining answers
  ]
}

Response:

{
  "score": 85.5,
  "correct_answers": 8,
  "total_questions": 10,
  "answer_details": [
    {
      "mcq_id": 1,
      "question_text": "What is a primary key?",
      "selected_option_index": 2,
      "correct_option_index": 2,
      "is_correct": true,
      "explanation": "A primary key uniquely identifies each record...",
      "correct_option": "Option C"
    },
    // ... details for all questions
  ]
}

Get Quiz Results

GET /user/result
Authorization: Bearer {token}

Response:

[
  {
    "id": 1,
    "user_id": 1,
    "score": 8.0,
    "correct_answers": 8
  },
  // ... more results
]

Get Resume Analysis History

GET /user/resumeAnalysis
Authorization: Bearer {token}

Response:

[
  {
    "id": 1,
    "user_id": 1,
    "job_title": "Software Engineer",
    "ats_score": 87.5
  },
  // ... more analyses
]

Resume Analysis (`/resume`)

Analyze Resume

POST /resume/analyze
Authorization: Bearer {token}
Content-Type: multipart/form-data

job_title: Software Engineer
resume: [PDF file]

Response:

{
  "ats_score": 87.5,
  "summary": "Experienced software engineer with 5 years of full-stack development...",
  "improvements": [
    "Add more quantifiable achievements",
    "Include relevant technical certifications",
    "Optimize keywords for ATS systems"
  ]
}

Voice Interview (`/voice`)

Start Voice Interview

POST /voice/interview/start
Authorization: Bearer {token}
Content-Type: application/json

{
  "job_role": "Software Engineer"
}

Response:

{
  "session_id": "unique-session-id",
  "message": "Interview started",
  "first_question": "Tell me about yourself and your experience."
}

Submit Audio Response

POST /voice/interview/respond
Authorization: Bearer {token}
Content-Type: multipart/form-data

session_id: unique-session-id
audio: [audio file]

Response:

{
  "transcription": "I am a software engineer with 3 years of experience...",
  "next_question": "Can you describe a challenging project you worked on?",
  "audio_url": "/audio/response.mp3"
}

End Interview Session

POST /voice/interview/end
Authorization: Bearer {token}
Content-Type: application/json

{
  "session_id": "unique-session-id"
}

Response:

{
  "feedback": "Strong communication skills, demonstrated technical knowledge...",
  "score": 8.5,
  "suggestions": [
    "Provide more specific examples",
    "Elaborate on problem-solving approach"
  ]
}

🗂️ Project Structure

PREPLENS/
├── backend/
│   ├── agent/
│   │   └── agent.py          # OpenAI Swarm agent for voice interviews
│   ├── db/
│   │   ├── __init__.py
│   │   ├── database.py       # Database connection & session
│   │   └── models.py         # SQLAlchemy models
│   ├── router/
│   │   ├── __init__.py
│   │   ├── auth.py           # Authentication endpoints
│   │   ├── user.py           # MCQ quiz endpoints
│   │   ├── resume.py         # Resume analysis endpoints
│   │   └── interview_voice_simple.py  # Voice interview endpoints
│   ├── venv/                 # Virtual environment (not in git)
│   ├── .env                  # Environment variables (not in git)
│   ├── main.py               # FastAPI application entry point
│   ├── VOICE_INTERVIEW_GUIDE.md  # Voice interview documentation
│   └── test_voice_interview.html  # Testing interface
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Navbar.jsx              # Navigation component
│   │   │   └── VoiceInterviewComponent.jsx  # Voice interview UI
│   │   ├── context/
│   │   │   └── AuthContext.jsx         # Authentication state management
│   │   ├── pages/
│   │   │   ├── Login.jsx               # Login page
│   │   │   ├── Signup.jsx              # Registration page
│   │   │   ├── Dashboard.jsx           # Main dashboard
│   │   │   ├── Quiz.jsx                # MCQ quiz interface
│   │   │   ├── Results.jsx             # Quiz results page
│   │   │   ├── ResumeAnalysis.jsx      # Resume upload & analysis
│   │   │   └── VoiceInterview.jsx      # Voice interview page
│   │   ├── services/
│   │   │   └── api.js                  # Axios API configuration
│   │   ├── App.jsx                     # Main app component
│   │   ├── App.css                     # Tailwind theme & global styles
│   │   └── main.jsx                    # React entry point
│   ├── index.html                      # HTML template
│   ├── package.json                    # Frontend dependencies
│   ├── vite.config.js                  # Vite configuration
│   └── .env                            # Frontend env variables (optional)
├── requirements.txt          # Python dependencies
└── README.md

🔒 Security Features

Password Hashing: Bcrypt with automatic salt generation
JWT Tokens: Secure token-based authentication with 20-minute expiration
Token Revocation: Redis-based token blacklisting for secure logout
Environment Variables: Sensitive data stored in .env file
SQL Injection Protection: SQLAlchemy ORM with parameterized queries
CORS: Configurable cross-origin resource sharing

🤖 AI Features

Resume Analysis with Gemini AI

The system uses Google's Gemini 2.5 Flash model to:

Analyze resume content against job requirements
Calculate ATS compatibility scores
Generate professional summaries
Provide actionable improvement suggestions
Extract key skills and experiences

Voice Interview with OpenAI GPT-4

The AI-powered voice interview system features:

Intelligent Agent: OpenAI Swarm framework for dynamic conversation
Natural Language Processing: GPT-4 for understanding and generating responses
Speech Recognition: Whisper API for accurate audio transcription
Voice Synthesis: Text-to-speech for AI interviewer responses
Adaptive Questioning: Context-aware follow-up questions
Real-time Evaluation: Continuous assessment during the interview
Comprehensive Feedback: Detailed analysis with improvement suggestions

📊 Database Schema

Users Table

id (Primary Key)
email (Unique)
username (Unique)
first_name
last_name
hashed_password
is_active

MCQs Table

id (Primary Key)
question_text
category
difficulty
options (JSON array)
correct_option_index
explanation

Results Table

id (Primary Key)
user_id (Foreign Key)
score
correct_answers

Resume Analysis Table

id (Primary Key)
user_id (Foreign Key)
job_title
ats_score

Interview Sessions Table

id (Primary Key)
user_id (Foreign Key)
summary
score

🧪 Testing with Swagger UI

Start the server: uvicorn main:app --reload
Open http://127.0.0.1:8000/docs
Register a new user via /auth/signup
Login via /auth/login to get access token
Click "Authorize" button (🔒) at top right
Enter: Bearer {your_access_token}
Test all authenticated endpoints

🚧 Roadmap

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

⭐ Star this repo if you find it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
backend		backend
frontend		frontend
.gitignore		.gitignore
README.md		README.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

PREPLENS 🎓

🌟 Features

1. User Authentication & Authorization

2. MCQ Quiz System

3. AI-Powered Resume Analysis

4. Interview Sessions

5. AI Voice Interview System

🛠️ Tech Stack

Backend

Frontend

Database Schema

📋 Prerequisites

🚀 Installation & Setup

Backend Setup

1. Clone the Repository

2. Set Up Virtual Environment

3. Install Dependencies

4. Configure Environment Variables

5. Set Up Redis

6. Set Up Database

7. Run the Backend Server

Frontend Setup

1. Navigate to Frontend Directory

2. Install Dependencies

3. Configure Environment Variables (Optional)

4. Run the Development Server

🎨 Frontend Styling with Tailwind CSS

Custom Theme Configuration

Key Features

Development Notes

📚 API Endpoints

Authentication (/auth)

Register User

Login

Logout

MCQ Quiz (/user)

Generate Quiz

Submit Quiz

Get Quiz Results

Get Resume Analysis History

Resume Analysis (/resume)

Analyze Resume

Voice Interview (/voice)

Start Voice Interview

Submit Audio Response

End Interview Session

🗂️ Project Structure

🔒 Security Features

🤖 AI Features

Resume Analysis with Gemini AI

Voice Interview with OpenAI GPT-4

📊 Database Schema

Users Table

MCQs Table

Results Table

Resume Analysis Table

Interview Sessions Table

🧪 Testing with Swagger UI

🚧 Roadmap

🤝 Contributing

About

Resources

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages

Authentication (`/auth`)

MCQ Quiz (`/user`)

Resume Analysis (`/resume`)

Voice Interview (`/voice`)