Mock Interview Training System

Real-time mock interview platform where trainers control AI interviewer avatars to conduct practice interviews with candidates, featuring automatic recording, transcription, and AI-powered feedback generation.

Features

Live video interviews with AI text-to-speech interviewer
Real-time transcription using browser Web Speech API
Question bank with customizable templates
AI-powered performance feedback using Groq
WebRTC peer-to-peer video connection
Recording and playback capabilities
100% free for testing

Tech Stack

Frontend:

React with Vite
Tailwind CSS (black and white design)
WebRTC for peer-to-peer video
Zustand for state management
Axios for API communication

Backend:

Python FastAPI
WebSocket for real-time messaging
SQLite for database (testing), PostgreSQL (production)
SQLAlchemy ORM with async support

Key Services (All Free):

Text-to-Speech: Browser Web Speech API (built-in, zero cost)
Speech-to-Text: Browser Web Speech API (real-time, zero cost)
AI Feedback: Groq API (completely free, fast inference)
Video: WebRTC with Google STUN servers (free)

Quick Start

Prerequisites

Python 3.10+
Node.js 18+
Modern browser (Chrome recommended for best Web Speech API support)

Backend Setup

Navigate to the project directory:

cd mock-interview-system

Create a virtual environment and activate it:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install Python dependencies:

pip install -r requirements.txt

Create a .env file in the root directory:

DATABASE_URL=sqlite+aiosqlite:///./interviews.db
JWT_SECRET=your-secret-key-change-in-production
GROQ_API_KEY=your-groq-api-key-here
ALLOWED_ORIGINS=http://localhost:5173

Run the backend server:

python -m uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000 with interactive docs at http://localhost:8000/docs

Frontend Setup

Install Node.js dependencies:

npm install

Create a .env file in the frontend directory:

VITE_API_URL=http://localhost:8000
VITE_WS_URL=ws://localhost:8000

Start the development server:

npm run dev

The frontend will be available at http://localhost:5173

Get Groq API Key (Free)

Visit https://console.groq.com
Sign up for a free account
Generate an API key
Add it to your .env file

Usage

For Trainers/Admins:

Register an account at the login page
Log in to access the admin dashboard
Click "Create New Interview"
Select interview type (Technical, Behavioral, HR, System Design, Custom)
Choose duration (30, 45, or 60 minutes)
Share the generated room code with the candidate
Wait for the candidate to join
Click "Start Interview" when ready
Type questions in the text field and click "Speak" to have the AI interviewer speak them
Monitor the live transcript on the right side
Take private notes as needed
Use "Pause" to temporarily stop, "Resume" to continue
Click "End Interview" when finished to generate AI feedback

For Candidates:

Receive the room code from your interviewer
Visit the application and click "Join with room code"
Enter the room code (format: ABC-123)
Enter your full name
Allow camera and microphone access
Wait in the waiting room for the interview to start
Listen to the AI interviewer's questions (text-to-speech)
Answer verbally (speech-to-text will capture your responses)
Use the controls to mute/unmute or toggle camera if needed
Receive feedback after the interview ends

System Architecture

Two-PC Setup

PC A (Admin/Trainer): Controls the interview, types questions, sees live transcript, takes notes
PC B (Candidate): Joins via room code, sees/hears AI interviewer, gets interviewed
AI Interviewer Avatar: Speaks whatever admin types using browser text-to-speech
Post-Interview: Auto-generates detailed feedback using Groq AI

WebRTC Connection

Peer-to-peer video and audio between admin and candidate
Uses free Google STUN servers for NAT traversal
WebSocket for signaling (ICE candidate exchange)
Echo cancellation and noise suppression enabled
Auto-reconnect on disconnect with exponential backoff

Real-time Communication

WebSocket maintains persistent connections for each session
Message types: admin_question, candidate_response, transcript_update, webrtc_signal, session_control
Admin types question → WebSocket → Candidate receives → TTS plays
Candidate speaks → Browser STT → WebSocket → Updates transcript → Shows to admin

API Endpoints

Authentication

POST /api/auth/register - Register new admin account
POST /api/auth/login - Admin login
POST /api/auth/verify - Verify JWT token

Interview Management

POST /api/interview/create - Create new session and generate room code
POST /api/interview/join - Candidate joins with room code
GET /api/interview/{session_id} - Get session details
POST /api/interview/start - Start interview
POST /api/interview/pause - Pause interview
POST /api/interview/resume - Resume interview
POST /api/interview/end - End interview and trigger feedback generation
WS /api/interview/ws/{session_id}/{role} - WebSocket connection

Question Bank

GET /api/questions - Get all questions (with optional filters)
POST /api/questions - Create new question
PUT /api/questions/{id} - Update question
DELETE /api/questions/{id} - Delete question
GET /api/questions/templates - Get pre-built question templates

Feedback

POST /api/feedback/generate - Generate AI feedback using Groq
GET /api/feedback/{session_id} - Get feedback report

Transcript

GET /api/transcript/{session_id} - Get full transcript
POST /api/transcript/entry - Add transcript entry

Project Structure

