1. InterVue Labs — Initial MVP Cleanup & Code Refactor Summary

This update finalizes the Initial MVP for the InterVue Labs AI Interview Simulator. We performed a complete cleanup, structural re-organization, and bug-fix pass to prepare the project for public testing and future feature releases.

Architecture🏗️

High level System Architecture

graph TB
    subgraph "Frontend - React"
        UI[User Interface]
        Audio[Audio System]
        State[State Management]
    end
    
    subgraph "Backend - FastAPI"
        API[API Layer]
        Orchestrator[Interview Orchestrator]
        Services[Intelligence Services]
    end
    
    subgraph "AI Services - OpenAI"
        GPT[GPT-4o-mini]
        TTS[Text-to-Speech]
        Embeddings[Embeddings API]
    end
    
    subgraph "Data Layer"
        DB[(PostgreSQL)]
        Cache[Audio Cache]
        QB[Question Bank]
    end
    
    UI -->|HTTP/JSON| API
    API -->|Coordinates| Orchestrator
    Orchestrator -->|Uses| Services
    Services -->|Calls| GPT
    Services -->|Generates| TTS
    Services -->|Creates| Embeddings
    Services -->|Reads/Writes| DB
    TTS -->|Saves| Cache
    Services -->|Selects| QB
    Cache -->|Serves| UI
    
    style UI fill:#3b82f6,color:#fff
    style Orchestrator fill:#8b5cf6,color:#fff
    style GPT fill:#10b981,color:#fff
    style DB fill:#f59e0b,color:#fff

Interview Flow - Complete Journey

graph TD
    Start([👤 You Start Interview]) --> Q1[🎤 AI Asks Question via Voice]
    
    Q1 --> A1[🗣️ You Answer Out Loud]
    
    A1 --> Process{🧠 AI Analyzes Your Answer}
    
    Process --> Store[💾 Saves Your AnswerRemembers Everything]
    
    Store --> Think{🤔 AI Thinks...}
    
    Think -->|Your Answer Was Great| Response1[✅ AI: 'Excellent example!'Moves to Next Question]
    
    Think -->|Your Answer Was Vague| Response2[❓ AI: 'Can you give more detail?'Asks Follow-up]
    
    Think -->|You Contradicted Earlier Answer| Response3[🤨 AI: 'Earlier you said X, now Y?'Asks for Clarification]
    
    Think -->|You Mentioned Topic 3 Times| Response4[🎯 AI: 'You love Python!'Asks Deep Technical Question]
    
    Response1 --> Generate[🤖 AI Creates Next QuestionBased on Your Conversation]
    Response2 --> Generate
    Response3 --> Generate
    Response4 --> Generate
    
    Generate --> Voice[🔊 Converts to Natural Voice]
    
    Voice --> Visual[🔵 Glowing Orb AppearsShows AI is Speaking]
    
    Visual --> Next[📢 You Hear Next Question]
    
    Next --> A1
    
    style Start fill:#e0f2fe,stroke:#0284c7,stroke-width:3px
    style Process fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Think fill:#f3e8ff,stroke:#a855f7,stroke-width:2px
    style Generate fill:#dcfce7,stroke:#16a34a,stroke-width:2px
    style Visual fill:#dbeafe,stroke:#3b82f6,stroke-width:2px

Project Structure

graph TD
    A["📦 InterVue Labs"]
    
    A --> B["📂 backend/"]
    B --> C["📄 api.py"]
    C --> D["📄 db.py"]
    D --> E["📄 models.py"]
    
    E --> F["📂 services/<br/>━━━━━━━━"]
    F --> F1["🧠 orchestrator"]
    F1 --> F2["❓ question_generator"]
    F2 --> F3["🎯 decision_engine"]
    F3 --> F4["💭 conversation_context"]
    F4 --> F5["🔍 contradiction_detector"]
    F5 --> F6["🔢 embedding_service"]
    F6 --> F7["⚡ realtime_response"]
    F7 --> F8["💬 personality"]
    F8 --> F9["🔊 tts_service"]
    F9 --> F10["📚 question_selector"]
    F10 --> F11["📄 job_introduction"]
    
    F11 --> G["📂 prompts/"]
    G --> H["📂 data/"]
    H --> I["📂 audio_cache/"]
    I --> J["📂 tests/"]
    
    A --> K["📂 frontend/"]
    K --> L["📂 src/"]
    L --> M["📂 pages/"]
    
    M --> M1["📄 Interview.jsx"]
    M1 --> M2["📄 Dashboard.jsx"]
    M2 --> M3["📄 Results.jsx"]
    
    M3 --> N["📂 components/Interview/"]
    
    N --> N1["🔵 GlowingOrb"]
    N1 --> N2["📊 ConversationIndicator"]
    N2 --> N3["💬 AIResponseDisplay"]
    N3 --> N4["❓ QuestionDisplay"]
    N4 --> N5["🎤 AnswerInput"]
    
    N5 --> O["🎨 index.css"]
    
    classDef root fill:#dbeafe,stroke:#3b82f6,stroke-width:3px
    classDef important fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    
    class A root
    class F,F1,F2,F9,M1,N1,N2 important

