# 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

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

### 2. Backend

```bash
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](https://github.com/justadudewhohacks/face-api.js/tree/master/weights).

### 3. Frontend

```bash
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)