# microsoft/graphrag architecture

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

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

## Overview

1. **Repository shape**
   - This is a Python monorepo centered on the `graphrag` package, with smaller reusable packages (`graphrag-llm`, `graphrag-input`, `graphrag-storage`, `graphrag-vectors`, `graphrag-chunking`, `graphrag-cache`, `graphrag-common`) and one consumer app (`unified-search-app`).
   - The repo is organized around a GraphRAG pipeline: ingest documents, build graph-structured knowledge, persist intermediate/final artifacts, then query that knowledge with LLM-backed search modes.

2. **Primary orchestration layer: `packages/graphrag`**
   - This is the main product package and CLI entrypoint.
   - It owns the top-level APIs, command-line commands, configuration loading, logging, prompt tuning, indexing, querying, and data-model definitions.
   - If you draw a diagram, this package is the hub connecting input, LLM, storage, vector retrieval, and query/search subsystems.

3. **Input ingestion boundary**
   - `graphrag-input` handles reading source documents from multiple formats: text, CSV, JSON, JSONL, Parquet, and HTML/markitdown-based conversion.
   - The core repo’s `data_model` package defines the canonical entities that move through the system: documents, text units, entities, relationships, communities, covariates, and reports.
   - The input stage converts heterogeneous raw files into normalized document objects before indexing starts.

4. **Indexing pipeline**
   - The indexing flow is implemented in `graphrag/index` using workflows and operations.
   - Major phases include loading documents, splitting into text units, extracting graph structure, extracting covariates/claims, generating embeddings, clustering the graph into communities, summarizing communities, pruning/finalizing the graph, and writing snapshots.
   - There is also explicit support for incremental updates, so indexing is not just a one-shot batch pipeline.

5. **LLM and model execution layer**
   - `graphrag-llm` abstracts model access: completion, embedding, tokenization, templating, retries, rate limiting, caching, metrics, and threaded/batched execution.
   - It uses provider adapters such as LiteLLM and mock implementations for testing.
   - This package is the boundary between GraphRAG logic and external model APIs; all LLM/embedding calls pass through here rather than being embedded directly in business logic.

6. **Graph extraction and summarization mechanics**
   - Within indexing, graph extraction is split into dedicated operations for noun-graph building, entity/relationship extraction, claim/covariate extraction, and summarization.
   - Community summarization builds report artifacts from graph context and text-unit context.
   - Prompt templates live under `graphrag/prompts` and `graphrag/prompt_tune`, so prompt assets are part of the architecture, not just configuration.

7. **Storage and persistence**
   - `graphrag-storage` provides abstract storage plus concrete backends for file, memory, Azure Blob Storage, and Azure Cosmos DB.
   - It also defines table abstractions and table providers for CSV, Parquet, and Cosmos-backed tables.
   - The indexing pipeline persists its artifacts through these storage abstractions, which is why the system can run locally with files or scale to cloud storage.

8. **Vector retrieval layer**
   - `graphrag-vectors` manages vector-store integrations, including LanceDB, Azure AI Search, and Cosmos DB.
   - This layer is used for embedding-backed retrieval of text units and related content during query-time search.
   - It forms the retrieval index boundary between generated embeddings and downstream search algorithms.

9. **Query subsystem**
   - `graphrag/query` implements multiple search modes: basic search, local search, global search, and drift search.
   - Query-time context builders assemble the inputs for each mode from stored graph artifacts, retrieved text units, community reports, and conversation/history context.
   - There is a question-generation path as well, which suggests the system can both answer and generate follow-up questions.

10. **Search data flow at query time**
   - Query processing generally flows from user question → retrieval/context builder → structured search strategy → LLM completion → response.
   - Local search emphasizes nearby entities/text units, global search uses community-level summaries, and drift search tracks iterative state.
   - The `query/input/retrieval` and `query/context_builder` directories show that retrieval and context assembly are first-class architectural stages.

