# karanjain09/graph-rag-ai-bot architecture

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

- Interactive diagram: https://gitdiagram.com/karanjain09/graph-rag-ai-bot
- Repository: https://github.com/karanjain09/graph-rag-ai-bot

## Overview

##### Project type and purpose
- This is a full-stack AI-driven chatbot application (“Graph-RAG-AI-Bot”) that lets users enter a website URL, scrapes and processes its content into a knowledge graph, and uses an LLM to answer user queries in a chat interface.

##### File structure
- Top-level scripts and modules:
- app.py – orchestrates HTTP server (Chainlit) and routes user input/queries
- web_scraper.py – fetches and parses HTML (BeautifulSoup)
- text_chunker.py – splits markdown text into logical chunks
- neo4j_manager.py – interfaces with Neo4j for storage and semantic retrieval
- llm_client.py – calls Groq’s API for LLaMA 3.3 inference
- config.py – loads environment variables (Neo4j URI/creds, Groq API key)
- requirements.txt lists dependencies; .gitignore excludes env files, caches, etc.

##### Extract architecture from the README
- Eight-step flow (Input → Scrape → Convert → Chunk → Store → Query → Generate → Output)
- Frontend: Chainlit chat interface served by app.py
- Persistence: Neo4j graph database
- External service: Groq LLaMA API

##### Main components
a. Presentation Layer
- User’s web browser
- Chainlit UI (within app.py process)
b. Application Layer
- Web Scraper module
- HTML→Markdown Converter (can be shown as part of web_scraper or a separate submodule)
- Text Chunker module
- Neo4j Manager module
- LLM Client module
- Orchestrator / Router (app.py)
c. Data Layer
- Neo4j Graph Database
d. External Services
- Groq API endpoint for LLaMA 3.3 inference
e. Configuration
- Environment/config module (config.py) feeding credentials to the Neo4j Manager and LLM Client

##### Relationships and data flow
- URL → Web Scraper → HTML
- HTML → Markdown Converter → Markdown
- Markdown → Text Chunker → Content Chunks
- Chunks → Neo4j Manager → Neo4j (store / index)
- For user queries:
- User → Chainlit UI → Orchestrator
- Orchestrator → Neo4j Manager → retrieve relevant chunks
- Retrieved chunks → LLM Client → Groq API → Response Text
- Response → Chainlit UI → User

##### Architectural patterns and design principles
- Modular pipeline: each processing step in its own module (single responsibility)
- Layered architecture: clear separation between presentation, application logic, persistence, and external services
- Dependency injection of config values (via config.py and environment variables)
- Graph-based retrieval pattern (RAG) for semantic search

##### Relevant technologies & libraries
- Python 3.8+
- Chainlit (chat UI framework)
- BeautifulSoup (web_scraping)
- Markdown converter library (e.g., markdownify)
- Neo4j with official Python driver
- Groq API for LLaMA 3.3
- Environment management (.env)

##### Next steps for the principal software engineer
- Validate with stakeholders and iterate, ensuring every module and its interaction is captured succinctly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (Presentation Layer)"
        Browser["User Browser"]:::frontend
        ChainlitUI["Chainlit UI"]:::frontend
        Browser -->|"Enter URL / Query"| ChainlitUI
    end

    subgraph "Backend (Application Layer)"
        Orchestrator["Orchestrator / Router\n(app.py)"]:::processing
        Config["Configuration\n(config.py)"]:::config
        WebScraper["Web Scraper\n(web_scraper.py)"]:::processing
        MarkdownConv["Markdown Converter"]:::processing
        Chunker["Text Chunker\n(text_chunker.py)"]:::processing
        Neo4jMgr["Neo4j Manager\n(neo4j_manager.py)"]:::processing
        LLMClient["LLM Client\n(llm_client.py)"]:::processing

        ChainlitUI -->|"Calls Orchestrator"| Orchestrator
        Orchestrator --> Config
        Config --> Neo4jMgr
        Config --> LLMClient

        Orchestrator -->|"Scrape URL"| WebScraper
        WebScraper -->|"HTML"| MarkdownConv
        MarkdownConv -->|"Markdown"| Chunker
        Chunker -->|"Content Chunks"| Neo4jMgr
    end

    subgraph "Data Layer"
        Neo4jDB[(Neo4j Graph Database)]:::db
        Neo4jMgr -->|"Store & Index"| Neo4jDB
    end

    subgraph "Query Pipeline"
        Orchestrator -->|"User Query"| Neo4jMgr
        Neo4jMgr -->|"Retrieve Chunks"| Orchestrator
        Orchestrator -->|"Send Chunks"| LLMClient
        LLMClient -->|"Inference"| GroqAPI
        GroqAPI(("Groq LLaMA API")):::external
        GroqAPI -->|"Response Text"| Orchestrator
        Orchestrator -->|"Return Response"| ChainlitUI
    end

    subgraph "Documentation"
        Requirements["requirements.txt"]:::doc
        README["README.md"]:::doc
    end

    click Orchestrator "https://github.com/karanjain09/graph-rag-ai-bot/blob/main/app.py"
    click Config "https://github.com/karanjain09/graph-rag-ai-bot/blob/main/config.py"
    click WebScraper "https://github.com/karanjain09/graph-rag-ai-bot/blob/main/web_scraper.py"
    click Chunker "https://github.com/karanjain09/graph-rag-ai-bot/blob/main/text_chunker.py"
    click Neo4jMgr "https://github.com/karanjain09/graph-rag-ai-bot/blob/main/neo4j_manager.py"
    click LLMClient "https://github.com/karanjain09/graph-rag-ai-bot/blob/main/llm_client.py"
    click Requirements "https://github.com/karanjain09/graph-rag-ai-bot/blob/main/requirements.txt"
    click README "https://github.com/karanjain09/graph-rag-ai-bot/blob/main/README.md"

    classDef frontend fill:#BEDEFF,stroke:#444,stroke-width:1px
    classDef processing fill:#C2F0C2,stroke:#444,stroke-width:1px
    classDef db fill:#FFDDAA,stroke:#444,stroke-width:1px
    classDef external fill:#E3CCFF,stroke:#444,stroke-width:1px
    classDef config fill:#FFFFCC,stroke:#444,stroke-width:1px
    classDef doc fill:#F8F8F8,stroke:#999,stroke-dasharray: 2 2
    class Orchestrator,WebScraper,MarkdownConv,Chunker,Neo4jMgr,LLMClient processing
    class Config config
    class Neo4jDB db
    class GroqAPI external
    class Browser,ChainlitUI frontend
    class Requirements,README doc
```