✅ Dual-Mode ATS Scoring (Core Feature)

🔹 Mode A — Resume Only

Evaluates general ATS readiness:

Searchability (contact info, links)
ATS essentials (sections, bullets)
Content quality (skills, metrics)
Recruiter best practices

🔹 Mode B — Resume + Job Description

Evaluates job match + readiness:

Hard skill overlap (Jobscan-style)
Responsibility alignment (Enhancv-style)
Seniority match
Missing keyword detection

➡️ ATS scores are deterministic, repeatable, and not random.

🛠️ Tech Stack

Backend:

Python 3.11+
FastAPI
PostgreSQL (Supabase)
OpenAI GPT-4o-mini
OpenAI TTS
Sentence Transformers

Frontend:

React 18
Vite
Tailwind CSS
Lucide Icons

AI Services:

Semantic embeddings (1536 dimensions)
Pattern detection
Contradiction analysis
Natural language generation

Database:

PostgreSQL (Supabase)

📂 Important Backend Files

File	Description
`api.py`	All API endpoints
`ats.py`	Deterministic ATS scoring logic
`models.py`	Database models
`db.py`	Database initialization
`ParseOut`	Strict response schema

▶️ Running the Project Locally

Backend

cd backend
python -m venv venv
.\venv\Scripts\activate.bat
pip install -r requirements.txt
uvicorn api:app --reload

Frontend

cd frontend
npm install
npm run dev

🚀 Features Overview

🔐 Authentication (New)

Secure Signup & Login flow
Password hashing using bcrypt
JWT-based authentication
Protected routes for authenticated users only
Logout functionality with session cleanup
Navbar displays “Logged in as ”

📥 PDF Download (New)

One-click Download Feedback as PDF
Client-side PDF generation using jsPDF
Includes:
- Interview metadata
- Overall score
- Strengths & improvements
- Question-level breakdown
No backend dependency for downloads

🧭 Routing & Access Control

Route	Access	Description
`/`	Public Gate	Redirects to login or home
`/login`	Public	Login page
`/signup`	Public	Signup page
`/home`	Protected	Main dashboard
`/resume-analysis`	Protected	Resume insights
`/interview`	Protected	Interview session
`/feedback`	Protected	Feedback & PDF download

Navbar and footer are rendered only on protected routes via a shared layout.

🔑 Authentication System (Signup, Login, Logout)

1. Signup Functionality

We implemented a complete user registration system using FastAPI on the backend and React on the frontend. What was added:

A dedicated Signup page with a clean, modern UI matching the app’s blue/white theme.
Form fields for Full Name, Email, and Password.
Client-side validation and loading states.
Backend endpoint /api/auth/signup.

Backend logic:

Validates password length (minimum 8 characters).
Enforces bcrypt’s 72-byte password limit to prevent runtime crashes.
Hashes passwords securely using passlib + bcrypt.
Generates a unique user ID using UUID.
Stores user credentials safely in the database.
Issues a JWT token upon successful signup.

Why this matters:

Prevents plain-text password storage.
Makes the platform safe for real users.
Lays the foundation for user-specific interview history and analytics.

2. Login Functionality

We added a secure login flow for returning users. What was added:

A Login page visually aligned with Signup.
Backend endpoint /api/auth/login.
JWT-based authentication.

Backend logic:

Verifies user email.
Compares entered password with the stored bcrypt hash.
Issues a new JWT token on success.

Frontend behavior:

Stores authToken and authUser in localStorage.
Redirects authenticated users to the main application.
Shows meaningful error messages for invalid credentials.

Why this matters:

