MockMate

Introduction

MockMate is an AI-powered interview practice platform that simulates real-world technical interviews. It features streaming question generation with incremental persistence, multi-turn follow-up conversations, structured answer evaluation, session recovery, resume-based project drilling, and trending news-based interview questions — all designed for a realistic and resilient interview experience.

Major Update: Resume Drill

MockMate 2.0.0 introduces Resume Drill, a focused "resume grilling" mode for project-based interview practice. Upload a PDF, TXT, or Markdown resume, let MockMate extract your project experience, then run a strict but constructive interview loop against each project.

Resume Drill Highlights

• Resume Upload and Parsing — Upload a resume directly in the training UI; MockMate extracts project entries and supporting evidence
• Project-by-project Drilling — Pick a parsed project and receive targeted questions about architecture, trade-offs, technical decisions, and real ownership
• Streaming Resume Questions — Resume drill questions and follow-ups stream through SSE for the same real-time interview feel as normal training
• Answer Evaluation — Each resume drill answer is evaluated with the existing structured scoring flow
• Draft Recovery — Active resume drill state is saved locally so you can refresh or return without losing progress
• Resume Management — Replace or delete the current resume from the UI when your experience changes

Key Features

• Streaming AI Questions — Real-time SSE streaming with background persistence; generation continues server-side even if you close the tab
• Multi-turn Follow-ups — AI probes deeper with follow-up questions based on your answers
• Resume Drill — Upload a resume and practice rigorous project-specific questioning based on your own experience
• Structured Evaluation — Scoring across technical accuracy, communication clarity, completeness, and practical experience
• Session Recovery — Refresh or return later; your interview session and questions are restored from the server
• News-based Questions — Trending tech news automatically generates relevant interview questions
• Configurable — Choose position, difficulty, question type, language, OpenAI model, and follow-up depth

Tech Stack

Layer	Technologies
Backend	Python 3.12+, FastAPI, async SQLAlchemy, SQLite, OpenAI Responses API
Frontend	React 19, TypeScript, Vite, Joy UI, Zustand, react-markdown
AI	OpenAI Responses API (default: gpt-5.4-mini, configurable per-request)
Scheduling	APScheduler (news fetching every 4h, cleanup every 24h)

Setup

Prerequisites

• Python 3.10+ (3.12 recommended)
• Node.js 18+ (20+ recommended)
• npm 10+
• uv (pip install uv if not installed)

Backend

cd backend
cp .env.example .env
uv venv
source .venv/bin/activate
uv sync

Edit .env and set your OPENAI_API_KEY. Alternatively, users can enter their own API key in the frontend UI.

For NEWS_FETCH_USER_AGENT, the default usually works. If news fetching fails, replace it with your browser's user agent.

Run in development mode

./run.sh  # uvicorn dev server on :5200 with --reload

API Documentation

Visit http://localhost:5200/docs for the interactive Swagger docs.

Frontend

cd frontend
cp .env.example .env
npm i

Run in development mode

npm run dev  # Vite dev server on :1314

Production Deployment

For Ubuntu server deployment, see DEPLOYMENT.md. A one-click update script is provided:

cd /root/mockmate/app
chmod +x update.sh
./update.sh

This will pull latest code, sync backend dependencies, restart the backend service, and rebuild frontend assets.

Database Maintenance

News data accumulates over time. A scheduled task cleans up expired data every 24h (default retention: 30 days). Manual cleanup:

cd backend

# Preview (no changes)
python cleanup_news.py --dry-run

# Clean up with default 30-day retention
python cleanup_news.py

# Custom retention
python cleanup_news.py --days 7

Set NEWS_RETENTION_DAYS in .env to change the default. The cleanup deletes expired news questions (skipping those used in sessions), expired news items, and runs SQLite VACUUM.

Architecture

See SYSTEM_ARCHITECTURE.md for the full system design, including:

• Directory layout and tech stack
• API endpoint reference (users, questions, answers, sessions, trending, resume)
• Streaming generation architecture (background thread + async flush task + SSE)
• Session recovery and follow-up conversation flows
• Resume drill upload, parsing, and project-question flow
• News processing pipeline and scheduled cleanup

For interactive documentation, visit this repo's DeepWiki.