mock-interview-system/
├── README.md
├── requirements.txt
├── package.json
├── .env.example
├── .gitignore
├── backend/
│   ├── __init__.py
│   ├── main.py                 # FastAPI app entry point
│   ├── config.py               # Configuration settings
│   ├── database.py             # Database connection and session
│   ├── models.py               # SQLAlchemy models
│   ├── websocket_manager.py    # WebSocket connection manager
│   ├── routes/
│   │   ├── __init__.py
│   │   ├── auth.py             # Authentication endpoints
│   │   ├── interview.py        # Interview session endpoints
│   │   ├── feedback.py         # Feedback generation endpoints
│   │   ├── questions.py        # Question bank endpoints
│   │   └── transcript.py       # Transcript endpoints
│   └── services/
│       ├── __init__.py
│       └── ai_feedback.py      # Groq AI feedback service
├── frontend/
│   ├── index.html
│   ├── src/
│   │   ├── main.jsx            # React entry point
│   │   ├── App.jsx             # Main app with routing
│   │   ├── index.css           # Tailwind CSS imports
│   │   ├── pages/
│   │   │   ├── Login.jsx       # Admin login/register
│   │   │   ├── AdminDashboard.jsx   # Admin interview control
│   │   │   ├── CandidateRoom.jsx    # Candidate interview view
│   │   │   └── FeedbackReport.jsx   # Feedback display
│   │   ├── components/
│   │   │   ├── VideoCall.jsx        # Video display component
│   │   │   ├── AIAvatar.jsx         # AI interviewer avatar
│   │   │   ├── AdminControls.jsx    # Admin control panel
│   │   │   ├── TranscriptPanel.jsx  # Live transcript display
│   │   │   └── Timer.jsx            # Interview timer
│   │   ├── hooks/
│   │   │   ├── useWebRTC.js         # WebRTC connection hook
│   │   │   ├── useWebSocket.js      # WebSocket connection hook
│   │   │   └── useTTS.js            # Text-to-speech hook
│   │   └── services/
│   │       ├── api.js               # API client
│   │       └── webrtc.js            # WebRTC service
│   └── vite.config.js
├── tailwind.config.js
├── postcss.config.js
└── tests/

Database Schema

Tables

users: Admin accounts

id, email, password_hash, role, created_at

interview_sessions: Interview sessions

id, session_id, room_code, admin_id, candidate_name, status, interview_type, started_at, ended_at, duration, recording_url

questions: Question bank

id, category, difficulty, text, expected_points, time_allocation, tags, created_by

interview_questions: Questions asked in specific interviews

id, session_id, question_id, question_text, asked_at, response_text, response_duration, admin_rating, admin_notes

transcripts: Interview transcripts

id, session_id, speaker, text, timestamp

feedback_reports: AI-generated feedback

id, session_id, overall_score, dimension_scores, strengths, improvements, detailed_feedback, recommendations

Design Guidelines

The UI follows a strict black and white design:

Background: Pure white (#FFFFFF)
Text: Pure black (#000000)
Secondary text: Dark gray (#333333)
Borders: Medium gray (#CCCCCC)
Disabled: Light gray (#999999)
Hover: Light gray background (#F5F5F5)
No colors except black, white, and grays
No emojis in the interface

Deployment

Frontend (Vercel - Free)

Push code to GitHub
Connect Vercel to repository
Set build command: npm run build
Set output directory: dist
Add environment variables: VITE_API_URL, VITE_WS_URL
Deploy

Backend (Railway - Free 500 hours/month)

Create Railway account
Connect GitHub repository
Set start command: uvicorn backend.main:app --host 0.0.0.0 --port $PORT
Add environment variables: DATABASE_URL, JWT_SECRET, GROQ_API_KEY, ALLOWED_ORIGINS
Deploy

Database

Testing: SQLite (included with Python)
Production: Neon PostgreSQL free tier (0.5GB storage)

Cost Analysis

Testing

Everything: $0

Production (up to 100 interviews/month)

Vercel hosting: $0
Railway hosting: $0 (500 free hours)
Neon PostgreSQL: $0 (free tier)
Groq AI: $0 (free)
WebRTC/STUN: $0 (free)
Web Speech API: $0 (browser built-in)

Total: $0-5/month for production use

Browser Compatibility

Best experience: Google Chrome (latest)
Supported: Edge, Safari, Firefox
Required features: WebRTC, Web Speech API (SpeechSynthesis, SpeechRecognition)

Troubleshooting

WebRTC connection fails

Ensure both parties allow camera/microphone access
Check firewall settings
Try using Chrome for better compatibility

Speech recognition not working

Use Chrome or Edge for best support
Ensure microphone permission granted
Check browser console for errors

Groq API errors

Verify API key is correct in .env
Check Groq API status at https://status.groq.com
Review API rate limits

WebSocket disconnects

Auto-reconnect should handle temporary issues
Check network stability
Verify backend is running

Future Enhancements

Screen sharing for technical interviews
Code editor integration for live coding
Calendar scheduling and email notifications
Mobile app for iOS/Android
Premium AI avatars with realistic voices
Advanced analytics and performance tracking
Multi-language support
Recording playback with timestamp navigation

License

MIT License - Feel free to use this for your mock interview training needs.

Support

For issues, questions, or contributions, please open an issue on the GitHub repository.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
backend		backend
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
ock.md		ock.md
package.json		package.json
postcss.config.js		postcss.config.js
requirements.txt		requirements.txt
tailwind.config.js		tailwind.config.js
vite.config.js		vite.config.js

zy1h0s/mock

Folders and files

Latest commit

History

Repository files navigation