11. **Reusable support packages**
   - `graphrag-chunking` isolates sentence/token chunking strategies.
   - `graphrag-cache` provides cache implementations and key generation for expensive operations.
   - `graphrag-common` contains shared config loading, factory helpers, and hashing utilities used across packages.
   - These packages reduce coupling so the core pipeline can swap implementations without changing orchestration code.

12. **Unified search application**
   - `unified-search-app` is a separate downstream application that consumes GraphRAG outputs.
   - It has its own app logic, UI components, state management, knowledge loading, and RAG-specific helpers.
   - It appears to support multiple knowledge sources, including local files and blob-backed sources, and is packaged as a deployable container.

13. **Docs, examples, and notebooks as part of the product surface**
   - The repository includes extensive docs, example notebooks, and fixture datasets for indexing and query scenarios.
   - These are not just samples; they encode expected data shapes, pipeline stages, and output artifacts, which is useful when drawing the system boundary and lifecycle.
   - The notebooks also demonstrate how consumers are expected to interact with each subsystem.

14. **Testing and delivery model**
   - There is a broad test matrix: unit, integration, notebook, smoke, and verb-level tests, plus CI workflows for checks, publishing, and semantic versioning.
   - The presence of cloud-specific integration tests for Azure storage and vector services indicates the architecture is designed to run in both local and managed cloud environments.
   - A diagram should reflect that the repo is a platform/library stack with strong test coverage and multiple runtime backends, not a single deployable service.

