# kartikeya-0211/quantum-tutor architecture

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

- Interactive diagram: https://gitdiagram.com/kartikeya-0211/quantum-tutor
- Repository: https://github.com/kartikeya-0211/quantum-tutor

## Overview

##### Project type and purpose
- This is a full-stack RAG (Retrieval-Augmented Generation) chatbot, “Quantum Tutor,” built in Python.
- It provides an interactive Streamlit UI (app.py) that connects to a LangChain-based RAG pipeline, uses ChromaDB for embeddings, and dispatches LLM requests via LiteLLM to external providers (Groq, Ollama).

##### File structure
- Top-level:
- app.py – Streamlit entrypoint for the web UI
- chains/ – RAG pipeline definitions (chains/rag_chains.py)
- loaders/ – Document ingestion (loaders/load_documents.py)
- retrievers/ – Re-ranking logic (retrievers/reranker.py)
- utils/ – Helpers (chunker, embedder, llm_loader, query_classifier)
- config/ – litellm_config.yaml for LLM provider settings
- data/ – PDF knowledge base
- tests/ – Benchmark harness and evaluation scripts
- requirements.txt, .env.example – dependencies and env setup

- Architectural patterns:
- A clear separation between “frontend” (Streamlit UI) and “backend” (RAG pipeline).
- A single monolithic service with modular subcomponents rather than microservices.

##### README for additional insights
- Core technologies: Streamlit, LangChain, LiteLLM, ChromaDB.
- Use cases: querying academic materials, benchmarking LLMs.

- Frontend (blue),
- Backend pipeline (green),
- Data store (orange),
- External services (purple).
- Rectangles for code modules,
– Increase font size on labels for readability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["Streamlit UI"]:::frontend
    end

    %% Backend Pipeline
    subgraph "Backend Pipeline"
        Controller["RAG Pipeline Controller"]:::backend

        subgraph "Document Store & Ingestion"
            Loader["Document Ingestion & Loader"]:::backend
            Chunker["Chunking Helper"]:::backend
            Embedder["Embedding Helper"]:::backend
            VectorDB["ChromaDB Vector Store"]:::data
        end

        subgraph "Retrieval & Ranking"
            QueryCls["Query Classification Helper"]:::backend
            Retriever["Retriever & Re-ranker"]:::backend
        end

        subgraph "LLM Generation"
            Prompt["Prompt Templates"]:::backend
            LLMAbst["LLM Provider Abstraction"]:::backend
            ExtLLM["External LLM Services\n(Groq, Ollama)"]:::external
        end
    end

    %% Configuration
    subgraph "Configuration"
        Env["Environment Variables (.env.example)"]:::config
        ConfigFile["LLM Provider Config\n(litellm_config.yaml)"]:::config
    end

    %% Benchmarking Suite
    subgraph "Benchmarking Suite"
        Bench1["benchmark.py"]:::tests
        Bench2["evaluate.py"]:::tests
        BenchQ["Benchmark_questions.csv"]:::tests
    end

    %% Data Layer
    subgraph "Knowledge Base"
        Data["PDF Knowledge Base"]:::data
    end

    %% Connections
    UI -->|"User Query"| Controller
    Controller -->|classify| QueryCls
    Controller -->|load docs| Loader
    Loader -->|chunk| Chunker
    Chunker -->|embed| Embedder
    Embedder -->|store/retrieve| VectorDB
    VectorDB -->|top-k| Retriever
    Retriever -->|prepare prompt| Prompt
    Prompt -->|invoke| LLMAbst
    LLMAbst -->|API call| ExtLLM
    ExtLLM -->|response| LLMAbst
    LLMAbst -->|LLM reply| Controller
    Controller -->|display| UI

    Env -->|provides| LLMAbst
    ConfigFile -->|configures| LLMAbst

    Bench1 -->|runs against| Controller
    Bench2 -->|evaluates| Bench1
    BenchQ -->|data for| Bench1

    Data --> Loader

    %% Click Events
    click UI "https://github.com/kartikeya-0211/quantum-tutor/blob/master/app.py"
    click Controller "https://github.com/kartikeya-0211/quantum-tutor/blob/master/chains/rag_chains.py"
    click Loader "https://github.com/kartikeya-0211/quantum-tutor/blob/master/loaders/load_documents.py"
    click Chunker "https://github.com/kartikeya-0211/quantum-tutor/blob/master/utils/chunker.py"
    click Embedder "https://github.com/kartikeya-0211/quantum-tutor/blob/master/utils/embedder.py"
    click QueryCls "https://github.com/kartikeya-0211/quantum-tutor/blob/master/utils/query_classifier.py"
    click LLMAbst "https://github.com/kartikeya-0211/quantum-tutor/blob/master/utils/llm_loader.py"
    click Retriever "https://github.com/kartikeya-0211/quantum-tutor/blob/master/retrievers/reranker.py"
    click Prompt "https://github.com/kartikeya-0211/quantum-tutor/blob/master/prompts/prompt_template.py"
    click ConfigFile "https://github.com/kartikeya-0211/quantum-tutor/blob/master/config/litellm_config.yaml"
    click Env "https://github.com/kartikeya-0211/quantum-tutor/blob/master/.env.example"
    click Data "https://github.com/kartikeya-0211/quantum-tutor/tree/master/data/"
    click Bench1 "https://github.com/kartikeya-0211/quantum-tutor/blob/master/tests/benchmark.py"
    click Bench2 "https://github.com/kartikeya-0211/quantum-tutor/blob/master/tests/evaluate.py"
    click BenchQ "https://github.com/kartikeya-0211/quantum-tutor/blob/master/tests/Benchmark_questions.csv"

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#0366d6,color:#0366d6,font-size:14px;
    classDef backend fill:#d9ead3,stroke:#6aa84f,color:#38761d,font-size:14px;
    classDef data fill:#f9cb9c,stroke:#e69138,color:#b45f06,font-size:14px;
    classDef external fill:#c9daf8,stroke:#3d85c6,color:#0b5394,font-size:14px;
    classDef config fill:#eeeeee,stroke:#999999,color:#333333,font-size:14px;
    classDef tests fill:#f4cccc,stroke:#cc0000,color:#990000,font-size:14px;
```
