🧠 InterviewLab – AI Voice Interview Practice

Mock Interviews with Role-Based Questions, Follow-Ups & Real-Time Coaching

This project is built for the Eightfold Interview Partner Assignment. It simulates a real interview using voice-based AI interviewer, follows up intelligently, handles confused/off-topic users, and finally gives detailed feedback & scores across communication, structure, technical knowledge, and confidence.

---

📌 Table of Contents

1. Overview
2. Features (Mapped to Assignment Requirements)
3. System Architecture
4. Technical Stack
5. Flow Diagram
6. Backend Architecture
7. Frontend Architecture
8. API Endpoints
9. Database Schema
10. Setup & Run Instructions
11. Demo Instructions

---

🚀 Overview

InterviewLab is a full-stack AI-powered mock interview simulator. Users:

1. Select a role, persona, and difficulty

2. Enter a voice-based interview room

3. Speak naturally while the AI interviewer:

   • Asks structured questions
   • Asks follow-ups
   • Handles confused/off-topic/over-chatty behavior
   • Evaluates each answer

4. At the end, users receive:

   • Overall score
   • Category scores
   • Strengths & improvements
   • Actionable next steps

The experience mimics Google Meet, with waveform animations & live transcript.

---

🎯 Features (Mapped to Assignment Requirements)

✔ 1. Mock interviews for role types

• Sales, Engineer, Retail, Product, and Custom role support
• Backend receives role & difficulty to generate tailored questions

✔ 2. Follow-up questions like a real interviewer

• Orchestrator agent decides:

  • followup
  • next_question
  • clarification
  • or end_due_to_completion

✔ 3. Voice-first interaction

• User speaks → Browser STT → Backend
• AI responds with TTS playback
• Animated waveform when speaking/thinking

✔ 4. Persona & Edge-case Handling

Backend detects and responds with friendly UI hints for:

• Confused user
• Chatty user
• Efficient user
• Off-topic user
• Invalid input
• Normal

The backend sends:

{
"edgeCaseLabel": "...",
"edgeCaseCommentForUi": "..."
}

✔ 5. Post-interview detailed evaluation

• Communication
• Structure (STAR)
• Technical Depth
• Confidence
• Strengths
• Improvements
• Next steps

✔ 6. Multiple interviews + results dashboard

• Interview history
• Resume unfinished interviews
• View full result breakdown

---

🏗 System Architecture

Frontend (React + Vite + Tailwind)
|
| voice -> STT -> API call
v
Backend (Node.js + Express)
|
| context → structured JSON
v
Gemini Orchestrator
|
| question/followup/evaluation
v
MongoDB (Session + Messages)

Components:

1. Frontend

• Voice capture + STT
• TTS playback
• InterviewRoom UI
• Dashboard + Results pages

2. Backend

• Session management
• AI Orchestrator
• AI Evaluator
• Message persistence
• Edge-case detection

3. AI Layer (Gemini 2.5 Flash)

• First question generator
• Orchestrator agent
• Evaluator agent

4. Database

• InterviewSession
• Message

---

🔧 Technical Stack

Frontend

• React + Vite
• Tailwind CSS (custom glowing theme)
• ShadCN UI
• Web Speech API (STT)
• HTML Audio API for TTS
• React Router for page navigation

Backend

• Node.js + Express
• MongoDB + Mongoose
• Gemini 2.5 Flash (via @google/genai)
• Modularized services architecture

---

🔄 Flow Diagram

Interview Flow

User selects role → Backend session created → First question generated
↓
User speaks → STT → sendMessage()
↓
Backend → Orchestrator →
followup | next_question | clarification | end
↓
AI reply → TTS playback
↓
Repeat until:
should_end == true
↓
Backend → Evaluator → Detailed scores
↓
Frontend → Results screen

---

🧩 Backend Architecture

1. Session creation

POST /api/interviews

• Stores role, difficulty, persona
• Generates first question
• Creates first Message

2. Main messaging loop

POST /api/interviews/:id/message

• Stores user's answer
• Fetches recent history
• Sends to Orchestrator
• Saves AI’s reply
• Returns JSON:

{
"type": "continue",
"aiReply": "...",
"questionIndex": 3,
"edgeCaseLabel": "chatty_user",
"edgeCaseCommentForUi": "Try keeping your answer more concise."
}

3. Evaluation

POST /api/interviews/:id/end or triggered automatically when planned questions complete.

Returns:

{
"overall_score": 78,
"category_scores": { ... },
"strengths": { ... },
"improvements": { ... },
"actionable_next_steps": [ ... ]
}

4. Result fetch

GET /api/interviews/:id

---

🗄 Database Schema

InterviewSession

{roleCategory: String,customRoleTitle: String,persona: String,difficulty: String,mode: String,numQuestionsPlanned: Number,currentQuestionIndex: Number,status: "in_progress"|"completed",overallScore: Number,categoryScores: { communication, structure, technical, confidence },strengths: {communication: [...], ... },improvements: {communication: [...], ... },nextSteps: [String],conversationSummary: String}

Message

{interviewId: ObjectId,from: "user"|"ai",type: "question"|"answer"|"followup",text: String,_meta: {
questionIndex,
replyType,
edgeCaseLabel,
edgeCaseCommentForUi
}}

---

⚙️ API Endpoints

1. Create interview

POST /api/interviews

2. Get all interviews

GET /api/interviews

3. Get single interview

GET /api/interviews/:id

4. Send message

POST /api/interviews/:id/message

5. End interview

POST /api/interviews/:id/end

---

🛠 Setup

📦 Docker Setup Guide:
See full instructions in Docker.md.

1. Clone

git clone https://github.com/TheCoderAdi/interviewlab
cd interviewlab

2. Backend

cd backend
npm install
cp .env.example .env
npm run dev

3. Frontend

cd frontend
npm install
npm run dev

Backend runs on http://localhost:4000 Frontend on http://localhost:5173