An intelligent interview preparation platform that helps job seekers practice interviews with AI-powered feedback and CV optimization suggestions.
- 📄 Document Analysis: Upload your CV (PDF, DOCX, TXT) and job descriptions.
- 🤖 AI-Powered Interviews: Engage in realistic mock interviews with adaptive questioning from multiple AI providers (Gemini, OpenRouter).
- 💡 Smart Feedback: Receive detailed performance analysis and actionable insights.
- ✨ CV Optimization: Get specific suggestions to tailor your CV for target roles.
- 📊 Progress Tracking: Monitor your interview progress with visual indicators.
- 🔒 Session Management: Resume incomplete sessions anytime.
- Python 3.11+
- An AI provider API key (e.g., Gemini - Get one here)
-
Clone the repository
git clone https://github.com/DanielPopoola/interview-simulator.git cd interview-simulator -
Set up environment
# Create virtual environment python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies pip install -r requirements.txt
-
Configure environment variables
# Copy example env file cp .env.example .env # Edit .env and add your API key(s) GEMINI_API_KEY=your_gemini_api_key_here OPENROUTER_API_KEY=your_openrouter_api_key_here SECRET_KEY=your_random_secret_key DATABASE_URL=sqlite:///instance/app.db
-
Run the application
flask run
-
Open your browser
http://127.0.0.1:5000
# Build and run with Docker Compose
docker-compose up --build
# Access at http://localhost:8000Start by entering the job title and company name you're preparing for.
- CV Upload: Upload your resume (PDF, DOCX, or TXT format).
- Job Description: Paste the full job posting.
- Answer up to 8 AI-generated questions tailored to your background and the role.
- Questions adapt based on your responses.
- Conversational, natural interview flow.
Receive comprehensive analysis including:
- Performance Score (1-10)
- Strengths: What you did well
- Areas to Improve: Specific suggestions
- CV Optimization: Tailored recommendations for the role.
┌─────────────────────────────────────────┐
│ Flask Application │
│ ┌──────────────────────────────────┐ │
│ │ Routes (app/routes) │ │
│ └──────────┬───────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────┐ │
│ │ Services Layer (app/services) │ │
│ │ • SessionService │ │
│ │ • DocumentService │ │
│ │ • InterviewService │ │
│ │ • FeedbackService │ │
│ └──────────┬───────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────┐ │
│ │ Repositories (app/repositories)│ │
│ │ • SessionRepository │ │
│ │ • MessageRepository │ │
│ │ • FeedbackRepository │ │
│ │ • FileRepository │ │
│ └──────────┬───────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────┐ │
│ │ Data Layer (app/models) │ │
│ │ • SQLite Database │ │
│ │ • SQLAlchemy ORM │ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────┘
│ │
↓ ↓
┌──────────┐ ┌──────────┐
│ AI Client│ │ HTMX │
│(client/) │ │ Frontend │
└──────────┘ └──────────┘
- Flask: Lightweight web framework
- SQLAlchemy: ORM for database operations
- SQLite: Development database
- Google Gemini & OpenRouter: Powers interview generation and feedback analysis.
- Provider Pattern: Easily switch between or add new AI providers.
- Tenacity: Retry logic for API reliability.
- HTMX: Dynamic interactions without complex JavaScript.
- Jinja2: Server-side templating.
- CSS: Custom styling with
main.css.
- pdfplumber: PDF text extraction
- python-docx: Word document parsing
interview-simulator/
├── app/
│ ├── __init__.py # App factory
│ ├── config.py # Configuration
│ ├── models.py # Database models
│ ├── exceptions.py # Custom exceptions
│ ├── services/ # Business logic
│ ├── repositories/ # Data access
│ └── routes/ # Flask routes
│
├── client/ # AI provider abstraction
│ ├── ai_client.py # Main AI client
│ ├── ai_provider.py # Provider protocol
│ ├── gemini_provider.py # Gemini implementation
│ └── openrouter_provider.py # OpenRouter implementation
│
├── utils/ # Utility modules
│ ├── document_parser.py # Document text extraction
│ └── prompt_templates.py # AI prompt templates
│
├── templates/ # HTML templates
│ ├── index.html
│ ├── upload.html
│ ├── interview.html
│ ├── feedback.html
│ └── fragments/ # HTMX partial templates
│
├── tests/ # Pytest test suite
├── wsgi.py # WSGI entry point
└── requirements.txt
# Run all tests
pytest
# Run with coverage
pytest --cov=app
# Run specific test file
pytest tests/test_interview_service.py- Services: Business logic and orchestration.
- Repositories: Database abstraction.
- Separation of Concerns: Each layer has a single responsibility.
- Server-side rendering keeps logic in Python.
- Minimal JavaScript complexity.
- Fast development with progressive enhancement.
AIProviderprotocol allows easy switching between AI services.- Currently supports Gemini and OpenRouter, and is easily extendable.
- Retry logic with exponential backoff.
- Single interface for multiple file formats.
- Graceful error handling for corrupted files.
- Flask sessions track user's interview sessions.
- No authentication required for MVP.
| Variable | Description | Default |
|---|---|---|
GEMINI_API_KEY |
Google Gemini API key | Optional |
OPENROUTER_API_KEY |
OpenRouter API key | Optional |
ACTIVE_PROVIDERS |
Comma-separated list of active providers | openrouter,gemini |
SECRET_KEY |
Flask session secret | dev-secret-key-change-in-production |
DATABASE_URL |
Database connection string | sqlite:///dev.db |
-- Users (optional, for future auth)
CREATE TABLE users (
id INTEGER PRIMARY KEY,
email VARCHAR(120) UNIQUE,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- Interview Sessions
CREATE TABLE sessions (
id INTEGER PRIMARY KEY,
user_id INTEGER REFERENCES users(id),
job_title VARCHAR(200) NOT NULL,
company_name VARCHAR(200) NOT NULL,
cv_text TEXT,
job_description_text TEXT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- Conversation Messages
CREATE TABLE messages (
id INTEGER PRIMARY KEY,
session_id INTEGER NOT NULL REFERENCES sessions(id),
role VARCHAR(20) NOT NULL, -- 'assistant', 'user'
content TEXT NOT NULL,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- Feedback Results
CREATE TABLE feedback (
id INTEGER PRIMARY KEY,
session_id INTEGER NOT NULL REFERENCES sessions(id),
interview_score INTEGER,
strengths TEXT,
weaknesses TEXT,
cv_improvements TEXT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);| Method | Endpoint | Description |
|---|---|---|
GET |
/ |
Homepage with recent sessions |
POST |
/session/create |
Create new interview session |
GET |
/session/<id>/upload |
Upload page for CV and job description |
POST |
/session/<id>/upload-cv |
Upload CV file |
POST |
/session/<id>/upload-job |
Submit job description |
GET |
/session/<id>/interview |
Interview interface |
POST |
/session/<id>/message |
Submit interview answer (HTMX) |
POST |
/session/<id>/complete |
Generate feedback |
GET |
/session/<id>/feedback |
View results |
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow PEP 8 style guidelines.
- Write tests for new features.
- Update documentation as needed.
- Run
ruff check .before committing.
This project is licensed under the MIT License.
- Google Gemini & OpenRouter for powering the AI capabilities.
- Flask community for excellent documentation.
- HTMX for simplifying frontend interactions.
Daniel Popoola - @iamuchihadan - iamuchihdadaniel236@gmail.com
Project Link: https://github.com/DanielPopoola/interview-simulator
Built with ❤️ to help job seekers succeed in their interviews