AI-powered mock interview platform with real-time feedback, adaptive questioning, and personalized scoring.
InterviewIQ simulates a full technical interview end-to-end — warmup conversation, adaptive questions, real-time follow-ups, and a scored evaluation report. The interviewer responds contextually to every answer, adjusts difficulty on the fly, and produces a rubric-based score with actionable feedback at the end.
Supported interview tracks: SWE, Behavioral, System Design, Data Science, DevOps/Cloud, Cybersecurity, Product Management.
| Layer | Technology |
|---|---|
| Backend | FastAPI, SQLAlchemy, Alembic, Python 3.11 |
| Frontend | Next.js 15, TypeScript, Tailwind CSS, Zustand |
| AI | DeepSeek (primary) + K2Think (fallback), streaming SSE |
| Database | PostgreSQL |
| Auth | JWT (httpOnly cookies + Bearer), refresh token rotation |
| TTS | ElevenLabs (primary) + browser fallback |
| RAG | Session embeddings + curated response examples |
| CI | GitHub Actions (lint + tests on every push) |
INTERVIEWPREP-APP/
├── backend/ # FastAPI app, services, migrations
│ ├── app/
│ │ ├── api/v1/ # Route handlers
│ │ ├── services/ # Interview engine, scoring, LLM, TTS
│ │ ├── models/ # SQLAlchemy models
│ │ ├── crud/ # Database operations
│ │ └── schemas/ # Pydantic schemas
│ ├── alembic/ # Database migrations
│ └── tests/ # 1000+ pytest tests
├── frontend-next/ # Next.js UI (primary)
├── data/
│ ├── questions/ # Question bank (JSON, by track/company/difficulty)
│ └── rubrics/ # Scoring rubrics per track
├── docs/ # Architecture, deployment, AI docs
│ └── audits/ # Engine audit reports
└── .github/workflows/ # CI pipeline
First time here? Follow the full step-by-step setup guide — it covers everything from installing Python to running both servers, with troubleshooting for common errors.
Prerequisites: Python 3.11+, Node 20+, a Supabase account (free)
git clone https://github.com/CephasTechOrg/INTERVIEWPREP-APP.git
cd INTERVIEWPREP-APPcd backend
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
cp .env.example .env # Fill in SECRET_KEY and DATABASE_URL
alembic upgrade head # Create database tables
python seed.py --questions # Load question bank
uvicorn app.main:app --reload # http://localhost:8000cd frontend-next
npm install
npm run dev # http://localhost:3000Copy backend/.env.example to backend/.env and fill in:
| Variable | Required | Description |
|---|---|---|
SECRET_KEY |
Yes | JWT signing secret |
DATABASE_URL |
Yes | PostgreSQL connection string |
DEEPSEEK_API_KEY |
Yes | Primary LLM provider |
K2THINK_API_KEY |
No | Fallback LLM (auto-used on DeepSeek failure) |
ELEVENLABS_API_KEY |
No | Text-to-speech |
SMTP_HOST / SMTP_* |
No | Email verification (prints to console if unset) |
# Backend (1017 tests)
cd backend
pytest --no-cov -q
# Frontend (53 tests)
cd frontend-next
npm run test:run
# Linting
cd backend && ruff check app/ tests/
cd frontend-next && npx tsc --noEmit- Adaptive interview engine — FSM-based stage machine (warmup → questions → followups → scoring), adjusts difficulty in real time based on answer quality
- Contextual AI interviewer — reacts to the specific content of each answer, not generic praise
- Multi-track support — coding, behavioral (STAR), system design, conceptual, and more
- RAG-enhanced context — retrieves similar past sessions and curated response examples to calibrate follow-up depth
- Streaming responses — SSE streaming for real-time interviewer replies and TTS
- Scoring + level calibration — rubric-based evaluation mapped to company tier (FAANG / Enterprise / Startup)
- Longitudinal profile — tracks weaknesses across sessions; injects chronic gaps into future interview prompts
- Local setup guide — step-by-step setup for new collaborators
- Architecture overview
- Deployment guide
- AI / interview engine
- Security
- Engine audit reports