# falahgs/graphrag-medical architecture

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

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

## Overview

##### Project type and purpose
- GraphRAG is an open-source Python library and CLI tool that implements a data-pipeline for transforming unstructured text into a knowledge-graph representation, enriching large-language-model (LLM) reasoning.
- Its main use cases are “indexing” (ingesting text, chunking, embeddings, graph construction, community extraction, summaries) and “querying” that index via LLM-augmented search.

##### File structure
- Top‐level modules:
- graphrag/cli: command‐line entrypoints (initialize, index, query, prompt_tune).
- graphrag/api: programmatic API wrappers around CLI-style operations.
- graphrag/config: config file/ENV loading, validation, defaults, pydantic models.
- graphrag/index: the indexing pipeline (configuring, running, all flow stages and operations).
- graphrag/query: the query engine (context building, retrieval adapters, structured search, question generation).
- graphrag/storage & cache: pipeline storage abstractions (file, blob, CosmosDB) and runtime caching strategies.
- graphrag/vector_stores: vector shop adapters (Azure Cognitive Search, Lancedb).
- graphrag/llm (under index and query): adapters to call LLM providers (OpenAI, mocks).
- Supporting modules:
- graphrag/logger: progress and console logging abstractions.
- graphrag/model: domain objects (Document, TextUnit, Community, Relationship).
- graphrag/prompt_tune & graphrag/prompts: prompt generation and tuning templates.
- Configuration, tests, examples, docs, and CI are present but not part of the runtime data flow.

##### README for additional insights
- Confirms two main workloads: GraphRAG “indexing” and “querying.”
- Points to extensibility via prompt-tuning and multiple storage back-ends.
- Reinforces that this is a demonstration toolkit for LLM + knowledge-graph pipelines.

