# hkuds/lightrag architecture

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

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

## Overview

#### Purpose and Entry Points
LightRAG is a Python graph-based retrieval-augmented generation system: it indexes documents into text/vector/knowledge-graph representations, then answers using local, global, naive, hybrid, or mix retrieval. The embedded SDK centers on `lightrag/lightrag.py`, with query/index operations in `lightrag/operate.py`. The primary deployment entry is the ASGI server in `lightrag/api/lightrag_server.py`; it exposes REST and serves built WebUI assets. Package/CLI definitions are rooted in `pyproject.toml`.

#### API, Access, and User Surfaces
The API server composes document, graph, query, Ollama-compatible, and UI-customization routers from `lightrag/api/routers/document_routes.py`, `lightrag/api/routers/graph_routes.py`, and `lightrag/api/routers/query_routes.py`. Authentication, admission/capacity control, body limits, and runtime validation form the public-boundary layer in `lightrag/api/auth.py`, `lightrag/api/admission.py`, and `lightrag/api/runtime_validation.py`. The React/TypeScript UI has distinct admin and query-only entry surfaces: `lightrag_webui/src/App.tsx` and `lightrag_webui/src/features/workspace/WorkspaceApp.tsx`.

#### Ingestion Pipeline
Document ingestion is an asynchronous, status-tracked pipeline coordinated by `lightrag/pipeline.py`; ingress and scheduling primitives live in `lightrag/kg/pipeline_ingress.py` and `lightrag/kg/scan_job_store.py`. It accepts direct text and files, persists lifecycle status, bounds concurrency, and supports retry, cancellation, deletion, and recovery. File parsing is dispatched by rules/registries in `lightrag/parser/routing.py` and `lightrag/parser/registry.py`, separating parser engines from downstream indexing.

#### Parse, Multimodal IR, and Chunking
Native Markdown/DOCX, legacy, and external Docling/MinerU parser implementations normalize files into an intermediate representation/sidecar contract. Key implementations are `lightrag/parser/docx/parser.py`, `lightrag/parser/markdown/parser.py`, and `lightrag/parser/external/docling/parser.py`. Parsed content can include images, tables, and equations; sidecar persistence/backfill is in `lightrag/sidecar/ir.py` and `lightrag/sidecar/writer.py`. Chunking then selects fixed/token, recursive, vector-semantic, or paragraph-semantic strategies through `lightrag/chunker/registry.py` and `lightrag/chunker/paragraph_semantic.py`.

#### Extraction and Index Construction
Chunk content is embedded and sent to role-specific model bindings for entity/relation extraction, keyword generation, query answering, and optional visual analysis. Provider adapters are isolated under `lightrag/llm/`, with representative bindings in `lightrag/llm/openai.py` and `lightrag/llm/ollama.py`; role resolution is in `lightrag/llm_roles.py`. Extraction/query orchestration in `lightrag/operate.py` writes chunks, entities, relationships, provenance, and LLM caches. This is the main boundary between untrusted/model-produced output and validated persistent graph records.

#### Storage Abstraction and Consistency
Four logical stores—KV/cache, vectors, graph, and document status—are abstracted behind factories and shared lifecycle/control mechanisms in `lightrag/kg/factory.py`, `lightrag/kg/shared_storage.py`, and `lightrag/kg/write_seq.py`. Local defaults use JSON/NanoVectorDB/NetworkX (`lightrag/kg/json_kv_impl.py`, `lightrag/kg/networkx_impl.py`); production options include unified PostgreSQL, MongoDB, or OpenSearch plus specialized Neo4j, Milvus, Qdrant, Redis, and Memgraph adapters. Vector-space provenance and embedding-dimension compatibility are handled in `lightrag/kg/vector_space.py`.

#### Query Flow and Operations
Queries enter through API or SDK, are validated in `lightrag/query_validation.py`, and execute retrieval/generation in `lightrag/operate.py`. Depending on mode, the system combines vector chunk search with graph entity/relation traversal, optionally reranks via `lightrag/rerank.py`, constructs bounded context, and invokes the QUERY model; result caching is stored in KV. Administrative graph edits and document deletion must coordinate with pipeline/write gates so affected graph/vector state can be rebuilt. Repair and migration CLIs—including vector rebuild and graph migration—live in `lightrag/tools/rebuild_vdb.py` and `lightrag/tools/migrate_graph_storage.py`.

