# shiv0112/ai-interviewer architecture

> Architecture diagram of the GitHub repository shiv0112/ai-interviewer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shiv0112/ai-interviewer
- Repository: https://github.com/shiv0112/ai-interviewer

## Overview

##### Project type and purpose
- This is a full-stack AI Interviewer application.
- Frontend: Streamlit UI for users to select interview mode and upload files.
- Backend: FastAPI service exposing chat endpoints.
- Core logic: LangChain-based “chains” that drive conversations in four modes (role-based, JD-based, resume-based, hybrid).
- Data stores: Vector DB (Qdrant/FAISS/Chroma), file uploads, logs.
- External services: LLM API (e.g., OpenAI), PDF parsing.

##### File structure
- main.py: boots FastAPI, includes routers.
- app/
- chains/: definitions of the four ConversationChains.
- memory/: session managers that back each chain with message history or RAG contexts.
- prompts/: text templates for LLM inputs and evaluation.
- routers/: HTTP endpoints (/chat/role, /chat/jd, /chat/resume, /chat/hybrid, /status).
- schemas/: Pydantic request/response models.
- config/: settings loader for environment variables.
- utils/: logger setup and PDF loader.
- data/: persistent storage for uploaded files, logs, vectorstore.
- qdrant_db/: orchestrates the vector DB.
- frontend/streamlit_app.py: React-style Streamlit interface driving user interactions.

##### README for additional insights
- Clear user flows for four interview modes.
- Architectural notes: RAG for resume-based mode, pure prompt for role/JD modes, hybrid combines both.
- Dependencies: FastAPI, LangChain, Pydantic, Streamlit, vectorstore client.