##### Essential elements
- Don’t collapse strategy or factory modules—show them as extension points.
- Fallback or mock providers for testing.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        CLI["CLI Entrypoints"]:::compute
        API["Python API Facade"]:::compute
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        Config["Config Loader & Models"]:::config
    end

    %% Processing Layer
    subgraph "Processing Layer"
        subgraph "Indexing Pipeline" 
            IB["Pipeline Bootstrap & Config"]:::compute
            Flows["Flows & Stages"]:::compute
            Ops["Operations (chunk, embed, graph, summary)"]:::compute
            Inputs["Input Loaders"]:::compute
        end
        subgraph "Query Engine"
            Retrieval["Retrieval Adapters"]:::compute
            Context["Context Builder"]:::compute
            Search["Structured / Lightweight Search"]:::compute
            PromptGen["Question Generation"]:::compute
            QLLM["Query-side LLM Adapter"]:::ext
            Post["Post-Processing"]:::compute
        end
    end

    %% Integration Layer
    subgraph "Integration Layer"
        subgraph "Storage & Cache"
            StorageFactory["Storage Factory"]:::storage
            FileStorage["File / Blob / Cosmos / Memory"]:::storage
            CacheFactory["Cache Factory"]:::storage
            CacheImpl["JSON / Memory / No-op Cache"]:::storage
        end
        subgraph "Vector Store & LLM"
            VectorFactory["Vector Store Factory"]:::ext
            AzureVS["Azure Cognitive Search Adapter"]:::ext
            LanceDB["Lancedb Adapter"]:::ext
            IndexLLM["Index-side LLM Adapter"]:::ext
            QueryLLM["LLM Providers (OpenAI, Mock)"]:::ext
        end
    end

    %% Cross-cutting
    subgraph "Cross-Cutting"
        Logger["Logger & Progress"]:::log
        Callbacks["Callbacks & Workflow Hooks"]:::log
    end

    %% Flows
    CLI -->|"invoke"| Config
    API -->|"invoke"| Config
    Config -->|"load config"| IB
    IB --> Flows
    Flows --> Ops
    Ops --> Inputs
    Ops -->|embeddings, graph| StorageFactory
    Ops -->|embeddings, graph| VectorFactory
    Retrieval -->|query| VectorFactory
    Retrieval -->|cache lookup| CacheFactory
    VectorFactory --> QLLM
    Context --> PromptGen
    PromptGen --> QLLM
    QLLM --> Post
    Post -->|"return results"| API
    Post -->|"return results"| CLI

    %% Storage & Cache Connections
    StorageFactory --> FileStorage
    CacheFactory --> CacheImpl

    %% Vector Store & LLM Connections
    VectorFactory --> AzureVS
    VectorFactory --> LanceDB
    IndexLLM -->|"LLM calls"| IndexLLM
    QueryLLM -->|"LLM calls"| QueryLLM

    %% Cross-cutting Connections
    IB --> Logger
    Flows --> Logger
    Ops --> Logger
    Retrieval --> Logger
    QLLM --> Logger
    IB --> Callbacks
    Flows --> Callbacks
    Ops --> Callbacks
    Retrieval --> Callbacks
    Post --> Callbacks

    %% Click Events
    click CLI "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/cli/"
    click API "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/api/"
    click Config "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/config/"
    click IB "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/index/bootstrap.py"
    click IB "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/index/create_pipeline_config.py"
    click Flows "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/index/flows/"
    click Ops "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/index/operations/"
    click Inputs "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/index/input/factory.py"
    click Inputs "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/index/input/text.py"
    click Inputs "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/index/input/csv.py"
    click Retrieval "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/query/structured_search/"
    click Context "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/query/context_builder/"
    click PromptGen "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/query/question_gen/"
    click QLLM "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/query/llm/get_client.py"
    click StorageFactory "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/storage/factory.py"
    click FileStorage "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/storage/file_pipeline_storage.py"
    click FileStorage "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/storage/blob_pipeline_storage.py"
    click FileStorage "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/storage/cosmosdb_pipeline_storage.py"
    click FileStorage "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/storage/memory_pipeline_storage.py"
    click CacheFactory "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/cache/factory.py"
    click CacheImpl "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/cache/json_pipeline_cache.py"
    click CacheImpl "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/cache/memory_pipeline_cache.py"
    click CacheImpl "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/cache/noop_pipeline_cache.py"
    click VectorFactory "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/vector_stores/factory.py"
    click AzureVS "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/vector_stores/azure_ai_search.py"
    click LanceDB "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/vector_stores/lancedb.py"
    click IndexLLM "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/index/llm/load_llm.py"
    click IndexLLM "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/index/llm/manager.py"
    click IndexLLM "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/index/llm/mock_llm.py"
    click QueryLLM "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/query/llm/base.py"
    click QueryLLM "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/query/llm/oai/"
    click Logger "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/logger/factory.py"
    click Logger "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/logger/console.py"
    click Logger "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/logger/rich_progress.py"
    click Logger "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/logger/print_progress.py"
    click Logger "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/logger/null_progress.py"
    click Callbacks "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/callbacks/factory.py"
    click Callbacks "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/callbacks/console_workflow_callbacks.py"
    click Callbacks "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/callbacks/blob_workflow_callbacks.py"
    click Callbacks "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/callbacks/file_workflow_callbacks.py"
    click Callbacks "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/callbacks/progress_workflow_callbacks.py"
    click Callbacks "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/callbacks/global_search_callbacks.py"
    click Callbacks "https://github.com/falahgs/graphrag-medical/blob/main/graphrag/callbacks/llm_callbacks.py"
    click PromptGen "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/prompt_tune/generator/"
    click PromptGen "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/prompt_tune/prompt/"
    click PromptGen "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/prompt_tune/template/"
    click PromptGen "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/prompts/index/"
    click PromptGen "https://github.com/falahgs/graphrag-medical/tree/main/graphrag/prompts/query/"

    %% Styles
    classDef compute fill:#cce5ff,stroke:#005cbf,color:#004085
    classDef storage fill:#d4edda,stroke:#155724,color:#155724
    classDef ext fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef config fill:#ffeeba,stroke:#856404,color:#856404
    classDef log fill:#f8f9fa,stroke:#6c757d,color:#495057
```