Main entry points: [`packages/graphrag/graphrag/index/run/run_pipeline.py`](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/index/run/run_pipeline.py) (Indexing), [`packages/graphrag/graphrag/query/structured_search/basic_search/search.py`](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/basic_search/search.py) (Query engine), [`packages/graphrag-llm/graphrag_llm/completion/completion.py`](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-llm/graphrag_llm/completion/completion.py) (LLM runtime), [`packages/graphrag-storage/graphrag_storage/storage.py`](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-storage/graphrag_storage/storage.py) (Storage layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core GraphRAG"]
  node_graphrag_main["CLI entry<br/>python package<br/>[__main__.py]"]
  node_graphrag_api["Public API<br/>api layer<br/>[index.py]"]
  node_graphrag_index["Indexing<br/>pipeline orchestrator<br/>[run_pipeline.py]"]
  node_graphrag_query["Query engine<br/>search subsystem<br/>[search.py]"]
  node_graphrag_prompt_tune["Prompt tuning<br/>prompt tooling"]
  node_graphrag_data_model[("Data model<br/>domain model<br/>[document.py]")]
  node_graphrag_query_context["Context builders<br/>context assembly<br/>[builders.py]"]
  node_graphrag_query_retrieval["Query retrieval<br/>retrieval adapters<br/>[text_units.py]"]
end

subgraph group_support["Reusable Packages"]
  node_input_pkg["Input readers<br/>ingest package<br/>[input_reader.py]"]
  node_llm_pkg["LLM runtime<br/>model boundary<br/>[completion.py]"]
  node_storage_pkg[("Storage layer<br/>persistence abstraction<br/>[storage.py]")]
  node_vectors_pkg[("Vector store<br/>retrieval index<br/>[vector_store.py]")]
  node_chunking_pkg["Chunking<br/>text splitting<br/>[chunker.py]"]
  node_cache_pkg["Cache<br/>memoization<br/>[cache.py]"]
  node_common_pkg["Common utils<br/>shared helpers<br/>[load_config.py]"]
end

subgraph group_app["Consumer App"]
  node_ui_app["Search app<br/>consumer app<br/>[app_logic.py]"]
  node_ui_loader["Knowledge loader<br/>data prep<br/>[data_prep.py]"]
  node_ui_rag["App RAG<br/>query helpers<br/>[typing.py]"]
  node_ui_state["App state<br/>ui state"]
end

subgraph group_delivery["Docs & CI"]
  node_docs_and_tests["Docs & tests<br/>delivery surface<br/>[README.md]"]
end

node_graphrag_main -->|"exposes"| node_graphrag_api
node_graphrag_api -->|"runs"| node_graphrag_index
node_graphrag_api -->|"runs"| node_graphrag_query
node_graphrag_api -->|"tunes"| node_graphrag_prompt_tune
node_graphrag_index -->|"loads"| node_input_pkg
node_graphrag_index -->|"splits"| node_chunking_pkg
node_graphrag_index -->|"calls"| node_llm_pkg
node_graphrag_index -->|"persists"| node_storage_pkg
node_graphrag_index -->|"indexes"| node_vectors_pkg
node_graphrag_index -->|"produces"| node_graphrag_data_model
node_graphrag_index -->|"shares"| node_common_pkg
node_graphrag_query -->|"builds"| node_graphrag_query_context
node_graphrag_query -->|"retrieves"| node_graphrag_query_retrieval
node_graphrag_query -->|"generates"| node_llm_pkg
node_graphrag_query -->|"reads"| node_storage_pkg
node_graphrag_query -->|"searches"| node_vectors_pkg
node_graphrag_prompt_tune -->|"proposes"| node_llm_pkg
node_graphrag_prompt_tune -->|"loads"| node_common_pkg
node_input_pkg -->|"normalizes"| node_graphrag_data_model
node_llm_pkg -->|"caches"| node_cache_pkg
node_llm_pkg -->|"configures"| node_common_pkg
node_storage_pkg -->|"builds"| node_common_pkg
node_vectors_pkg -->|"depends on"| node_storage_pkg
node_ui_app -->|"loads"| node_ui_loader
node_ui_app -->|"uses"| node_ui_rag
node_ui_app -->|"tracks"| node_ui_state
node_ui_loader -->|"reads"| node_storage_pkg
node_ui_loader -->|"consumes"| node_vectors_pkg
node_docs_and_tests -->|"exercises"| node_graphrag_index
node_docs_and_tests -->|"exercises"| node_graphrag_query
node_docs_and_tests -->|"verifies"| node_llm_pkg

click node_graphrag_main "https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/__main__.py"
click node_graphrag_api "https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/api/index.py"
click node_graphrag_index "https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/index/run/run_pipeline.py"
click node_graphrag_query "https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/basic_search/search.py"
click node_graphrag_prompt_tune "https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompt_tune/generator/extract_graph_prompt.py"
click node_graphrag_data_model "https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/data_model/document.py"
click node_graphrag_query_context "https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/context_builder/builders.py"
click node_graphrag_query_retrieval "https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/input/retrieval/text_units.py"
click node_input_pkg "https://github.com/microsoft/graphrag/blob/main/packages/graphrag-input/graphrag_input/input_reader.py"
click node_llm_pkg "https://github.com/microsoft/graphrag/blob/main/packages/graphrag-llm/graphrag_llm/completion/completion.py"
click node_storage_pkg "https://github.com/microsoft/graphrag/blob/main/packages/graphrag-storage/graphrag_storage/storage.py"
click node_vectors_pkg "https://github.com/microsoft/graphrag/blob/main/packages/graphrag-vectors/graphrag_vectors/vector_store.py"
click node_chunking_pkg "https://github.com/microsoft/graphrag/blob/main/packages/graphrag-chunking/graphrag_chunking/chunker.py"
click node_cache_pkg "https://github.com/microsoft/graphrag/blob/main/packages/graphrag-cache/graphrag_cache/cache.py"
click node_common_pkg "https://github.com/microsoft/graphrag/blob/main/packages/graphrag-common/graphrag_common/config/load_config.py"
click node_ui_app "https://github.com/microsoft/graphrag/blob/main/unified-search-app/app/app_logic.py"
click node_ui_loader "https://github.com/microsoft/graphrag/blob/main/unified-search-app/app/knowledge_loader/data_prep.py"
click node_ui_rag "https://github.com/microsoft/graphrag/blob/main/unified-search-app/app/rag/typing.py"
click node_ui_state "https://github.com/microsoft/graphrag/blob/main/unified-search-app/app/state/session_variables.py"
click node_docs_and_tests "https://github.com/microsoft/graphrag/blob/main/README.md"

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_graphrag_main,node_graphrag_api,node_graphrag_index,node_graphrag_query,node_graphrag_prompt_tune,node_graphrag_data_model,node_graphrag_query_context,node_graphrag_query_retrieval toneBlue
class node_input_pkg,node_llm_pkg,node_storage_pkg,node_vectors_pkg,node_chunking_pkg,node_cache_pkg,node_common_pkg toneAmber
class node_ui_app,node_ui_loader,node_ui_rag,node_ui_state toneMint
class node_docs_and_tests toneRose
```

## Components

### Core GraphRAG

Primary package that orchestrates indexing, querying, prompt tuning, and CLI entrypoints.

- [CLI entry](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/__main__.py): python package · Main entrypoint for the GraphRAG command-line surface. · `packages/graphrag/graphrag/__main__.py`
- [Public API](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/api/index.py): api layer · Top-level programmatic APIs for indexing, querying, and prompt tuning. · `packages/graphrag/graphrag/api/index.py`
- [Indexing](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/index/run/run_pipeline.py): pipeline orchestrator · Coordinates document loading, graph extraction, embedding, clustering, summarization, pruning, and snapshots. · `packages/graphrag/graphrag/index/run/run_pipeline.py`
- [Query engine](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/basic_search/search.py): search subsystem · Implements basic, local, global, drift, and question-generation search modes. · `packages/graphrag/graphrag/query/structured_search/basic_search/search.py`
- [Prompt tuning](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompt_tune/generator/extract_graph_prompt.py): prompt tooling · Generates and manages prompts used by indexing and query workflows. · `packages/graphrag/graphrag/prompt_tune/generator/extract_graph_prompt.py`
- [Data model](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/data_model/document.py): domain model · Canonical entities and records that move through indexing and query flows. · `packages/graphrag/graphrag/data_model/document.py`
- [Context builders](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/context_builder/builders.py): context assembly · Builds retrieval context from graph artifacts, text units, communities, and conversation state. · `packages/graphrag/graphrag/query/context_builder/builders.py`
- [Query retrieval](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/input/retrieval/text_units.py): retrieval adapters · Loads stored entities, relationships, covariates, text units, and reports for search-time use. · `packages/graphrag/graphrag/query/input/retrieval/text_units.py`

### Reusable Packages

Shared runtime packages for input normalization, model access, storage, retrieval, chunking, caching, and common helpers.

- [Input readers](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-input/graphrag_input/input_reader.py): ingest package · Normalizes text, CSV, JSON, JSONL, Parquet, and HTML inputs into documents. · `packages/graphrag-input/graphrag_input/input_reader.py`
- [LLM runtime](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-llm/graphrag_llm/completion/completion.py): model boundary · Completion, embedding, retries, rate limiting, caching, templating, metrics, and provider adapters. · `packages/graphrag-llm/graphrag_llm/completion/completion.py`
- [Storage layer](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-storage/graphrag_storage/storage.py): persistence abstraction · File, memory, Azure Blob, and Cosmos-backed storage plus table providers. · `packages/graphrag-storage/graphrag_storage/storage.py`
- [Vector store](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-vectors/graphrag_vectors/vector_store.py): retrieval index · Vector-store integrations for LanceDB, Azure AI Search, and Cosmos DB. · `packages/graphrag-vectors/graphrag_vectors/vector_store.py`
- [Chunking](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-chunking/graphrag_chunking/chunker.py): text splitting · Sentence and token chunking strategies used before extraction and embedding. · `packages/graphrag-chunking/graphrag_chunking/chunker.py`
- [Cache](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-cache/graphrag_cache/cache.py): memoization · Reusable cache implementations and cache-key generation for expensive operations. · `packages/graphrag-cache/graphrag_cache/cache.py`
- [Common utils](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-common/graphrag_common/config/load_config.py): shared helpers · Shared config loading, factory helpers, and hashing utilities. · `packages/graphrag-common/graphrag_common/config/load_config.py`

### Consumer App

Downstream unified search application built on GraphRAG outputs.

- [Search app](https://github.com/microsoft/graphrag/blob/main/unified-search-app/app/app_logic.py): consumer app · Unified search application that consumes GraphRAG outputs. · `unified-search-app/app/app_logic.py`
- [Knowledge loader](https://github.com/microsoft/graphrag/blob/main/unified-search-app/app/knowledge_loader/data_prep.py): data prep · Prepares local and blob-backed knowledge sources for the app. · `unified-search-app/app/knowledge_loader/data_prep.py`
- [App RAG](https://github.com/microsoft/graphrag/blob/main/unified-search-app/app/rag/typing.py): query helpers · RAG-specific typing and helpers used by the consumer application. · `unified-search-app/app/rag/typing.py`
- [App state](https://github.com/microsoft/graphrag/blob/main/unified-search-app/app/state/session_variables.py): ui state · Session and query state managed by the application UI. · `unified-search-app/app/state/session_variables.py`

### Docs & CI

Documentation, notebooks, fixtures, tests, and automation that define and validate the platform.

- [Docs & tests](https://github.com/microsoft/graphrag/blob/main/README.md): delivery surface · Documentation, notebooks, fixtures, tests, and CI workflows that validate the platform. · `README.md`

## Connections

- CLI entry → Public API: exposes · The CLI delegates into the public API surface.
- Public API → Indexing: runs · API calls launch indexing workflows.
- Public API → Query engine: runs · API calls launch query/search workflows.
- Public API → Prompt tuning: tunes · API exposes prompt tuning operations.
- Indexing → Input readers: loads · Indexing starts from normalized input documents.
- Indexing → Chunking: splits · Documents are chunked into text units before extraction.
- Indexing → LLM runtime: calls · Extraction, summarization, and embedding use the LLM boundary.
- Indexing → Storage layer: persists · Intermediate and final artifacts are written through storage abstractions.
- Indexing → Vector store: indexes · Embeddings are stored in vector backends for retrieval.
- Indexing → Data model: produces · Indexing materializes canonical graph and document entities.
- Indexing → Common utils: shares · Indexing reuses config, factory, and hashing helpers.
- Query engine → Context builders: builds · Search modes assemble structured context before generation.
- Query engine → Query retrieval: retrieves · Query execution loads graph artifacts and text units.
- Query engine → LLM runtime: generates · Final answers and question generation use model calls.
- Query engine → Storage layer: reads · Querying consumes persisted index artifacts.
- Query engine → Vector store: searches · Embedding-backed retrieval supports local and related search flows.
- Prompt tuning → LLM runtime: proposes · Prompt tuning depends on model execution and templating support.
- Prompt tuning → Common utils: loads · Prompt assets are loaded via shared helpers.
- Input readers → Data model: normalizes · Readers convert heterogeneous files into canonical document objects.
- LLM runtime → Cache: caches · Model calls can be wrapped with caching middleware.
- LLM runtime → Common utils: configures · Shared utilities help configure model factories and hashing.
- Storage layer → Common utils: builds · Storage backends reuse shared config and factory helpers.
- Vector store → Storage layer: depends on · Vector integrations rely on persisted tables and storage patterns.
- Search app → Knowledge loader: loads · The app prepares knowledge sources before interaction.
- Search app → App RAG: uses · Application logic depends on RAG helpers and types.
- Search app → App state: tracks · User interaction is coordinated through session state.
- Knowledge loader → Storage layer: reads · Knowledge sources can be file- or blob-backed.
- Knowledge loader → Vector store: consumes · Loaded knowledge can include vector-backed artifacts.
- Docs & tests → Indexing: exercises · Docs, notebooks, and tests demonstrate indexing behavior.
- Docs & tests → Query engine: exercises · Query notebooks and tests document search modes.
- Docs & tests → LLM runtime: verifies · Integration and notebook tests cover model execution behavior.
