Skip to content

README.md

Latest commit

 

History

History
334 lines (249 loc) · 12.7 KB

README.md

File metadata and controls

334 lines (249 loc) · 12.7 KB

Interview Simulator Logo

🎙️ AI Interview Simulator

Practice job interviews with a real-time AI interviewer powered by Google Gemini

Features • Quick Start • Documentation • Tech Stack • Contributing

Java 25 Spring Boot 4.0.0 PostgreSQL Gemini AI License: GPL v3

✨ Features

🎤 Real-Time Voice Conversation

Have natural, bidirectional voice conversations with an AI interviewer using Google's Gemini Live API. No typing required - just speak!

📄 CV/Resume Integration

Upload your PDF or DOCX resume. The AI uses it to ask personalized questions about your experience and projects.

🌍 Multi-Language Support

Interview in English or Bulgarian. The AI adapts its questions and speech to your chosen language.

🎭 4 Interviewer Voices

Choose from 4 distinct AI voices:

  • 👨 George/Георги (Algieba)
  • 👩 Victoria/Виктория (Kore)
  • 👨 Max/Макс (Fenrir)
  • 👩 Diana/Диана (Despina)

📊 AI-Powered Grading

Get detailed performance feedback after each interview:

  • Overall, Communication, Technical, & Confidence scores
  • Strengths & areas for improvement
  • Verdict: STRONG HIRE / HIRE / MAYBE / NO HIRE

📋 Interview History

Your past interviews are automatically saved in your browser. Visit /history to see a full table of your sessions from the last 14 days — with scores, verdicts, and links back to each report. No account needed.

🔗 Shareable Results

Every report page has a Copy Link button. Share your interview results directly with friends, mentors, or recruiters.

🎯 Difficulty Levels

Level Style Best For
😌 Chill Relaxed, CV-focused conversation Beginners, confidence building
⚖️ Standard Balanced technical + soft skills General interview prep
🔥 Stress High-pressure, deep technical Senior roles, tough companies

⏱️ Interview Length Modes

Mode Typical Duration Question Scope
⚡ Quick 2-3 min 2-3 focused questions
🧭 Standard 5-8 min 4-6 balanced questions
🏁 Marathon 10-15 min 8-12 in-depth questions

🎙️ Push to Talk

During an interview, click the Settings button (⚙️ next to the status badge) to switch between two input modes:

Mode How it works
Free Talk Mic toggle button controls recording (default)
Push to Talk Hold a keyboard shortcut to record; release to send

Default shortcut is Ctrl+D — changeable to Ctrl+Space, Ctrl+M, Ctrl+Shift+M, Ctrl+Shift+D, or F9. Preference is saved to browser storage.

💼 Position-Specific Questions

The AI tailors questions to your target role:

  • Java/Backend Developer → OOP, Spring Boot, databases, API design
  • Frontend Developer → HTML/CSS/JS, React/Vue/Angular, UX
  • QA Engineer → Testing methodologies, automation, SDLC
  • DevOps Engineer → CI/CD, cloud, containerization
  • Project/Product Manager → Leadership, planning, stakeholders

🚀 Quick Start

Option 1: Docker (Recommended)

# Clone the repository
git clone https://github.com/dkirichev/interviewSimulator.git
cd interviewSimulator

# Start with Docker Compose
docker-compose up -d

# Open in browser
open http://localhost:8080

👉 See Docker Deployment Guide for detailed instructions.

Option 2: Local Development

Prerequisites:

  • Java 25+
  • PostgreSQL 14+
  • Maven 3.9+
  • Gemini API Key (free from Google AI Studio)
# Clone and navigate
git clone https://github.com/dkirichev/interviewSimulator.git
cd interviewSimulator

# Set up environment variables
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=interview_simulator
export DB_USERNAME=postgres
export DB_PASSWORD=your_password
export GEMINI_API_KEY=your_api_key
export APP_MODE=DEV

# Build and run
./mvnw spring-boot:run

👉 See Local Setup Guide for detailed instructions.

📖 Documentation

Document Description
📋 Local Setup Guide Complete local development setup
🐳 Docker Guide Production deployment with Docker
🏗️ Architecture System design, privacy model, and admin panel
🔌 API Reference REST and WebSocket endpoints
🤝 Contributing How to contribute to the project

🛠️ Tech Stack

Spring
Spring Boot 4 		Java
Java 25 		PostgreSQL
PostgreSQL 		Gemini
Gemini AI 		Thymeleaf
Thymeleaf 		Docker
Docker

