# bu-bu-xxx/nano-graphrag architecture

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

- Interactive diagram: https://gitdiagram.com/bu-bu-xxx/nano-graphrag
- Repository: https://github.com/bu-bu-xxx/nano-graphrag

## Overview

##### Project Context and Purpose
- nano-graphrag is a lightweight, “easy-to-hack” implementation of GraphRAG. It provides core retrieval-augmented generation functionality by combining LLM interactions, text chunking, embedding operations, and graph-based storage for relational context.
- The README emphasizes integration with multiple external services (e.g., OpenAI, Amazon Bedrock, DeepSeek, ollama), asynchronous methods, and multiple storage backends (vector DB, key–value JSON, graph storage via networkx/neo4j).

##### Analyzing the File Structure
- The core source of the project lies in the “nano_graphrag” directory, which comprises submodules such as:
– _llm.py: Implementation of LLM call interfaces.
– _op.py and _splitter.py: Text processing, chunking and splitting techniques.
– _storage folder: Contains various storage implementations (e.g., for graph storage, key–value stores via JSON, and vector storage via hnswlib or nano-vectordb).
– “entity_extraction”: Modules for extracting entities and relationships.
– “base.py”: Likely defines interfaces for the storage components and possibly abstract classes.
- Additional directories like “examples”, “docs”, and “tests” provide usage demonstrations, documentation (including benchmarks and advanced customization), and unit tests to validate functionality.

##### Identifying Main Components and Their Relationships

a. Client / User Interface:
– Represents the code that calls nano-graphrag (e.g., sample scripts in the “examples” folder).

b. Core Engine (GraphRAG Class):
– Acts as the central orchestrator for operations like insertion and querying.
– It connects with the processing modules, storage modules, and external API interfaces.

c. Text Ingestion and Chunking Module:
– Responsible for reading documents and splitting them into manageable chunks.
– Found in _op.py and _splitter.py.
– This module feeds data into the rest of the processing pipeline.

d. Embedding Module:
– Converts text chunks into vector representations.
– The default (built-in) OpenAI embedding function is showcased; alternatives (like Sentence-transformers) are available via examples.
– Make sure to include details such as support for asynchronous operation.

e. Storage Components:
– KV Storage: Stores key (md5 hash)-to-JSON data pairs for deduplication and document metadata.
– Vector Database Storage: Handles the indexing of embeddings using nano-vectordb, hnswlib, faiss, milvus-lite, etc.
– Graph Storage: Manages the knowledge graph using networkx (and a Neo4j option is available).

f. LLM / Prompt Module:
– LAN (the “great” and “cheap” LLMs) handling planning, summarization, and generation.
– Prompts come from the nano_graphrag/prompt module, with pre-defined entries for entity extraction, community reporting, local and global query generation, and fallback responses.
– This component shows the interaction with external LLM APIs or local models.

g. Query Processor:
– Implements the logic for both “global” and “local” retrieval—this component takes a user query, retrieves relevant chunks (through vector similarity and graph community analysis), and then determines the appropriate answer-generation method.
– Handles special modes (e.g., naive RAG, incremental insertion, asynchronous variants).

##### Interactions and Data Flow
– Document/Raw Text → Chunking Module.
– Chunking → Embedding Module (conversion to vectors).
– Embeddings + extracted metadata → KV Storage, Vector Storage, and Graph Storage.
– For queries: The user query is passed to the Query Processor, which in turn fetches relevant context from the storages.
– The retrieved context is then fed into the LLM / Prompt Module which produces the final answer.
- Asynchronous flows where appropriate (e.g., asynchronous insert, query, and LLM calls).

##### Architectural Patterns and Design Principles
- Modularization: The separation of concerns is evident, as each component (chunking, embedding, storage, LLM, etc.) is implemented in separate modules.
- Pluggability/Extensibility: The system facilitates “plugging in” custom implementations for storage, chunking, and LLM functions.
- Interface Abstraction: The “base” interfaces (like those in base.py) abstract component behavior so that internal implementations (e.g., neo4j vs. networkx) can be swapped easily.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    A["Client/Interface"]:::client

    %% Core Engine
    B["GraphRAG Core Engine"]:::core

    %% Processing Modules - Text Ingestion and Embedding
    subgraph "Processing Modules"
        C1["Text Ingestion (_op)"]:::processing
        C2["Text Chunking (_splitter)"]:::processing
        M["Merge Ingestion Results"]:::merge
        D["Embedding Engine (Async) (_llm)"]:::processing
    end

    %% Storage Components
    subgraph "Storage"
        E["KV Storage (kv_json)"]:::storage
        subgraph "Vector DB Storage"
            F1["vdb_hnswlib"]:::storage
            F2["vdb_nanovectordb"]:::storage
        end
        subgraph "Graph Storage"
            G1["gdb_networkx"]:::storage
            G2["gdb_neo4j"]:::storage
        end
    end

    %% Query and LLM Modules
    I["Query Processor"]:::query
    H["LLM / Prompt Module"]:::llm

    %% Ingestion Flow
    A -->|"calls"| B
    B -->|"initiates"| C1
    B -->|"initiates"| C2
    C1 --> M
    C2 --> M
    M -->|"processes"| D
    D -->|"stores_to"| E
    D -->|"stores_to"| F1
    D -->|"stores_to"| F2
    D -->|"stores_to"| G1
    D -->|"stores_to"| G2

    %% Query Flow
    A -->|"submits_query"| I
    I -->|"fetches"| E
    I -->|"fetches"| F1
    I -->|"fetches"| F2
    I -->|"fetches"| G1
    I -->|"fetches"| G2
    I -->|"aggregates_context"| H
    H -->|"generates_answer"| B
    B -->|"delivers_answer"| A

    %% Click Events
    click A "https://github.com/bu-bu-xxx/nano-graphrag/tree/main/examples/"
    click B "https://github.com/bu-bu-xxx/nano-graphrag/blob/main/nano_graphrag/graphrag.py"
    click C1 "https://github.com/bu-bu-xxx/nano-graphrag/blob/main/nano_graphrag/_op.py"
    click C2 "https://github.com/bu-bu-xxx/nano-graphrag/blob/main/nano_graphrag/_splitter.py"
    click D "https://github.com/bu-bu-xxx/nano-graphrag/blob/main/nano_graphrag/_llm.py"
    click E "https://github.com/bu-bu-xxx/nano-graphrag/blob/main/nano_graphrag/_storage/kv_json.py"
    click F1 "https://github.com/bu-bu-xxx/nano-graphrag/blob/main/nano_graphrag/_storage/vdb_hnswlib.py"
    click F2 "https://github.com/bu-bu-xxx/nano-graphrag/blob/main/nano_graphrag/_storage/vdb_nanovectordb.py"
    click G1 "https://github.com/bu-bu-xxx/nano-graphrag/blob/main/nano_graphrag/_storage/gdb_networkx.py"
    click G2 "https://github.com/bu-bu-xxx/nano-graphrag/blob/main/nano_graphrag/_storage/gdb_neo4j.py"
    click H "https://github.com/bu-bu-xxx/nano-graphrag/blob/main/nano_graphrag/prompt.py"
    click I "https://github.com/bu-bu-xxx/nano-graphrag/blob/main/nano_graphrag/graphrag.py"

    %% Styles
    classDef client fill:#E0FFFF,stroke:#000,stroke-width:2px;
    classDef core fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef processing fill:#B0E0E6,stroke:#000,stroke-width:2px;
    classDef storage fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef llm fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef query fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef merge fill:#FFFFFF,stroke:#000,stroke-dasharray: 5,5,stroke-width:2px;
```
