# bayu-siddhi/graph-rag-arangodb architecture

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

- Interactive diagram: https://gitdiagram.com/bayu-siddhi/graph-rag-arangodb
- Repository: https://github.com/bayu-siddhi/graph-rag-arangodb

## Overview

##### Main Components
- User Interface: Represented by the Gradio-based UI (launched by main.py). This is the entry point where users interact with the system.
- Backend Processing:
- Query & Retrieval Engine: Modules like app/graph_rag/agent.py and app/graph_rag/prompt.py manage the retrieval process, integrating LLM responses with graph data.
- Knowledge Graph Handler: Files in app/graph_rag (models.py, tools.py) combine with app/database.py and app/custom_adbnx.py to handle ArangoDB connectivity and query execution using AQL.
- Data & Graph Analytics: The file app/dataset.py along with integration of NetworkX (as mentioned in the README) handles graph analytics (e.g., shortest paths, influences, community detection).
- Data Storage & Graph Data:
- External ArangoDB: The project assumes an ArangoDB instance (credentials in .env, and instructions in README), serving as the primary data store for nodes, edges, and legal documents.
- Static Data Files: The “data” directory contains both raw data (data/raw) and preprocessed graph JSON files (nodes and various edge types) that can be used for visualization and validation.
- Auxiliary Components:
- Helper utilities: Such as app/helper.py and any additional configuration files (.env.example) that support runtime setup and configuration.

##### Relationships and Data Flow
- User Query Path: Begin with the Gradio UI (main.py) where a user submits a legal question.
- Query Processing: The input is then handed off to the retrieval engine (app/graph_rag/agent.py) which uses custom prompts (from app/graph_rag/prompt.py) and model configurations (in app/graph_rag/models.py).
- Graph Analytics: Indicate a data flow to NetworkX-powered analytics (hinted at in the README) where algorithms assess connectedness, centrality, and community structures from the legal data.
- Response Assembly: The combined insights from graph analytics and LLM results are then composed into a context-aware response that is delivered back to the UI.

##### Architectural Patterns & Design Principles
- Modular Design: The separation between data handling (knowledge graph operations), analytics (NetworkX), and NLP tasks (RAG with LLM) is clear in the directory structure.
- Separation of Concerns: Highlight how the project separates data storage, retrieval logic, and user interaction.
- External Dependency Integration: Emphasize integration with third-party tools and services such as ArangoDB for storage and Gradio for the UI.
- Extensibility: The project’s structure (with various submodules within app/graph_rag) suggests that components can be extended or modified in isolation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    subgraph "User Interface"
        UI["Gradio UI (main.py)"]:::ui
    end

    %% Backend Processing
    subgraph "Backend Processing"
        subgraph "Query & Retrieval Engine"
            AGENT["Retrieval Engine (agent.py)"]:::backend
            PROMPT["Prompt Module (prompt.py)"]:::backend
        end
        subgraph "Knowledge Graph Handler"
            MODELS["Models (models.py)"]:::backend
            TOOLS["Tools (tools.py)"]:::backend
            DATABASE["Database Connector (database.py)"]:::backend
            CUSTOM["Custom ADBNX (custom_adbnx.py)"]:::backend
        end
        ANI["Graph Analytics (dataset.py)"]:::backend
    end

    %% External Data & Storage
    subgraph "External Data & Storage"
        ARANGO["ArangoDB (External Data Store)"]:::external
        STATIC["Static Data (data/)"]:::external
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        HELPER["Helper Utilities (helper.py)"]:::auxiliary
        CONFIG["Configurations (.env.example)"]:::auxiliary
    end

    %% Connections
    UI -->|"submits_query"| AGENT
    AGENT -->|"invokes"| PROMPT
    AGENT -->|"queries_via"| MODELS
    AGENT -->|"queries_via"| TOOLS
    AGENT -->|"executes_via"| DATABASE
    AGENT -->|"executes_via"| CUSTOM
    MODELS -->|"fetches_data"| ARANGO
    TOOLS -->|"assists_query"| ARANGO
    DATABASE -->|"executes_AQL"| ARANGO
    CUSTOM -->|"custom_query"| ARANGO
    STATIC -->|"provides_data"| DATABASE
    AGENT -->|"performs_analytics"| ANI
    ANI -->|"analyzes_data"| STATIC
    ANI -->|"computes_metrics"| ARANGO
    AGENT -->|"assembles_response"| UI
    HELPER -->|"supports"| AGENT
    CONFIG -->|"configures"| AGENT

    %% Click Events
    click UI "https://github.com/bayu-siddhi/graph-rag-arangodb/blob/main/main.py"
    click AGENT "https://github.com/bayu-siddhi/graph-rag-arangodb/blob/main/app/graph_rag/agent.py"
    click PROMPT "https://github.com/bayu-siddhi/graph-rag-arangodb/blob/main/app/graph_rag/prompt.py"
    click MODELS "https://github.com/bayu-siddhi/graph-rag-arangodb/blob/main/app/graph_rag/models.py"
    click TOOLS "https://github.com/bayu-siddhi/graph-rag-arangodb/blob/main/app/graph_rag/tools.py"
    click DATABASE "https://github.com/bayu-siddhi/graph-rag-arangodb/blob/main/app/database.py"
    click CUSTOM "https://github.com/bayu-siddhi/graph-rag-arangodb/blob/main/app/custom_adbnx.py"
    click ANI "https://github.com/bayu-siddhi/graph-rag-arangodb/blob/main/app/dataset.py"
    click STATIC "https://github.com/bayu-siddhi/graph-rag-arangodb/tree/main/data/"
    click HELPER "https://github.com/bayu-siddhi/graph-rag-arangodb/blob/main/app/helper.py"
    click CONFIG "https://github.com/bayu-siddhi/graph-rag-arangodb/blob/main/.env.example"

    %% Styles
    classDef ui fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#fcc,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#ccf,stroke:#333,stroke-width:2px;
```
