# quanglekim021223/graphrag architecture

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

- Interactive diagram: https://gitdiagram.com/quanglekim021223/graphrag
- Repository: https://github.com/quanglekim021223/graphrag

## Overview

##### Project Type & Purpose
- This is a full-stack healthcare chatbot system that leverages a Neo4j knowledge graph and integrates large language models (via Azure OpenAI) with Retrieval-Augmented Generation (RAG).
- It supports multiple interfaces (web via Streamlit, REST API via FastAPI, and a command-line interface) and is built around a layered architecture which separates UI, business logic, and data access.

##### Analyzing the File Structure
- Top-Level Directories and Files:
- Main entry point (main.py)
- Configuration files (.env.example, Dockerfile, docker-compose.yml)
- Assets with images used for documentation/UI.
- A dedicated Neo4j configuration folder (neo4j/) and data dump folder (data/healthcare.csv and backup with neo4j.dump).
- The primary source code is under the src/ directory which is further organized into:
∙ config: holding settings for the application.
∙ handlers: responsible for the core business logic like conversation handling, graph management, LLM integration, and memory management.
∙ helpers: utility and initialization functions for agents and LLMs.
∙ routers: different interfaces exposing the application’s functionality (API, CLI, UI).

##### Architectural Layers
- User Interface (Presentation) Layer:
- Three distinct front-ends:
▸ Streamlit-based web UI.
▸ FastAPI-powered REST API.
▸ Command-Line Interface (CLI).
- Business Logic (Service) Layer:
- Components from the src/handlers folder:
▸ Conversation Handler (manages chat and interaction history).
▸ Graph Manager (handles interactions with the Neo4j graph database).
▸ GraphRAG Handler (implements the retrieval-augmented generation logic).
▸ LLM Manager and Memory Manager (ensure context storage and LLM decisions via the ReAct Agent).
▸ Additionally, the helpers that initialize agents and LLM components should be marked as supporting functionalities.
- Data & External Services Layer:
- Neo4j Graph Database (core knowledge graph storing healthcare data and conversation histories).
- Azure OpenAI (for LLM queries and generating responses).
- LangChain and LangGraph integration frameworks (which might be used inside the business logic layer to coordinate between the knowledge graph and LLM).

##### Relationships & Interactions
- How each UI component (Streamlit, FastAPI, CLI) sends user queries to the business logic layer.
- The business logic module (e.g., the GraphRAG handler) consulting the Neo4j graph for retrieval and then invoking Azure OpenAI for generating responses.
- Memory Manager updating and retrieving conversation context from an internal or persistent store.
- Integration flows where configuration (from settings.py) governs communication parameters (Neo4j connection, API keys, etc.).

