ai-interviewer/README.md

AI Interviewer

A real-time AI-powered interview platform with audio streaming, face verification, and intelligent evaluation.

Architecture

ai_interview_assistant/
├── server/          # NestJS backend
│   └── src/
│       ├── candidate/     # Profile, resume upload, OCR
│       ├── face-auth/     # face-api.js face verification
│       ├── interview/     # WebSocket gateway, orchestrator, voice providers
│       └── brain/         # Cerebras LLM integration, evaluation
├── client/          # React + Vite frontend
│   └── src/
│       ├── components/    # Avatar
│       ├── pages/         # Onboarding, InterviewRoom
│       ├── hooks/         # useSocket, useAudioRecorder
│       └── services/      # REST API client
└── .env.example     # Environment variables template

Quick Start

1. Environment Setup

cp .env.example .env
# Fill in your API keys: DEEPGRAM_API_KEY, SARVAM_API_KEY, CEREBRAS_API_KEY

2. Backend

cd server
npm install
npm run start:dev    # http://localhost:3001

Note: face-api.js requires model weight files in server/face-models/. Download them from face-api.js models.

3. Frontend

cd client
npm install
npm run dev          # http://localhost:5173

4. MongoDB

Ensure MongoDB is running on localhost:27017 (or update MONGODB_URI in .env).

Tech Stack

Layer	Technology
Backend	NestJS, Mongoose, Socket.io, face-api.js
Frontend	React 19, Vite, TailwindCSS, socket.io
LLM	Cerebras (llama-4-scout)
STT/TTS	Deepgram (primary), Sarvam (fallback)
OCR	pdf-parse + tesseract.js
Database	MongoDB

Key Features

• Real-time audio streaming via WebSocket (Socket.io)
• Face verification on interview start (flag-only, non-blocking)
• Resume OCR supporting text PDFs and scanned images
• Stage-aware interviewing (Intro → Technical → Behavioral → Wrap-up)
• Structured evaluation with per-dimension ratings and reviews
• Swappable voice providers (Deepgram ↔ Sarvam via env config)