# kayvanshah1/quizgenie architecture

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

- Interactive diagram: https://gitdiagram.com/kayvanshah1/quizgenie
- Repository: https://github.com/kayvanshah1/quizgenie

## Overview

##### Project type and purpose
- QuizGenie is a monolithic, full-stack AI application (back-end + UI) for dynamically generating quizzes from user-provided documents (PDFs).
- Its goal is to ingest text, use AI (Google Gemini + Langchain) to create questions, store/retrieve embeddings (ChromaDB), and present interactive quizzes via Streamlit.

##### File structure
- Top-level:
- README.md, LICENSE, .gitignore, requirements.txt, env.yml
- /app: contains the core Python modules and entrypoints
- app/ module breakdown:
- main.py – orchestrates the Streamlit UI and ties components together
- settings.py – configuration (env variables, paths)
- pdf_processing.py – PDF ingestion and text extraction
- embedding_client.py – calls Langchain/Google Gemini to embed text
- vector_store.py – persists and queries embeddings in ChromaDB
- quiz.py – generates questions, runs AI prompts, formats feedback

##### README for architecture clues
- Technologies: Python, Streamlit (UI), Langchain (NLP), ChromaDB (vector DB), Google Gemini (AI model), GCP for auth

- User (browser)
- Streamlit UI (app/main.py)
- PDF Processor (app/pdf_processing.py)
- Embedding Client (app/embedding_client.py)
- Vector Store (ChromaDB via app/vector_store.py)
- Quiz Generator (app/quiz.py + Google Gemini API)
- Configuration/Auth layer (app/settings.py + GCP service account)
b. Relationships & data flow:
1. User uploads PDF → Streamlit UI
2. UI calls PDF Processor → extracted text
3. Text → Embedding Client → embeddings
4. Embeddings → Vector Store (ChromaDB) for similarity searches
5. UI or Quiz module triggers question generation → Google Gemini API
6. Gemini responds with questions/explanations → UI
c. Architectural patterns & design principles:
- RAG (Retrieval‐Augmented Generation) pipeline
- Single codebase with clear module separation (ingestion, embedding, storage, generation, presentation)
- Configuration via environment (.env, settings.py)
d. Key technologies & frameworks:
- Streamlit for front-end
- Langchain for text embedding orchestration
- ChromaDB as vector database
- Google Gemini API (AI model)
- GCP service account for authentication

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client / UI Layer
    subgraph "Client / UI Layer"
        direction TB
        User["User<br/>(Browser)"]:::external
        UI["Streamlit UI<br/>(app/main.py)"]:::ui
    end

    %% Back-end Services
    subgraph "Back-end Services"
        direction TB
        PDFProc["PDF Processor<br/>(app/pdf_processing.py)"]:::backend
        Embed["Embedding Client<br/>(app/embedding_client.py)"]:::backend
        VectorStore["Vector Store<br/>(ChromaDB via app/vector_store.py)"]:::backend
        QuizGen["Quiz Generator<br/>(app/quiz.py)"]:::backend
        Config["Configuration / Auth<br/>(app/settings.py)"]:::config
    end

    %% External Services and Assets
    subgraph "External Services & Assets"
        direction TB
        Gemini["Google Gemini API"]:::external
        ChromaDB["ChromaDB"]:::external
        GCP["GCP IAM / Service Account"]:::external
        Assets["Static Assets<br/>(assets/)"]:::docs
        EnvYml["env.yml"]:::docs
        Req["requirements.txt"]:::docs
        Readme["README.md"]:::docs
    end

    %% Data Flows
    User -->|"Upload PDF"| UI
    UI -->|"calls"| PDFProc
    PDFProc -->|"extracted text"| Embed
    Embed -->|"embeddings"| VectorStore
    UI -->|"request quiz"| QuizGen
    QuizGen -->|"prompt via HTTP+JSON"| Gemini
    Gemini -->|"QA JSON"| QuizGen
    QuizGen -->|"questions & feedback"| UI

    %% Config/Auth Usage
    Config --> PDFProc
    Config --> Embed
    Config --> VectorStore
    Config --> QuizGen

    %% External Dependencies
    VectorStore -->|"stores/query vectors"| ChromaDB
    QuizGen --> GCP
    UI --> Assets

    %% Click Events
    click UI "https://github.com/kayvanshah1/quizgenie/blob/main/app/main.py"
    click PDFProc "https://github.com/kayvanshah1/quizgenie/blob/main/app/pdf_processing.py"
    click Embed "https://github.com/kayvanshah1/quizgenie/blob/main/app/embedding_client.py"
    click VectorStore "https://github.com/kayvanshah1/quizgenie/blob/main/app/vector_store.py"
    click QuizGen "https://github.com/kayvanshah1/quizgenie/blob/main/app/quiz.py"
    click Config "https://github.com/kayvanshah1/quizgenie/blob/main/app/settings.py"
    click Assets "https://github.com/kayvanshah1/quizgenie/tree/main/assets/"
    click EnvYml "https://github.com/kayvanshah1/quizgenie/blob/main/env.yml"
    click Req "https://github.com/kayvanshah1/quizgenie/blob/main/requirements.txt"
    click Readme "https://github.com/kayvanshah1/quizgenie/blob/main/README.md"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#2b6cb0,color:#2a4365
    classDef backend fill:#d4f5d4,stroke:#2f855a,color:#22543d
    classDef external fill:#ffe5cc,stroke:#dd6b20,color:#7b341e
    classDef config fill:#fefcbf,stroke:#d69e2e,color:#744210
    classDef docs fill:#f0f0f0,stroke:#a0a0a0,color:#4a4a4a
```