##### Key Technological Components
- Python (the programming language).
- Docker & Docker Compose (for container orchestration).
- Neo4j as the graph database.
- Azure OpenAI as the external LLM service.
- Frameworks: FastAPI for the API, Streamlit for web UI, and support for CLI operations.
- Supporting libraries like LangChain and LangGraph that abstract complex functionality for RAG.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Entry Point
    mainEntry["Main Entry Point"]:::service

    %% Deployment & Configuration
    subgraph "Deployment & Configuration"
        env_file["Environment Variables (.env.example)"]:::deployment
        dockerfile["Docker Configuration (Dockerfile)"]:::deployment
        docker_compose["Container Orchestration (docker-compose.yml)"]:::deployment
        settings["Configuration & Settings"]:::service
    end

    %% User Interface Layer
    subgraph "User Interface Layer"
        ui_streamlit["Streamlit Web UI"]:::ui
        ui_fastapi["FastAPI REST API"]:::ui
        ui_cli["Command-Line Interface (CLI)"]:::ui
    end

    %% Business Logic (Service) Layer
    subgraph "Business Logic Layer"
        graphrag_handler["GraphRAG Handler"]:::service
        conv_handler["Conversation Handler"]:::service
        graph_manager["Graph Manager"]:::service
        llm_manager["LLM Manager"]:::service
        memory_manager["Memory Manager"]:::service

        %% Supporting Functionalities (Helpers)
        subgraph "Supporting Functions"
            agent_init["Agent Initializer"]:::helper
            llm_init["LLM Initializer"]:::helper
            logging_config["Logging Config"]:::helper
            prompts["Prompts"]:::helper
            tools["Utility Tools"]:::helper
        end
    end

    %% Data & External Services Layer
    subgraph "Data & External Services Layer"
        neo4j_db["Neo4j Database"]:::data
        neo4j_config["Neo4j Configuration & Startup"]:::data
        healthcare_data["Healthcare Data (CSV)"]:::data
        schema_def["Database Schema Definition"]:::data
        azure_openai["Azure OpenAI Service"]:::external
        langchain_framework["LangChain & LangGraph Frameworks"]:::external
    end

    %% Connections for Deployment & Configuration
    dockerfile --> mainEntry
    docker_compose --> mainEntry
    env_file --> mainEntry
    settings --> conv_handler
    settings --> graph_manager
    settings --> llm_manager
    settings --> memory_manager

    %% Connections from Main Entry to User Interfaces
    mainEntry --> ui_streamlit
    mainEntry --> ui_fastapi
    mainEntry --> ui_cli

    %% Connections from UI Layer to Business Logic
    ui_streamlit --> graphrag_handler
    ui_fastapi --> graphrag_handler
    ui_cli --> graphrag_handler

    %% Connections within Business Logic Layer
    graphrag_handler --> conv_handler
    graphrag_handler --> graph_manager
    graphrag_handler --> llm_manager
    graphrag_handler --> memory_manager

    %% Connections from Supporting Functions to Business Logic
    agent_init --> llm_manager
    llm_init --> llm_manager
    logging_config --> graphrag_handler
    prompts --> graphrag_handler
    tools --> graphrag_handler

    %% Connections from Business Logic to Data & External Services
    graph_manager --> neo4j_db
    graph_manager --> neo4j_config
    healthcare_data --> neo4j_db
    schema_def --> neo4j_db

    llm_manager --> azure_openai
    llm_manager --> langchain_framework

    %% Click Events
    click mainEntry "https://github.com/quanglekim021223/graphrag/blob/main/main.py"
    click settings "https://github.com/quanglekim021223/graphrag/blob/main/src/config/settings.py"
    click ui_streamlit "https://github.com/quanglekim021223/graphrag/blob/main/src/routers/ui_router.py"
    click ui_fastapi "https://github.com/quanglekim021223/graphrag/blob/main/src/routers/api_router.py"
    click ui_cli "https://github.com/quanglekim021223/graphrag/blob/main/src/routers/cli_router.py"
    click conv_handler "https://github.com/quanglekim021223/graphrag/blob/main/src/handlers/conversation_handler.py"
    click graph_manager "https://github.com/quanglekim021223/graphrag/blob/main/src/handlers/graph_manager.py"
    click graphrag_handler "https://github.com/quanglekim021223/graphrag/blob/main/src/handlers/graphrag_handler.py"
    click llm_manager "https://github.com/quanglekim021223/graphrag/blob/main/src/handlers/llm_manager.py"
    click memory_manager "https://github.com/quanglekim021223/graphrag/blob/main/src/handlers/memory_manager.py"
    click agent_init "https://github.com/quanglekim021223/graphrag/blob/main/src/helpers/agent_initializer.py"
    click llm_init "https://github.com/quanglekim021223/graphrag/blob/main/src/helpers/llm_initializer.py"
    click logging_config "https://github.com/quanglekim021223/graphrag/blob/main/src/helpers/logging_config.py"
    click prompts "https://github.com/quanglekim021223/graphrag/blob/main/src/helpers/prompts.py"
    click tools "https://github.com/quanglekim021223/graphrag/blob/main/src/helpers/tools.py"
    click neo4j_config "https://github.com/quanglekim021223/graphrag/blob/main/neo4j/entrypoint.sh"
    click healthcare_data "https://github.com/quanglekim021223/graphrag/blob/main/data/healthcare.csv"
    click schema_def "https://github.com/quanglekim021223/graphrag/blob/main/schema.cypher"
    click dockerfile "https://github.com/quanglekim021223/graphrag/tree/main/Dockerfile"
    click docker_compose "https://github.com/quanglekim021223/graphrag/blob/main/docker-compose.yml"
    click env_file "https://github.com/quanglekim021223/graphrag/blob/main/.env.example"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef service fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef data fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef helper fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef deployment fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