#### Runtime and Infrastructure
The server targets Python 3.10+, with Gunicorn support in `lightrag/api/run_with_gunicorn.py`. The frontend is built with Bun/Vite from `lightrag_webui/package.json`. Docker Compose variants (`docker-compose.yml`, `docker-compose-full.yml`) and Helm/Kubernetes manifests under `k8s-deploy/lightrag/` deploy the service and optional databases. External dependencies can include LLM/embedding/reranking providers, local Ollama/vLLM-style services, and self-hosted or cloud MinerU/Docling parser services.

Main entry points: [`lightrag/pipeline.py`](https://github.com/hkuds/lightrag/blob/main/lightrag/pipeline.py) (Document Pipeline), [`lightrag/operate.py`](https://github.com/hkuds/lightrag/blob/main/lightrag/operate.py) (Index & Query Orchestration), [`lightrag/kg/shared_storage.py`](https://github.com/hkuds/lightrag/blob/main/lightrag/kg/shared_storage.py) (Persistent Stores), [`lightrag/api/routers/query_routes.py`](https://github.com/hkuds/lightrag/blob/main/lightrag/api/routers/query_routes.py) (API Routers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User Surfaces"]
  node_sdk["LightRAG SDK<br/>Python SDK<br/>[lightrag.py]"]
  node_api["ASGI Server<br/>REST server<br/>[lightrag_server.py]"]
  node_routers["API Routers<br/>route modules<br/>[query_routes.py]"]
  node_boundary["Public Boundary Controls<br/>auth and admission<br/>[auth.py]"]
  node_webui["WebUI<br/>React application<br/>[App.tsx]"]
end

subgraph group_ingestion["Ingestion &amp; Indexing"]
  node_pipeline["Document Pipeline<br/>async coordinator<br/>[pipeline.py]"]
  node_ingress["Pipeline Ingress &amp; Jobs<br/>scheduler"]
  node_parser["Parser Routing<br/>parser registry<br/>[routing.py]"]
  node_multimodal["Multimodal IR &amp; Sidecars<br/>intermediate representation<br/>[ir.py]"]
  node_chunking["Chunking Strategies<br/>chunker registry<br/>[registry.py]"]
end

subgraph group_retrieval["Retrieval &amp; Models"]
  node_operate["Index &amp; Query Orchestration<br/>core operations<br/>[operate.py]"]
  node_models["LLM Role Bindings<br/>model adapters<br/>[llm_roles.py]"]
  node_validation["Query Validation<br/>request validation"]
  node_retrieval["Hybrid Retrieval &amp; Rerank<br/>retrieval flow<br/>[rerank.py]"]
end

subgraph group_storage["Storage &amp; Operations"]
  node_storage_factory["Storage Abstraction<br/>store factory<br/>[factory.py]"]
  node_write_gate["Write Sequencing<br/>consistency control<br/>[write_seq.py]"]
  node_stores[("Persistent Stores<br/>KV, vector, graph, status<br/>[shared_storage.py]")]
  node_repair_tools["Rebuild &amp; Migration Tools<br/>maintenance CLI<br/>[rebuild_vdb.py]"]
  node_deployment{{"Deployment Manifests<br/>container orchestration<br/>[docker-compose.yml]"}}
end

node_webui -->|"REST requests"| node_api
node_api -->|"applies controls"| node_boundary
node_boundary -->|"admits requests"| node_routers
node_routers -->|"uses service API"| node_sdk
node_sdk -->|"indexes documents"| node_pipeline
node_routers -->|"document operations"| node_pipeline
node_pipeline -->|"schedules and tracks"| node_ingress
node_pipeline -->|"dispatches files"| node_parser
node_parser -->|"normalizes content"| node_multimodal
node_multimodal -->|"supplies IR"| node_chunking
node_chunking -->|"indexes chunks"| node_operate
node_operate -->|"invokes role models"| node_models
node_operate -->|"reads and writes records"| node_storage_factory
node_storage_factory -->|"selects backend adapters"| node_stores
node_pipeline -->|"coordinates writes"| node_write_gate
node_write_gate -->|"serializes mutations"| node_stores
node_sdk -->|"submits queries"| node_validation
node_routers -->|"validates queries"| node_validation
node_validation -->|"approved query"| node_operate
node_operate -->|"retrieves context"| node_retrieval
node_retrieval -->|"generates answer"| node_models
node_retrieval -->|"vector, graph, cache access"| node_stores
node_repair_tools -->|"coordinates repair"| node_write_gate
node_repair_tools -->|"rebuilds and migrates"| node_stores
node_deployment -->|"deploys service"| node_api
node_deployment -.->|"provisions optional backends"| node_stores

click node_sdk "https://github.com/hkuds/lightrag/blob/main/lightrag/lightrag.py"
click node_api "https://github.com/hkuds/lightrag/blob/main/lightrag/api/lightrag_server.py"
click node_routers "https://github.com/hkuds/lightrag/blob/main/lightrag/api/routers/query_routes.py"
click node_boundary "https://github.com/hkuds/lightrag/blob/main/lightrag/api/auth.py"
click node_webui "https://github.com/hkuds/lightrag/blob/main/lightrag_webui/src/App.tsx"
click node_pipeline "https://github.com/hkuds/lightrag/blob/main/lightrag/pipeline.py"
click node_ingress "https://github.com/hkuds/lightrag/blob/main/lightrag/kg/pipeline_ingress.py"
click node_parser "https://github.com/hkuds/lightrag/blob/main/lightrag/parser/routing.py"
click node_multimodal "https://github.com/hkuds/lightrag/blob/main/lightrag/sidecar/ir.py"
click node_chunking "https://github.com/hkuds/lightrag/blob/main/lightrag/chunker/registry.py"
click node_operate "https://github.com/hkuds/lightrag/blob/main/lightrag/operate.py"
click node_models "https://github.com/hkuds/lightrag/blob/main/lightrag/llm_roles.py"
click node_validation "https://github.com/hkuds/lightrag/blob/main/lightrag/query_validation.py"
click node_retrieval "https://github.com/hkuds/lightrag/blob/main/lightrag/rerank.py"
click node_storage_factory "https://github.com/hkuds/lightrag/blob/main/lightrag/kg/factory.py"
click node_write_gate "https://github.com/hkuds/lightrag/blob/main/lightrag/kg/write_seq.py"
click node_stores "https://github.com/hkuds/lightrag/blob/main/lightrag/kg/shared_storage.py"
click node_repair_tools "https://github.com/hkuds/lightrag/blob/main/lightrag/tools/rebuild_vdb.py"
click node_deployment "https://github.com/hkuds/lightrag/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk,node_api,node_routers,node_boundary,node_webui toneBlue
class node_pipeline,node_ingress,node_parser,node_multimodal,node_chunking toneAmber
class node_operate,node_models,node_validation,node_retrieval toneMint
class node_storage_factory,node_write_gate,node_stores,node_repair_tools,node_deployment toneRose
```

## Components

### User Surfaces

- [LightRAG SDK](https://github.com/hkuds/lightrag/blob/main/lightrag/lightrag.py): Python SDK · Embedded indexing and query interface. · `lightrag/lightrag.py`
- [ASGI Server](https://github.com/hkuds/lightrag/blob/main/lightrag/api/lightrag_server.py): REST server · Serves REST APIs and built WebUI assets. · `lightrag/api/lightrag_server.py`
- [API Routers](https://github.com/hkuds/lightrag/blob/main/lightrag/api/routers/query_routes.py): route modules · Document, graph, query, Ollama, and UI endpoints. · `lightrag/api/routers/query_routes.py`
- [Public Boundary Controls](https://github.com/hkuds/lightrag/blob/main/lightrag/api/auth.py): auth and admission · Authentication, capacity, body-limit, and runtime checks. · `lightrag/api/auth.py`
- [WebUI](https://github.com/hkuds/lightrag/blob/main/lightrag_webui/src/App.tsx): React application · Admin and query-only workspace surfaces. · `lightrag_webui/src/App.tsx`

### Ingestion & Indexing

- [Document Pipeline](https://github.com/hkuds/lightrag/blob/main/lightrag/pipeline.py): async coordinator · Tracks lifecycle, concurrency, retry, cancellation, and recovery. · `lightrag/pipeline.py`
- [Pipeline Ingress & Jobs](https://github.com/hkuds/lightrag/blob/main/lightrag/kg/pipeline_ingress.py): scheduler · Accepts documents and persists scan jobs. · `lightrag/kg/pipeline_ingress.py`
- [Parser Routing](https://github.com/hkuds/lightrag/blob/main/lightrag/parser/routing.py): parser registry · Selects native, legacy, or external parser engines. · `lightrag/parser/routing.py`
- [Multimodal IR & Sidecars](https://github.com/hkuds/lightrag/blob/main/lightrag/sidecar/ir.py): intermediate representation · Persists normalized text, images, tables, and equations. · `lightrag/sidecar/ir.py`
- [Chunking Strategies](https://github.com/hkuds/lightrag/blob/main/lightrag/chunker/registry.py): chunker registry · Chooses fixed, recursive, vector, or paragraph semantic chunks. · `lightrag/chunker/registry.py`

### Retrieval & Models

- [Index & Query Orchestration](https://github.com/hkuds/lightrag/blob/main/lightrag/operate.py): core operations · Extracts graph records and executes retrieval/generation. · `lightrag/operate.py`
- [LLM Role Bindings](https://github.com/hkuds/lightrag/blob/main/lightrag/llm_roles.py): model adapters · Provider-backed embedding, extraction, keyword, query, and visual roles. · `lightrag/llm_roles.py`
- [Query Validation](https://github.com/hkuds/lightrag/blob/main/lightrag/query_validation.py): request validation · `lightrag/query_validation.py`
- [Hybrid Retrieval & Rerank](https://github.com/hkuds/lightrag/blob/main/lightrag/rerank.py): retrieval flow · Combines vector and graph retrieval into bounded model context. · `lightrag/rerank.py`

### Storage & Operations

- [Storage Abstraction](https://github.com/hkuds/lightrag/blob/main/lightrag/kg/factory.py): store factory · Coordinates KV, vector, graph, and document-status backends. · `lightrag/kg/factory.py`
- [Write Sequencing](https://github.com/hkuds/lightrag/blob/main/lightrag/kg/write_seq.py): consistency control · Gates coordinated pipeline and administrative writes. · `lightrag/kg/write_seq.py`
- [Persistent Stores](https://github.com/hkuds/lightrag/blob/main/lightrag/kg/shared_storage.py): KV, vector, graph, status · Local or production database adapters. · `lightrag/kg/shared_storage.py`
- [Rebuild & Migration Tools](https://github.com/hkuds/lightrag/blob/main/lightrag/tools/rebuild_vdb.py): maintenance CLI · Rebuilds vectors and migrates graph storage. · `lightrag/tools/rebuild_vdb.py`
- [Deployment Manifests](https://github.com/hkuds/lightrag/blob/main/docker-compose.yml): container orchestration · Compose and Helm deployments with optional databases. · `docker-compose.yml`

## Connections

- WebUI → ASGI Server: REST requests
- ASGI Server → Public Boundary Controls: applies controls
- Public Boundary Controls → API Routers: admits requests
- API Routers → LightRAG SDK: uses service API
- LightRAG SDK → Document Pipeline: indexes documents
- API Routers → Document Pipeline: document operations
- Document Pipeline → Pipeline Ingress & Jobs: schedules and tracks
- Document Pipeline → Parser Routing: dispatches files
- Parser Routing → Multimodal IR & Sidecars: normalizes content
- Multimodal IR & Sidecars → Chunking Strategies: supplies IR
- Chunking Strategies → Index & Query Orchestration: indexes chunks
- Index & Query Orchestration → LLM Role Bindings: invokes role models
- Index & Query Orchestration → Storage Abstraction: reads and writes records
- Storage Abstraction → Persistent Stores: selects backend adapters
- Document Pipeline → Write Sequencing: coordinates writes
- Write Sequencing → Persistent Stores: serializes mutations
- LightRAG SDK → Query Validation: submits queries
- API Routers → Query Validation: validates queries
- Query Validation → Index & Query Orchestration: approved query
- Index & Query Orchestration → Hybrid Retrieval & Rerank: retrieves context
- Hybrid Retrieval & Rerank → LLM Role Bindings: generates answer
- Hybrid Retrieval & Rerank → Persistent Stores: vector, graph, cache access
- Rebuild & Migration Tools → Write Sequencing: coordinates repair
- Rebuild & Migration Tools → Persistent Stores: rebuilds and migrates
- Deployment Manifests → ASGI Server: deploys service
- Deployment Manifests → Persistent Stores: provisions optional backends
