# alizeeshan-07/lightrag architecture

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

- Interactive diagram: https://gitdiagram.com/alizeeshan-07/lightrag
- Repository: https://github.com/alizeeshan-07/lightrag

## Overview

##### Project type and purpose
- LightRAG is an open-source Python framework for Retrieval-Augmented Generation (RAG). It provides:
- A core library (“lightrag/…”) that ingests text, chunks it, computes embeddings, builds a knowledge graph (KG), and performs retrieval in four modes (naive, local, global, hybrid).
- Pluggable adapters for LLMs (OpenAI, Hugging Face, Ollama), embedding functions, and storage backends (NetworkX, Neo4j, Oracle).
- A FastAPI-based REST server for remote use, plus numerous example scripts.

##### File structure
- Top-level: README, Dockerfile, setup.py, requirements.txt, tests, examples, reproduce
- “lightrag/”: core modules
- base.py: foundational classes
- lightrag.py: orchestrates insert/query pipelines
- llm.py: LLM adapter functions
- operate.py: high-level operations
- prompt.py: prompt templates & management
- storage.py: vector/KV store abstractions
- kg/neo4j_impl.py: Neo4j storage implementation
- utils.py: helpers (e.g., xml_to_json)
- “examples/”: demos for ingestion, query, graph viz, API server
- “reproduce/”: step-by-step scripts for dataset prep and evaluation

##### Main components & relationships
a. Client Layer
- Script or REST client → calls API server or direct library
b. API Server (FastAPI) [optional]
- Receives HTTP requests → calls Core RAG pipeline
c. Core RAG Pipeline
1. Text Ingestion
– Chunker / Document Loader (textract support)
– Entity & Relation Extractor (via LLMs)
2. Embedding Service
– Calls embedding_func → produces vector representations
3. Storage Layer
– Vector store (flat files in working_dir)
– Knowledge Graph store
- Default: NetworkX (GraphML in working_dir)
- Pluggable: Neo4j, Oracle KG
4. Query Engine
– Retrieval strategies (naive/local/global/hybrid)
– Prompt Builder (combines contexts & relations)
– LLM adapter (generation)
d. External Systems
- LLM providers: OpenAI API, Hugging Face Hub, Ollama daemon
- KG backends: Neo4j server, Oracle Database

##### Architectural patterns & design principles
- Strategy pattern for storage backends (`kg="Neo4JStorage"` vs default)
- Adapter pattern for LLMs and embedding functions
- Pipeline orchestration in `LightRAG` class (single entry point)
- Separation of concerns: ingestion, storage, retrieval, generation