Enables session-based access control.
Ensures only authenticated users can access interview features.

3. Logout Functionality

We implemented a clean and predictable logout mechanism, integrated directly into the navbar. What was added:

A Logout button in the navbar.

On click:

Clears authToken and authUser.
Clears cached interview/session data.
Redirects the user to the Login page.

Security behavior:

Once logged out, protected routes are immediately inaccessible.
Manual URL access to /home, /interview, etc. is blocked.

Why this matters:

Prevents stale sessions.
Ensures user privacy.
Required for any real-world, multi-user application.

4. Route Protection & Auth Gate

We refactored routing to behave like a real production app. Key changes:

Introduced an Auth Gate at /.
If logged in → redirect to /home
If not logged in → redirect to /login
Moved the actual dashboard to /home.
Protected all app routes using a ProtectedRoute wrapper.
Ensured Login and Signup pages do not show navbar/footer.

Why this matters:

First-time users always see Login/Signup.
Logged-in users get a seamless experience.
Prevents accidental access to protected pages.

5. Navbar Enhancements

We improved the navbar to reflect authentication state.

What was added:

Display text: “Logged in as ”
Reads user details from localStorage.
Responsive behavior (hidden on small screens).
Integrated Logout button.

Why this matters:

Confirms to the user which account they are using.
Adds polish and professionalism to the UI.

📥 PDF Download for Feedback (Major Feature)

6. Download Feedback as PDF

We added a one-click PDF export feature on the Feedback page.

What was added:

“Download PDF” button.
Client-side PDF generation using jsPDF and jsPDF-AutoTable.

PDF contents include:

Interview metadata (role, difficulty, date).
Overall interview score and summary.
Key strengths and improvement areas.
Question-by-question breakdown:
Question text
User answer
Scores
Strengths
Improvement suggestions

Why frontend PDF generation was chosen:

Faster user experience.
No backend load.
Works immediately in the browser.
No email or storage dependency.

Why this matters:

Users can save/share feedback.
Makes the app feel complete and professional.
Essential for real interview preparation tools.

🛠️ Major Fixes & Improvements Implemented

Authentication

Added Signup/Login/Logout
Fixed bcrypt version mismatch
Enforced password length constraints
Fixed UUID generation bug in models

CORS & Networking

Proper CORS middleware configuration
Fixed preflight (OPTIONS) failures
Ensured consistent localhost origins
Added global OPTIONS handler

Routing

Introduced Auth Gate at /
Separated public and protected routes
Fixed navbar/footer rendering via nested layout
Prevented unauthorized route access

Interview Flow

Fixed NEXT button behavior
Ensured answers save correctly
Prevented duplicate session inserts
Improved microphone reliability handling

Feedback

Fixed missing user answers in feedback
Improved scoring strictness
Added human-like feedback tone
Enabled PDF export

Route Protection & Auth Gate

We refactored routing to behave like a real production app. Key changes:

Introduced an Auth Gate at /.
If logged in → redirect to /home
If not logged in → redirect to /login
Moved the actual dashboard to /home.
Protected all app routes using a ProtectedRoute wrapper.
Ensured Login and Signup pages do not show navbar/footer.

Why this matters:

First-time users always see Login/Signup.
Logged-in users get a seamless experience.
Prevents accidental access to protected pages.

Known Constraints (Handled)

bcrypt 72-byte password limit enforced
Resume must be text-based PDF/DOCX
PDF generation is client-side (no email sending yet)

Future Enhancements

2 Way Commincation(Head Tracking, Eye Movement)
Profile page
Email PDF feedback
Interview history dashboard
Admin analytics
Pro subscription tiers
Server-side PDF generation
Real-time interview avatars

🧪 Test Suite

Test Coverage: 75%+

All new services have comprehensive test suites with proper mocking.

Test Files Created:

File	Test Cases	Description
`test_embedding_service.py`	14	Embedding generation, similarity calculation
`test_conversation_context.py`	14	Context building, topic extraction
`test_contradiction_detector.py`	13	Contradiction detection, follow-up generation
`test_semantic_search_api.py`	10	Search API endpoints
`test_answer_storage.py`	6	Answer submission and retrieval

🔧 Technical Decisions

1. Embedding Storage Strategy

Decision: Store as JSON string in TEXT column Rationale:

Supabase PostgreSQL supports JSON natively
No need for pgvector extension
Simpler deployment and migration
Adequate performance for session-scoped queries