##### Final pointers
- Call out major code modules by name (e.g., role_based_chain.py, hybrid_sessions.py).
- Special flows: RAG retrieval for resume/hybrid modes vs. direct prompting for role/JD modes.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction
    User(("User")):::external
    User -->|"interacts"| UI

    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["Streamlit UI"]:::frontend
    end

    %% API Server Layer
    subgraph "API Server (FastAPI)" 
        APIServer["API Server<br/>(main.py)"]:::backend
        subgraph "Routers"
            R1["Role-Based<br/>(/chat/role)"]:::backend
            R2["JD-Based<br/>(/chat/jd)"]:::backend
            R3["Resume-Based<br/>(/chat/resume)"]:::backend
            R4["Hybrid<br/>(/chat/hybrid)"]:::backend
            R5["Status<br/>(/status)"]:::backend
        end
    end

    UI -->|"HTTP Request"| APIServer
    APIServer -->|"routes to"| R1
    APIServer --> R2
    APIServer --> R3
    APIServer --> R4
    APIServer --> R5

    %% Utilities
    subgraph "Utilities"
        U1["Logger"]:::util
        U2["PDF Loader"]:::util
    end

    R1 -->|"log request"| U1
    R2 -->|"log request"| U1
    R3 -->|"log request"| U1
    R4 -->|"log request"| U1
    R5 -->|"log request"| U1
    R3 -->|"parse PDF"| U2
    R4 -->|"parse PDF"| U2

    %% Chain Layer
    subgraph "Chain Layer" 
        C1["Role-Based Chain"]:::domain
        C2["JD-Based Chain"]:::domain
        C3["Resume-Based Chain"]:::domain
        C4["Hybrid Chain"]:::domain
    end

    R1 -->|"call chain"| C1
    R2 -->|"call chain"| C2
    R3 -->|"call chain"| C3
    R4 -->|"call chain"| C4

    %% Memory Layer
    subgraph "Memory Layer"
        M1["Role Sessions"]:::domain
        M2["JD Sessions"]:::domain
        M3["Resume Sessions"]:::domain
        M4["Hybrid Sessions"]:::domain
    end

    C1 -->|"history"| M1
    C2 -->|"history"| M2
    C3 -->|"RAG context"| M3
    C4 -->|"RAG+history"| M4

    %% Prompt Store
    subgraph "Prompt Store"
        P1["role_prompt.txt"]:::domain
        P2["role_evaluation_prompt.txt"]:::domain
        P3["jd_prompt.txt"]:::domain
        P4["jd_evaluation_prompt.txt"]:::domain
        P5["resume_prompt.txt"]:::domain
        P6["resume_evaluation_prompt.txt"]:::domain
        P7["hybrid_prompt.txt"]:::domain
        P8["hybrid_evaluation_prompt.txt"]:::domain
    end

    C1 -->|"load prompts"| P1
    C1 --> P2
    C2 -->|"load prompts"| P3
    C2 --> P4
    C3 -->|"load prompts"| P5
    C3 --> P6
    C4 -->|"load prompts"| P7
    C4 --> P8

    %% External LLM API
    subgraph "External Services"
        LLM["LLM API"]:::external
    end

    C1 -->|"prompt text"| LLM
    C2 -->|"prompt text"| LLM
    C3 -->|"prompt text + context"| LLM
    C4 -->|"prompt text + context"| LLM
    LLM -->|"LLM response"| C1
    LLM --> C2
    LLM --> C3
    LLM --> C4

    %% Data Stores
    subgraph "Data Stores"
        DB["Vector DB"]:::datastore
        FS["File Storage"]:::datastore
        Logs["Logs Storage"]:::datastore
    end

    M3 -->|"embeddings"| DB
    M4 -->|"embeddings"| DB
    DB -->|"retrieved context"| M3
    DB --> M4

    R3 -->|"save upload"| FS
    R4 --> FS
    R1 -->|"store log"| Logs
    R2 --> Logs
    R3 --> Logs
    R4 --> Logs
    R5 --> Logs
    U2 -->|"load file"| FS

    %% Response back to UI
    C1 -->|"response"| R1
    C2 -->|"response"| R2
    C3 -->|"response"| R3
    C4 -->|"response"| R4
    R1 -->|"HTTP Response"| UI
    R2 --> UI
    R3 --> UI
    R4 --> UI
    R5 --> UI

    %% Click Events
    click UI "https://github.com/shiv0112/ai-interviewer/blob/main/frontend/streamlit_app.py"
    click APIServer "https://github.com/shiv0112/ai-interviewer/blob/main/main.py"
    click R1 "https://github.com/shiv0112/ai-interviewer/blob/main/app/routers/role_based.py"
    click R2 "https://github.com/shiv0112/ai-interviewer/blob/main/app/routers/jd.py"
    click R3 "https://github.com/shiv0112/ai-interviewer/blob/main/app/routers/resume.py"
    click R4 "https://github.com/shiv0112/ai-interviewer/blob/main/app/routers/hybrid.py"
    click R5 "https://github.com/shiv0112/ai-interviewer/blob/main/app/routers/status.py"
    click C1 "https://github.com/shiv0112/ai-interviewer/blob/main/app/chains/role_based_chain.py"
    click C2 "https://github.com/shiv0112/ai-interviewer/blob/main/app/chains/jd_based_chain.py"
    click C3 "https://github.com/shiv0112/ai-interviewer/blob/main/app/chains/resume_based_chain.py"
    click C4 "https://github.com/shiv0112/ai-interviewer/blob/main/app/chains/hybrid_chain.py"
    click M1 "https://github.com/shiv0112/ai-interviewer/blob/main/app/memory/role_sessions.py"
    click M2 "https://github.com/shiv0112/ai-interviewer/blob/main/app/memory/jd_sessions.py"
    click M3 "https://github.com/shiv0112/ai-interviewer/blob/main/app/memory/resume_sessions.py"
    click M4 "https://github.com/shiv0112/ai-interviewer/blob/main/app/memory/hybrid_sessions.py"
    click P1 "https://github.com/shiv0112/ai-interviewer/blob/main/app/prompts/role_prompt.txt"
    click P2 "https://github.com/shiv0112/ai-interviewer/blob/main/app/prompts/role_evaluation_prompt.txt"
    click P3 "https://github.com/shiv0112/ai-interviewer/blob/main/app/prompts/jd_prompt.txt"
    click P4 "https://github.com/shiv0112/ai-interviewer/blob/main/app/prompts/jd_evaluation_prompt.txt"
    click P5 "https://github.com/shiv0112/ai-interviewer/blob/main/app/prompts/resume_prompt.txt"
    click P6 "https://github.com/shiv0112/ai-interviewer/blob/main/app/prompts/resume_evaluation_prompt.txt"
    click P7 "https://github.com/shiv0112/ai-interviewer/blob/main/app/prompts/hybrid_prompt.txt"
    click P8 "https://github.com/shiv0112/ai-interviewer/blob/main/app/prompts/hybrid_evaluation_prompt.txt"
    click U1 "https://github.com/shiv0112/ai-interviewer/blob/main/app/utils/logger.py"
    click U2 "https://github.com/shiv0112/ai-interviewer/blob/main/app/utils/pdf_loader.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90ee90,stroke:#333,stroke-width:1px
    classDef domain fill:#ffffb3,stroke:#333,stroke-width:1px
    classDef datastore fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef external fill:#d1c4e9,stroke:#333,stroke-width:1px
    classDef util fill:#d3d3d3,stroke:#333,stroke-width:1px
```