##### Detail and extensibility
- Plugin points: storage (NetworkX vs Neo4j vs Oracle), llm_model_func, embedding_func
- Call out the working_dir as the file system storage root
- FastAPI server as an overlay if used in deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client / API Layer
    subgraph "Client / API Layer"
        direction TB
        Script["Script / CLI Client"]:::external
        RESTClient["REST Client (curl/python)"]:::external
        APIServer["FastAPI Server"]:::api
    end

    %% Core Library Layer
    subgraph "Core RAG Pipeline"
        direction TB
        CoreLib["Core Library (RAG Pipeline)"]:::core
        BaseClasses["Foundational Classes"]:::core
        Orchestrator["LightRAG Orchestrator"]:::core
        LLMAdapters["LLM Adapters"]:::core
        HighOps["High-Level Operations"]:::core
        PromptMgmt["Prompt Management"]:::core
        StorageAPI["Storage Abstractions"]:::core
        Utils["Utility Functions"]:::core

        subgraph Ingestion
            direction TB
            Chunker["Chunker / Document Loader"]:::core
            EntityExtractor["Entity & Relation Extractor"]:::core
        end

        Embedding["Embedding Service"]:::core

        subgraph QueryEngine
            direction TB
            Retrieval["Retrieval Strategies"]:::core
            PromptBuilder["Prompt Builder"]:::core
            Generation["LLM Generation"]:::core
        end
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        VectorStore["Vector Store (files)"]:::storage
        subgraph "Graph Store"
            direction TB
            NXGraph["NetworkX GraphML (files)"]:::storage
            Neo4jStore["Neo4j Storage Impl"]:::storage
            OracleStore["Oracle Storage Impl"]:::storage
        end
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        OpenAI["OpenAI API"]:::external
        HFHub["Hugging Face Hub"]:::external
        Ollama["Ollama Daemon"]:::external
        Neo4jServer["Neo4j Server"]:::external
        OracleDB["Oracle Database"]:::external
    end

    %% Example & Reproduce
    subgraph "Examples & Tests"
        direction TB
        Examples["Examples"]:::external
        APIExample["FastAPI Demo"]:::external
        BatchEval["Batch Eval Scripts"]:::external
        GraphVizDemo["Graph Visualization"]:::external
        Reproduce["Reproducibility Scripts"]:::external
        TestNeo4j["Neo4j Integration Tests"]:::external
        GeneralTests["General Tests"]:::external
    end

    %% Connections
    Script -->|calls| APIServer
    RESTClient -->|HTTP Request| APIServer
    Script -->|direct import| CoreLib
    APIServer -->|calls| Orchestrator

    Orchestrator -->|ingest text| Chunker
    Chunker -->|"chunks"| EntityExtractor
    EntityExtractor -->|"entities/relations"| Embedding
    Embedding -->|"vectors"| VectorStore
    Embedding -->|embeddings| PromptBuilder

    Orchestrator -->|query| Retrieval
    Retrieval -->|context| PromptBuilder
    PromptBuilder -->|prompt| Generation
    Generation -->|response| Script

    StorageAPI -->|save vectors| VectorStore
    StorageAPI -->|save graph| NXGraph

    Orchestrator -->|kg backend| Neo4jStore
    Orchestrator -->|kg backend| OracleStore

    Neo4jStore -->|writes| Neo4jServer
    OracleStore -->|writes| OracleDB

    LLMAdapters -->|embed| OpenAI
    LLMAdapters -->|embed| HFHub
    LLMAdapters -->|embed| Ollama
    Generation -->|calls| OpenAI
    Generation -->|calls| HFHub
    Generation -->|calls| Ollama

    %% Click Events
    click CoreLib "https://github.com/alizeeshan-07/lightrag/tree/main/lightrag/"
    click BaseClasses "https://github.com/alizeeshan-07/lightrag/blob/main/lightrag/base.py"
    click Orchestrator "https://github.com/alizeeshan-07/lightrag/blob/main/lightrag/lightrag.py"
    click LLMAdapters "https://github.com/alizeeshan-07/lightrag/blob/main/lightrag/llm.py"
    click HighOps "https://github.com/alizeeshan-07/lightrag/blob/main/lightrag/operate.py"
    click PromptMgmt "https://github.com/alizeeshan-07/lightrag/blob/main/lightrag/prompt.py"
    click StorageAPI "https://github.com/alizeeshan-07/lightrag/blob/main/lightrag/storage.py"
    click Neo4jStore "https://github.com/alizeeshan-07/lightrag/blob/main/lightrag/kg/neo4j_impl.py"
    click OracleStore "https://github.com/alizeeshan-07/lightrag/blob/main/lightrag/kg/oracle_impl.py"
    click Utils "https://github.com/alizeeshan-07/lightrag/blob/main/lightrag/utils.py"
    click Examples "https://github.com/alizeeshan-07/lightrag/tree/main/examples/"
    click APIExample "https://github.com/alizeeshan-07/lightrag/blob/main/examples/lightrag_api_openai_compatible_demo.py"
    click BatchEval "https://github.com/alizeeshan-07/lightrag/blob/main/examples/batch_eval.py"
    click GraphVizDemo "https://github.com/alizeeshan-07/lightrag/blob/main/examples/graph_visual_with_html.py"
    click Reproduce "https://github.com/alizeeshan-07/lightrag/tree/main/reproduce/"
    click TestNeo4j "https://github.com/alizeeshan-07/lightrag/blob/main/test_neo4j.py"
    click GeneralTests "https://github.com/alizeeshan-07/lightrag/blob/main/test.py"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000;
    classDef storage fill:#90EE90,stroke:#000;
    classDef external fill:#FFA500,stroke:#000;
    classDef api fill:#D3D3D3,stroke:#000;
```