Backend:

  • Spring Boot 4.0.0 with WebSocket/STOMP
  • Spring Security
  • Flyway database migrations
  • OkHttp for Gemini WebSocket client
  • Apache PDFBox & POI for CV parsing
  • Thymeleaf for server-side templating

Frontend:

  • Vanilla JavaScript (minimal, ~1,500 lines)
  • Thymeleaf templates with i18n support
  • Tailwind CSS (compiled locally with Tailwind CLI)
  • Web Audio API for audio capture/playback

AI:

  • Gemini 2.5 Flash (real-time audio conversations)
  • Gemini 3 Flash (interview grading)

🔧 Application Modes

Mode API Key Use Case
DEV Backend provides key Local development, testing
PROD User provides own key Production deployment
REVIEWER Multi-key rotation (server) Competition judges, demos

In PROD mode, users are prompted to enter their free Gemini API key. This keeps hosting costs at zero while giving each user their own rate limits.

In REVIEWER mode, the API key modal is hidden and the server uses multiple pre-configured keys with automatic model fallback rotation. This is designed for competition judges who shouldn't have to set up API keys.

🔒 Privacy & Security

This project is built with a privacy-by-design philosophy:

Principle Implementation
No user accounts Users are never required to register or create accounts — minimizing collected personal data
No CV/resume storage Uploaded CV files are parsed for text in-memory and immediately discarded. The file is never saved to disk or database
No audio storage Voice recordings are streamed in real-time and never persisted
No transcript retention Interview transcripts are not permanently stored — they exist only during the session for grading purposes
No API key persistence on server In PROD mode, API keys may pass through backend memory for active Gemini sessions, but are never persisted to database or disk
Automatic data cleanup A scheduled task runs every 6 hours and deletes all interview session reports older than 14 days
Mobile device blocking Mobile phones and tablets are redirected away from the app via a server-side interceptor — a professional interview requires a desktop environment with a proper microphone
Mode-aware legal pages Privacy Policy and Terms & Conditions adapt their content based on the app mode (DEV/PROD/REVIEWER), so users only see information relevant to their context

Hardening details

  • Per-IP rate limiting on WebSocket handshakes, interview starts, CV uploads, admin login, and admin password changes. Buckets are evicted every 10 min so the in-memory map cannot grow unbounded.
  • Strict input sanitization on candidate name, position, and CV text — strips HTML, JavaScript, SQL fragments, LLM prompt-control tokens ([END_INTERVIEW], [system|user|assistant]), and prompt-injection lead-ins (English + Bulgarian).
  • Bounded grading thread pool (2→4, queue 32, caller-runs) so a flood of ended interviews cannot fork unbounded threads.
  • Hardened CSP (no unsafe-eval, object-src 'none', base-uri 'self', form-action 'self', frame-ancestors 'none').
  • Session cookies are HttpOnly, SameSite=Lax, and Secure by default. For local plain-HTTP dev, set SESSION_COOKIE_SECURE=false.
  • Reverse-proxy IP trust is off by default. Behind a trusted proxy (Cloudflare Tunnel, nginx, load balancer) set APP_TRUST_FORWARDED_HEADERS=true so per-IP rate limits use the real client IP. The resolver prefers CF-Connecting-IP (spoof-proof — Cloudflare overwrites at the edge) and falls back to the leftmost X-Forwarded-For entry.
  • Actuator exposes only /actuator/health (used by the Docker HEALTHCHECK); no other endpoints are reachable.
  • Hibernate ddl-auto=validate — schema is owned by Flyway; the app never mutates DDL at runtime.

🛡️ Admin Panel

The application includes a password-protected admin panel at /admin:

  • Dashboard with interview session statistics (total sessions, today's sessions, average score, top position)
  • Session browser with filtering by position, difficulty, and language
  • Pagination for navigating through sessions
  • Password management — change the admin password from the dashboard

⚠️ Default admin credentials:
Username: admin
Password: noit2026P4$$

Change this immediately after first login via the admin dashboard password change form.

The admin panel is secured via Spring Security with form-based authentication at /admin/login.

🖥️ Screenshots

Coming soon - screenshots of the setup wizard, interview screen, and report page

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

  • 🐛 Reporting bugs
  • 💡 Suggesting features
  • 🔧 Submitting pull requests
  • 📝 Code style guidelines

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

This means you can:

  • ✅ Use the software for any purpose
  • ✅ Change the software to suit your needs
  • ✅ Share the software with anyone
  • ✅ Share the changes you make

As long as you:

  • 📋 Include the original license
  • 📋 State significant changes made
  • 📋 Make source code available when distributing

🙏 Acknowledgements

Made with ❤️ for interview prep enthusiasts

⭐ Star this repo • 🐛 Report Bug • 💡 Request Feature