ai-interview

# 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**
````mermaid
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**
````mermaid
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**
````mermaid
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 <User Name>”**

#### 📥 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.
- Issu

[truncated…]