2. Embedding Model Choice

Decision: text-embedding-3-small (1536 dimensions) Rationale:

Lower cost than ada-002
Better performance on retrieval tasks
Sufficient dimensionality for semantic search

3. Database-First Architecture

Decision: Store answers immediately, not at session end Rationale:

Enables real-time follow-up generation
Supports mid-interview analysis
Prevents data loss on browser close
Required for contradiction detection

4. Async Contradiction Detection

Decision: Use async functions with OpenAI Rationale:

Non-blocking API calls
Better performance for multiple similarity checks
Scales well with concurrent interviews

📊 Key Features

✅ Conversational Memory - Remembers entire interview
✅ Pattern Detection - Identifies contradictions and interests
✅ Voice Interaction - Natural TTS responses
✅ Adaptive Questioning - Adjusts based on answers
✅ Job Personalization - Tailored to job descriptions
✅ Visual Intelligence - See AI making connections

🔄 How It Works

User answers question → Stored with semantic embedding
AI analyzes → Quality, patterns, contradictions
Decision engine → Determines next action
Question generated → Contextual, intelligent
TTS converts → Natural voice response
Frontend displays → Visual + audio feedback

📈 Performance

Answer processing: <3 seconds
Audio generation: <2 seconds
Pattern detection: Real-time
Semantic search: <500ms

📌 Summary

Phase 1 and 1.2 establish the intelligent memory foundation for two-way interview communication:

Component	Purpose
Real-time Storage	Immediate answer persistence
Embeddings	Semantic understanding of answers
Semantic Search	Find relevant previous answers
Context Building	AI-ready conversation summaries
Contradiction Detection	Ensure interview consistency
Test Suite	75%+ coverage with proper mocking

The system is now ready for dynamic, context-aware interview experiences.

📜 License & Copyright

📖 Usage Rights

This project is available for:

✅ Educational purposes - Learn from the code
✅ Personal projects - Use for your own learning
✅ Portfolio reference - Cite in your work (with attribution)

⚠️ Restrictions

The following are NOT permitted without written authorization:

❌ Commercial use or integration into paid products
❌ Redistribution as your own work
❌ Creating competing commercial products
❌ Removing copyright notices

🤝 Attribution

If you reference this work, please credit:

InterVue Labs by Abhinay Lingala
Repository: [https://github.com/codexsys-7/ai-interview?tab=readme-ov-file]

📧 Contact

For licensing inquiries, collaborations, or commercial use:

📧 Email: abhinaylingala7@gmail.com

Author

Built and architected by Abhinay Lingala.

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

1. InterVue Labs — Initial MVP Cleanup & Code Refactor Summary

Architecture🏗️

High level System Architecture

Interview Flow - Complete Journey

Project Structure

✅ Dual-Mode ATS Scoring (Core Feature)

🔹 Mode A — Resume Only

🔹 Mode B — Resume + Job Description

🛠️ Tech Stack

📂 Important Backend Files

▶️ Running the Project Locally

🚀 Features Overview

🔐 Authentication (New)

📥 PDF Download (New)

🧭 Routing & Access Control

🔑 Authentication System (Signup, Login, Logout)

1. Signup Functionality

Backend logic:

Why this matters:

2. Login Functionality

Backend logic:

Frontend behavior:

Why this matters:

3. Logout Functionality

On click:

Security behavior:

Why this matters:

4. Route Protection & Auth Gate

Why this matters:

5. Navbar Enhancements

What was added:

Why this matters:

📥 PDF Download for Feedback (Major Feature)

6. Download Feedback as PDF

What was added:

PDF contents include:

Why frontend PDF generation was chosen:

Why this matters:

🛠️ Major Fixes & Improvements Implemented

Authentication

CORS & Networking

Routing

Interview Flow

Feedback

Route Protection & Auth Gate

Why this matters:

Known Constraints (Handled)

Future Enhancements

🧪 Test Suite

Test Coverage: 75%+

Test Files Created:

🔧 Technical Decisions

1. Embedding Storage Strategy

2. Embedding Model Choice

3. Database-First Architecture

4. Async Contradiction Detection

📊 Key Features

🔄 How It Works

📈 Performance

📌 Summary

📜 License & Copyright

📖 Usage Rights

⚠️ Restrictions

🤝 Attribution

📧 Contact

Author