🎙️ Socratis - AI-Powered Technical Interview Platform

A real-time AI interviewer that conducts live coding interviews with voice interaction, intelligent feedback, and performance-based assessment.

Features • Architecture • Quick Start • API Reference

---

✨ Features

🎯 Core Capabilities

• Real-time Voice Interview: Natural conversation with AI interviewer using WebRTC
• Live Code Editor: Monaco Editor with syntax highlighting and real-time code snapshots
• Intelligent Feedback: AI provides contextual hints without giving away solutions
• Performance Assessment: Agent evaluates and decides interview progression

🧠 AI-Powered Intelligence (V3 - Zero-Error Refactor)

• Real-Time Code Awareness: Implemented Chat Context Injection. The agent now "sees" every code change through explicit system updates, eliminating hallucinations.
• Dynamic Problem Agnosticism: Agent automatically adapts to any coding problem or asks the candidate for a description if missing.
• Selective Feedback: Only speaks when detecting bugs, approach changes, or when candidate is stuck.
• Socratic Method: Guides candidates through hints rather than giving answers.

📊 Forensic Evaluation & Reports

• Approach & Complexity: Strict Big-O analysis of algorithms and space/time.
• Code Correctness: Line-by-line identifies EVERY bug with formatted fixes (Line X: [Issue] -> [Fix]).
• Communication Analysis: Cites exact quotes from the transcript to evaluate clarity and professional tone.
• Hallucination Check: Cross-references candidate claims (e.g., "this is O(n)") against actual code implementation.
• Visual Score Radar: Professional result page with dimensional mapping.

---

🏗 Architecture

Unified Agent System

Socratis uses a unified python agent for seamless context and analysis:

Component	Technology	Purpose
Socratis Agent	Python, LiveKit, Groq (70B)	Real-time voice conversation, Socratic questioning, and Post-interview forensic analysis

┌─────────────────────────────────────────────────────────────────────────────┐
│                              SOCRATIS PLATFORM                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐     WebSocket      ┌──────────────┐                       │
│  │   Frontend   │◄──────────────────►│   Backend    │                       │
│  │  (Next.js)   │    REST API        │  (Express)   │                       │
│  │  Port 3000   │                    │  Port 4000   │                       │
│  └──────┬───────┘                    └──────┬───────┘                       │
│         │                                   │                                │
│         │ WebRTC                            │ MongoDB                        │
│         │ (Voice)                           ▼                                │
│         │                            ┌──────────────┐                       │
│         ▼                            │   Database   │                       │
│  ┌──────────────┐                    │   MongoDB    │                       │
│  │   LiveKit    │                    └──────────────┘                       │
│  │    Cloud     │                                                           │
│  └──────┬───────┘                                                           │
│         │                                                                    │
│         │ LiveKit Protocol                                                   │
│         ▼                                                                    │
│  ┌──────────────────────────────────────────────────────────────┐          │
│  │                    PYTHON VOICE AGENT                         │          │
│  ├──────────────────────────────────────────────────────────────┤          │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────────┐ │          │
│  │  │  VAD    │  │   STT   │  │   LLM   │  │      TTS        │ │          │
│  │  │ Silero  │  │Deepgram │  │  Groq   │  │    Deepgram     │ │          │
│  │  └─────────┘  └─────────┘  │Llama3.1 │  │  aura-helios    │ │          │
│  │                            └─────────┘  └─────────────────┘ │          │
│  └──────────────────────────────────────────────────────────────┘          │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Component Breakdown

Component	Technology	Purpose
Frontend	Next.js 14, React, TailwindCSS	Interview UI, Code Editor, Voice Controls
Backend	Express.js, TypeScript, MongoDB	Session Management, Evaluation API
Voice Agent	Python, LiveKit Agents SDK	Real-time voice conversation & Forensic Reporting
STT	Deepgram	Real-time speech-to-text
TTS	Deepgram (aura-helios-en)	Natural voice synthesis
LLM	Groq (Llama 3.3 70B)	High-intelligence inference for interviewing and reporting
VAD	Silero	Voice activity detection

---

🚀 Quick Start

Prerequisites

• Node.js 18+
• Python 3.8+
• MongoDB running locally or connection string
• API Keys: LiveKit, Groq, Deepgram

1. Clone & Install

# Clone the repository
git clone https://github.com/your-username/socratis.git
cd socratis

# Install backend dependencies
cd server && npm install

# Install frontend dependencies
cd ../client && npm install

# Install Python agent dependencies
cd ../server/agent && pip install -r requirements.txt

2. Configure Environment

Server .env (server/.env):

MONGODB_URI=mongodb://localhost:27017/socratis
GROQ_API_KEY=your_groq_api_key
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
LIVEKIT_URL=wss://your-project.livekit.cloud

