# kvj-harsha/rag-qna-chatbot architecture

> Architecture diagram of the GitHub repository kvj-harsha/rag-qna-chatbot, 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/kvj-harsha/rag-qna-chatbot
- Repository: https://github.com/kvj-harsha/rag-qna-chatbot

## Overview

##### Project type and purpose
- This is a single-repo, Streamlit-based “retrieval-augmented” Q&A chatbot.
- It provides two UI pages—one for ingesting documents into a Chroma vector store, and one for conversational Q&A over that store using OpenAI’s models.

##### File structure
- Top level:
- main.py        – entry point registering Streamlit pages
- chroma_services.py – vector-store ingestion & query logic
- genai_services.py  – OpenAI embedding & chat-completion calls
- data.txt       – sample data for ingestion
- template.env   – environment variable placeholders (API keys, etc.)
- requirements.txt – Python dependencies
- .gitignore, batch scripts – dev setup files
- pages/
- ingest_page.py – UI for uploading/ingesting documents
- chatbot_page.py– UI for interactive Q&A
- No separate backend server: UI and business logic live in the same Streamlit process.

##### Insights from README
- Technologies in use:
- Streamlit – UI framework
- OpenAI API – embeddings & chat completions
- tiktoken – token counting
- ChromaDB – local vector database
- markitdown – Markdown rendering support

a. Main components
- Streamlit frontend
– ingest_page
– chatbot_page
- Service layer
– chroma_services.py (ingestion, semantic search)
– genai_services.py (make embeddings, chat completions)
- Data layer
– ChromaDB local vector store
– source docs (data.txt or uploaded files)
- External service
– OpenAI API
- Configuration
– .env / template.env for API keys
b. Relationships & interactions
1. User interacts with Streamlit UI
2. Ingest page calls chroma_services.ingest(docs) → stores embeddings in ChromaDB
3. Chat page sends user query →
i. chroma_services.query(query) → returns relevant context chunks
ii. genai_services.chat_completion(system_prompt + context + question) → returns answer
4. Response rendered back in UI
c. Architectural patterns
- Monolithic Streamlit app with clear separation of concerns:
- Presentation layer (pages/)
- Service layer (…_services.py)
- Data persistence (ChromaDB)
- Retrieval-augmented generation (RAG) pattern
d. Key technologies
- Streamlit, ChromaDB Python client, OpenAI Python SDK, tiktoken

##### Final advice
- RAG flow end-to-end, from user input through retrieval and LLM inference back to the UI.
- Avoid unnecessary detail: focus on those modules that appear in the file tree.
- This level of granularity ensures any new engineer or stakeholder sees exactly how UI, services, data, and external APIs interconnect.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entities
    User["User"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        Main["Streamlit Entry Point\n(main.py)"]:::ui
        IngestPage["Ingest Page\n(pages/ingest_page.py)"]:::ui
        ChatbotPage["Chatbot Page\n(pages/chatbot_page.py)"]:::ui
    end

    %% Service Layer
    subgraph "Service Layer"
        ChromaServices["ChromaServices\n(chroma_services.py)"]:::service
        GenAIServices["GenAIServices\n(genai_services.py)"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        SampleDocs["Source Documents\n(data.txt)"]:::datastore
        ChromaDB["ChromaDB Vector Store"]:::datastore
    end

    %% External Services
    OpenAI["OpenAI API"]:::external

    %% Configuration & Metadata
    Env["Env Variables\n(template.env)"]:::config
    Requirements["Dependencies\n(requirements.txt)"]:::config
    README["README / Tech Overview\n(README.md)"]:::config

    %% Flow: Registration
    User -->|"opens app"| Main
    Main -->|"registers pages"| IngestPage
    Main -->|"registers pages"| ChatbotPage

    %% Ingestion Flow
    User -->|"upload docs"| IngestPage
    IngestPage -->|"call ingest(docs)"| ChromaServices
    ChromaServices -->|"store embeddings"| ChromaDB
    IngestPage -->|"read sample"| SampleDocs

    %% Chat Flow
    User -->|"ask question"| ChatbotPage
    ChatbotPage -->|"query(query)"| ChromaServices
    ChromaServices -->|"retrieve context"| ChromaDB
    ChromaServices -->|"pass context+question"| GenAIServices
    GenAIServices -->|"chat completion call"| OpenAI
    OpenAI -->|"response"| GenAIServices
    GenAIServices -->|"answer"| ChatbotPage
    ChatbotPage -->|"display answer"| User

    %% Configuration usage
    Env -->|provides API keys| GenAIServices
    Env -->|provides config| ChromaServices
    README -.->|docs tech| Main
    Requirements -.->|install deps| Main

    %% Click Events
    click IngestPage "https://github.com/kvj-harsha/rag-qna-chatbot/blob/main/pages/ingest_page.py"
    click ChatbotPage "https://github.com/kvj-harsha/rag-qna-chatbot/blob/main/pages/chatbot_page.py"
    click Main "https://github.com/kvj-harsha/rag-qna-chatbot/blob/main/main.py"
    click ChromaServices "https://github.com/kvj-harsha/rag-qna-chatbot/blob/main/chroma_services.py"
    click GenAIServices "https://github.com/kvj-harsha/rag-qna-chatbot/blob/main/genai_services.py"
    click SampleDocs "https://github.com/kvj-harsha/rag-qna-chatbot/blob/main/data.txt"
    click Env "https://github.com/kvj-harsha/rag-qna-chatbot/blob/main/template.env"
    click Requirements "https://github.com/kvj-harsha/rag-qna-chatbot/blob/main/requirements.txt"
    click README "https://github.com/kvj-harsha/rag-qna-chatbot/blob/main/README.md"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef service fill:#DFFFE0,stroke:#28a745,color:#28a745;
    classDef datastore fill:#FFF4D0,stroke:#DAA520,color:#DAA520;
    classDef external fill:#FFE0E0,stroke:#d73a49,color:#d73a49;
    classDef config fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
```
