# awslabs/graphrag-toolkit architecture

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

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

## Overview

##### Project Type and Purpose
- This is an open-source Python toolkit (“GraphRAG Toolkit”) focused on the Lexical Graph component.
- Purpose: build and query a hierarchical lexical graph from unstructured data, and support Generative AI question-answering on top of that graph.

##### High-Level Components
a. Data Ingestion & Extraction
- Source adapters (file system, S3, JSON arrays, Bedrock knowledge base)
- Extraction pipeline modules (batch topic/proposition extractors, LLM-based extractors, doc parsers)
b. Graph Construction (Indexing Build)
- Build pipeline orchestrator
- Node/graph builders (chunk, entity, topic, statement, fact, source graphs)
- Checkpointing, batching, and summary builder
c. Storage Abstractions & Plugins
- Graph store interface + factory
- Implementations: dummy, multi-tenant, AWS Neptune, FalkorDB
- Vector store interface + factory
- Implementations: dummy, multi-tenant, Neptune analytics, OpenSearch serverless, PostgreSQL
d. Query & Retrieval
- Query engine entrypoint
- Retriever classes (keyword, semantic, traversal, composite, rerankers)
- Post-processors and result processors (filtering, deduplication, scoring, formatting)
- Prompt templates and LLM client cache/observability utils
e. Utilities & Configuration
- Config, logging, error handling, metadata, tenant-ID management, I/O helpers, LLM cache, observability utilities

##### External Services & Dependencies
- Cloud: AWS S3, AWS Neptune (graph DB), AWS Bedrock (LLM), OpenSearch (vector index), Aurora PostgreSQL
- Contrib modules: FalkorDB integration
- Jupyter notebooks and CloudFormation templates (in examples/) to deploy and demo the end-to-end flow

##### Relationships & Data Flow
- Ingestion → Extraction pipeline → Builds intermediate graph “model” objects
- Build pipeline → persists nodes/edges in Graph Store + vector embeddings in Vector Store
- Query engine → fetches from both stores → passes through retrievers → pipelines → LLM prompt → final answer
- Factored via interfaces (graph_store_factory, vector_store_factory) → allows plugin backends without changing core

##### Architectural Patterns & Principles
- Pipeline Pattern: clear separation between extract, build, load, query phases
- Factory & Strategy Patterns: storage backends and retriever algorithms are pluggable via factory methods
- Modularity: each concern in its own package (indexing.extract, indexing.build, storage.graph, storage.vector, retrieval)
- Multi-Tenancy: tenant ID tracking and multi-tenant store implementations