Agent .env (server/agent/.env):

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
DEEPGRAM_API_KEY=your_deepgram_api_key
GROQ_API_KEY=your_groq_api_key

Client .env.local (client/.env.local):

NEXT_PUBLIC_LIVEKIT_URL=wss://your-project.livekit.cloud

3. Start Everything (One Command)

# From root directory - starts ALL services
python start.py

This single command starts:

• ✅ Backend Server (Port 4000)
• ✅ Frontend (Port 3000)
• ✅ Voice Agent (LiveKit)

📊 Monitoring & Debugging

Since services run in the background via the orchestrator, real-time logs are auto-generated in the root directory:

• backend.log: Express API and Database connection logs.
• frontend.log: Next.js compilation and routing logs.
• agent.log: LiveKit Agent events, LLM context injection, and voice pipeline details.

Note: These logs are essential for identifying port conflicts or API failures that occur without a visible console.

Press Ctrl+C to stop all services.

4. Open the App

Navigate to http://localhost:3000 to access the dashboard and start your interview!

---

📁 Project Structure

socratis/
├── client/                    # Next.js Frontend
│   ├── app/                   # App Router pages
│   │   ├── interview/[id]/    # Interview room & results
│   │   └── page.tsx           # Landing page
│   ├── components/            # React components
│   │   ├── interview/         # Interview-specific components
│   │   │   ├── InterviewRoom.tsx
│   │   │   ├── CodeEditor.tsx
│   │   │   └── VoiceComponent.tsx
│   │   └── CustomIcons.tsx    # SVG icons & score donut
│   └── hooks/                 # Custom React hooks
│
├── server/                    # Express.js Backend
│   ├── src/
│   │   ├── routes/
│   │   │   └── interview.ts   # Interview API endpoints
│   │   ├── models/
│   │   │   └── Session.ts     # MongoDB schema
│   │   └── services/          # Business logic
│   └── agent/                 # Python Voice Agent
│       ├── agent.py           # Main agent entrypoint
│       ├── deepgram_patch.py  # TTS compatibility fix
│       └── requirements.txt
│
└── README.md

---

🔌 API Reference

Session Management

Endpoint	Method	Description
/api/start	POST	Create new interview session
/api/session/:id	GET	Get session details
/api/submit	POST	Submit code for final evaluation
/api/submit-question	POST	Submit current question, advance to next
/api/advance-question	POST	Agent-triggered question advancement
/api/token	GET	Get LiveKit access token

Request/Response Examples

Start Session:

POST /api/start
Response: {
  "sessionId": "socratis-interview",
  "question": { "title": "Two Sum", "description": "...", "examples": [...] },
  "totalQuestions": 1,
  "currentQuestionIndex": 0
}

Submit for Evaluation:

POST /api/submit
Body: { "sessionId": "...", "code": "...", "transcript": [...] }
Response: {
  "status": "completed",
  "message": "Session submitted. Analysis pending."
}

Note: The actual feedback is generated asynchronously by the agent and saved to the session. The frontend polls /api/session/:id to display results.

---

🧪 Agent Behavior

Interview Protocol

The AI agent follows a structured interview approach:

1. Greeting: Introduces itself and the problem
2. Clarification: Ensures candidate understands requirements
3. Approach Discussion: Asks about planned algorithm & complexity
4. Code Review: Watches for bugs and approach changes
5. Completion: Reviews solution, asks follow-up questions

Feedback Triggers

Condition	Agent Action
Bug Detected	Asks guiding question about the issue
Approach Change	Acknowledges and asks about reasoning
60s Silent	Offers gentle hint
Code Complete	Asks about complexity & edge cases

Performance Assessment

Based on candidate performance, the agent decides:

• Strong Performance → Ends interview, no second question needed
• Mixed Performance → Advances to second question for fuller picture
• Weak Performance → Gives another chance with different problem

---

🔑 Getting API Keys

LiveKit Cloud

1. Go to cloud.livekit.io
2. Create a new project
3. Copy API Key, API Secret, and WebSocket URL

Groq

1. Go to console.groq.com
2. Generate an API key
3. Free tier includes generous limits

Deepgram

1. Go to console.deepgram.com
2. Create a new API key
3. Free tier includes $200 credit

---

🎨 UI Features

• Brivio Light Theme: Clean, professional design with cobalt blue accents
• Responsive Layout: Resizable panels for problem description and code editor
• Real-time Indicators: Speaking/listening status, question progress
• Score Visualization: Radar chart for multi-dimensional performance view

---

🛠 Development

Running Tests

# Backend tests
cd server && npm test

# Frontend tests
cd client && npm test

Building for Production

# Build frontend
cd client && npm run build

# Build backend
cd server && npm run build

---

📜 License

MIT License - See LICENSE for details.

---

👥 Contributors

Built with ❤️ by Vasu-devs

---

⬆ Back to Top