##### Essential Elements
- Notes on key technologies/frameworks: Python, AWS SDK, Jupyter notebooks, CloudFormation

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Ingestion & Extraction"
        SA["Source Adapters"]:::core
        EP["Extraction Pipeline"]:::core
    end

    subgraph "Graph Construction (Build)"
        BPO["Build Pipeline Orchestrator"]:::core
        NGB["Node/Graph Builders"]:::core
        CS["Checkpoint & Summary"]:::core
    end

    subgraph "Storage Abstractions & Plugins"
        GSI["Graph Store Interface & Factory"]:::core
        GImpl["Graph Store Implementations"]:::plugin
        VSI["Vector Store Interface & Factory"]:::core
        VImpl["Vector Store Implementations"]:::plugin
    end

    subgraph "Query & Retrieval"
        QE["Query Engine Entrypoint"]:::core
        R["Retriever Classes"]:::core
        PP["Post-Processors & Result Processors"]:::core
        PT["Prompt Templates & LLM Utilities"]:::core
    end

    subgraph "Utilities & Configuration"
        CFG["Config & Logging"]:::core
        ERR["Error Handling & Metadata"]:::core
        TID["Tenant ID Management"]:::core
        IO["I/O Helpers & Observability"]:::core
    end

    subgraph "Examples & Demos"
        CF["CloudFormation Templates"]:::example
        NB["Jupyter Notebooks"]:::example
    end

    subgraph "External Services"
        S3["AWS S3"]:::external
        NBK["AWS Bedrock"]:::external
        NEP["AWS Neptune"]:::external
        ES["OpenSearch"]:::external
        PG["Aurora PostgreSQL"]:::external
    end

    S3 -->|"SDK"| SA
    SA -->|"data"| EP
    EP -->|"extracts"| BPO
    BPO -->|"orchestrates"| NGB
    BPO -->|"manages"| CS
    NGB -->|"builds nodes"| GSI
    GSI -->|"factory"| GImpl
    CS -->|"summaries"| VSI
    VSI -->|"factory"| VImpl
    QE -->|"fetch"| GSI
    QE -->|"fetch"| VSI
    GImpl -->|"Gremlin/HTTP"| NEP
    VImpl -->|"SQL/SDK"| PG
    VImpl -->|"REST"| ES
    NBK -->|"LLM calls"| PT
    PT -->|"prompts"| QE
    QE -->|"pipeline"| R
    R -->|"outputs"| PP
    PP -->|"processed"| QE
    QE -->|"answer"| User[(User)]
    NB -->|"demo flow"| QE
    CF -->|"deploy infra"| S3

    click SA "https://github.com/awslabs/graphrag-toolkit/tree/main/lexical-graph/src/graphrag_toolkit/lexical_graph/indexing/load"
    click EP "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/indexing/extract/extraction_pipeline.py"
    click BPO "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/indexing/build/build_pipeline.py"
    click NGB "https://github.com/awslabs/graphrag-toolkit/tree/main/lexical-graph/src/graphrag_toolkit/lexical_graph/indexing/build/"
    click CS "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/indexing/build/checkpoint.py"
    click CS "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/indexing/build/graph_summary_builder.py"
    click GSI "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/storage/graph/graph_store.py"
    click GSI "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/storage/graph/graph_store_factory.py"
    click GImpl "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/storage/graph/dummy_graph_store.py"
    click GImpl "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/storage/graph/multi_tenant_graph_store.py"
    click GImpl "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/storage/graph/neptune_graph_stores.py"
    click VSI "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/storage/vector/vector_store.py"
    click VSI "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/storage/vector/vector_store_factory.py"
    click VImpl "https://github.com/awslabs/graphrag-toolkit/tree/main/lexical-graph/src/graphrag_toolkit/lexical_graph/storage/vector/"
    click QE "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/lexical_graph_query_engine.py"
    click R "https://github.com/awslabs/graphrag-toolkit/tree/main/lexical-graph/src/graphrag_toolkit/lexical_graph/retrieval/retrievers"
    click PP "https://github.com/awslabs/graphrag-toolkit/tree/main/lexical-graph/src/graphrag_toolkit/lexical_graph/retrieval/post_processors"
    click PP "https://github.com/awslabs/graphrag-toolkit/tree/main/lexical-graph/src/graphrag_toolkit/lexical_graph/retrieval/processors"
    click PT "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/retrieval/prompts.py"
    click PT "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/retrieval/utils/llm_cache.py"
    click CFG "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/config.py"
    click CFG "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/logging.py"
    click ERR "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/errors.py"
    click ERR "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/metadata.py"
    click TID "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/tenant_id.py"
    click IO "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/utils/io_utils.py"
    click IO "https://github.com/awslabs/graphrag-toolkit/blob/main/lexical-graph/src/graphrag_toolkit/lexical_graph/utils/fm_observability.py"
    click CF "https://github.com/awslabs/graphrag-toolkit/tree/main/examples/lexical-graph/cloudformation-templates"
    click NB "https://github.com/awslabs/graphrag-toolkit/tree/main/examples/lexical-graph/notebooks"

    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef plugin fill:#fff3cd,stroke:#856404,color:#856404,stroke-dasharray: 5 5;
    classDef external fill:#d4edda,stroke:#155724,color:#155724,shape:cloud;
    classDef example fill:#f1f1f1,stroke:#6c757d,color:#6c757d,stroke-dasharray: 5 5;
    classDef User fill:#e2e3e5,stroke:#6c757d,color:#6c757d,shape:circle;
```
