# azure-samples/graphrag-accelerator architecture

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

- Interactive diagram: https://gitdiagram.com/azure-samples/graphrag-accelerator
- Repository: https://github.com/azure-samples/graphrag-accelerator

## Overview

##### Project Type and Purpose
- This is a full-stack “solution accelerator” that wraps the Microsoft graphrag library to expose REST APIs (indexing pipelines + graph-based query) and a Streamlit UI.
- Its goal is to run a hosted service on Azure with auto-scaling, security, logging, and managed identity.

##### File Structure
- Top-level separation:
- backend/ → Python FastAPI-style app (“graphrag_app”) plus unit/integration tests, CLI scripts, Bicep manifests for CronJob/Job
- frontend/ → Streamlit UI (app.py), components, deploy scripts
- infra/ → Azure Bicep modules (AKS, ACR, APIM, CosmosDB, AoAI, Search, Networking, RBAC, Monitoring), Helm chart for AKS, deploy scripts
- notebooks/ → example Jupyter workflows (Quickstart + Advanced)
- CI config (.github/workflows, .azdo/azure-pipeline.yaml) and Dockerfiles for local/dev containers
- Architectural patterns:
- Micro-service API layer (graphrag_app)
- Serverless/VM-based cron jobs for indexing
- Containerized frontend + backend on AKS (via Helm)
- Infrastructure as Code (IaC) with Bicep + Helm
- API Management fronting the service, secure by Azure AD

##### Extract Key Points from the README
- Hosted services incur cost—uses multiple Azure components (see infra/main.bicep).
- Deployment + Development Guides explain end-to-end provisioning and local development.

a. Main Components
- Users (Clients) – Web UI (Streamlit) or external client apps / notebooks
- Frontend – Streamlit service deployed (AKS or static)
- API Layer – graphrag_app running in containers on AKS
- Batch/CRON Jobs – Kubernetes CronJob or standalone Job pods
- Azure API Management – public entrypoint for APIs (graphrag-api & docs-api)
- Azure Kubernetes Service (AKS) – hosts containers
- Azure Container Registry (ACR) – Docker images
- Azure Cosmos DB – graph storage (knowledge graph)
- Azure Cognitive Search – indexing service
- Azure OpenAI (AoAI) – LLM inference
- Blob Storage – raw data for ingestion
- Azure Monitor / App Insights / Log Analytics – telemetry & logs
- Azure AD – authentication/authorization (managed identity)
- DevOps – GitHub Actions / Azure Pipelines for CI/CD, IaC deployments

b. Relationships & Data Flows
1. Developer commits → CI pipeline builds container → pushes to ACR
2. CI triggers Bicep/Helm deployment → AKS, APIM, Cosmos, Search, AoAI, Storage, Monitoring deployed
3. User/browser → HTTPS → APIM → routes to graphrag_app on AKS
4. graphrag_app → Azure AD (token auth) and AoAI for embeddings/inference
5. graphrag_app (API / CronJobs) → Blob Storage (ingest) → Cognitive Search & Cosmos DB for indexing
6. Streamlit UI → calls graphrag_app via APIM
7. Metrics/logs → App Insights + Log Analytics

c. Architectural Patterns & Principles
- Separation of concerns: frontend vs. backend vs. infra
- Infrastructure as Code: Bicep modules + Helm chart
- Cloud-native: containerized microservices on AKS, PaaS services (CosmosDB, Search, AoAI)
- Event-driven/batch indexing via Kubernetes jobs
- Security by default: API Management + Azure AD + Private Endpoints + RBAC

d. Technologies & Frameworks
- Python, FastAPI (or equivalent)
- Streamlit
- Azure Bicep, Helm
- Kubernetes (AKS)
- Azure API Management
- Azure Cosmos DB, Search, Blob Storage
- Azure OpenAI
- Azure Monitor / App Insights
- GitHub Actions / Azure Pipelines
- Docker, devcontainers

##### Detail without Overthinking
- Don’t omit any major piece: include CI/CD, IaC, ingress, compute, storage, monitoring, identity
- Both real-time (API) and batch (CronJob) flows
- Detail how frontend and notebooks consume the API

## Diagram (Mermaid)

```mermaid
graph TB
    %% Users & Clients
    subgraph "Users & Clients"
        direction TB
        Browser["Web Browser"]:::external
        ExternalApp["External SDK/Notebooks"]:::external
    end

    %% Kubernetes Cluster (AKS)
    subgraph "Kubernetes Cluster (AKS)"
        direction TB
        StreamlitUI["Streamlit UI"]:::container
        subgraph "Backend Services"
            direction TB
            APIApp["graphrag_app (FastAPI)"]:::container
            CronJobs["Batch/CronJobs"]:::container
        end
    end

    %% Azure PaaS Services
    subgraph "Azure PaaS Services"
        direction TB
        APIM["Azure API Management"]:::paas
        ACR["Azure Container Registry"]:::paas
        CosmosDB["Azure Cosmos DB"]:::paas
        Search["Azure Cognitive Search"]:::paas
        AoAI["Azure OpenAI (AoAI)"]:::paas
        BlobStorage["Blob Storage"]:::paas
        AzureAD["Azure AD"]:::external
        Monitor["Azure Monitor / App Insights"]:::paas
    end

    %% IaC & CI/CD
    subgraph "Infrastructure as Code & CI/CD"
        direction TB
        CI["CI/CD Pipelines"]:::infra
        BicepHelm["Bicep Modules & Helm Chart"]:::infra
        DeployScripts["Deploy Scripts"]:::infra
    end

    %% Notebooks Lane
    subgraph "Notebooks & SDK"
        direction TB
        QuickstartNB["1-Quickstart.ipynb"]:::external
        AdvancedNB["2-Advanced_Getting_Started.ipynb"]:::external
        SDKScript["get-wiki-articles.py"]:::external
    end

    %% Relationships
    Browser -->|"HTTPS"| APIM
    ExternalApp -->|"SDK/API" | APIM
    APIM -->|"routes to"| APIApp
    StreamlitUI -->|"calls API"| APIM
    APIApp -->|"Azure AD Auth"| AzureAD
    APIApp -->|"embeddings/inference"| AoAI
    APIApp -->|"ingest/read"| BlobStorage
    CronJobs -->|"indexing"| Search
    CronJobs -->|"store graph"| CosmosDB
    APIApp -->|"query graph"| CosmosDB
    APIApp -->|"search index"| Search
    APIApp -->|"logs & metrics"| Monitor
    CI -->|"build images"| ACR
    CI -->|"deploy infra"| BicepHelm
    BicepHelm -->|"provision resources"| AKS[("AKS Cluster")]
    BicepHelm --> CosmosDB
    BicepHelm --> Search
    BicepHelm --> AoAI
    BicepHelm --> BlobStorage
    BicepHelm --> APIM
    BicepHelm --> Monitor
    DeployScripts --> BicepHelm
    QuickstartNB -->|"Python SDK"| APIApp
    AdvancedNB -->|"Python SDK"| APIApp
    SDKScript -->|"Python SDK"| APIApp

    %% Click Events - Backend
    click APIApp "https://github.com/azure-samples/graphrag-accelerator/tree/main/backend/graphrag_app"
    click Browser "https://github.com/azure-samples/graphrag-accelerator/blob/main/frontend/app.py"
    click StreamlitUI "https://github.com/azure-samples/graphrag-accelerator/blob/main/frontend/app.py"
    click CronJobs "https://github.com/azure-samples/graphrag-accelerator/blob/main/backend/manifests/cronjob.yaml"
    click CronJobs "https://github.com/azure-samples/graphrag-accelerator/blob/main/backend/manifests/job.yaml"
    click APIApp "https://github.com/azure-samples/graphrag-accelerator/blob/main/backend/graphrag_app/main.py"
    click APIApp "https://github.com/azure-samples/graphrag-accelerator/tree/main/backend/graphrag_app/api"
    click APIApp "https://github.com/azure-samples/graphrag-accelerator/tree/main/backend/graphrag_app/logger"
    click APIApp "https://github.com/azure-samples/graphrag-accelerator/blob/main/backend/graphrag_app/utils/azure_clients.py"
    click APIApp "https://github.com/azure-samples/graphrag-accelerator/blob/main/backend/graphrag_app/utils/pipeline.py"
    click APIApp "https://github.com/azure-samples/graphrag-accelerator/blob/main/backend/graphrag_app/typing/models.py"
    click APIApp "https://github.com/azure-samples/graphrag-accelerator/blob/main/backend/graphrag_app/typing/pipeline.py"
    click CronJobs "https://github.com/azure-samples/graphrag-accelerator/blob/main/backend/scripts/indexer.py"
    click CronJobs "https://github.com/azure-samples/graphrag-accelerator/blob/main/backend/scripts/job-scheduler.py"
    click APIApp "https://github.com/azure-samples/graphrag-accelerator/tree/main/backend/tests/unit"
    click APIApp "https://github.com/azure-samples/graphrag-accelerator/tree/main/backend/tests/integration"
    click CI "https://github.com/azure-samples/graphrag-accelerator/tree/main/docker/Dockerfile-backend"
    click Browser "https://github.com/azure-samples/graphrag-accelerator/tree/main/docker/Dockerfile-frontend"
    click Browser "https://github.com/azure-samples/graphrag-accelerator/tree/main/frontend/src/components"
    click Browser "https://github.com/azure-samples/graphrag-accelerator/blob/main/frontend/src/graphrag_api.py"
    click Browser "https://github.com/azure-samples/graphrag-accelerator/blob/main/frontend/src/functions.py"
    click Browser "https://github.com/azure-samples/graphrag-accelerator/blob/main/frontend/deploy.sh"
    click Browser "https://github.com/azure-samples/graphrag-accelerator/blob/main/frontend/frontend_deploy.parameters.json"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/acr/acr.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/aks/aks.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/apim/apim.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/apim/apim.graphrag-api.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/apim/apim.graphrag-docs-api.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/tree/main/infra/core/apim/policies"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/cosmosdb/cosmosdb.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/ai-search/ai-search.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/aoai/aoai.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/storage/storage.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/identity/identity.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/rbac/aks-rbac.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/rbac/aoai-rbac.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/rbac/workload-identity-rbac.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/tree/main/infra/core/vnet"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/monitor/app-insights.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/core/log-analytics/log.bicep"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/helm/graphrag/Chart.yaml"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/tree/main/infra/helm/graphrag/templates"
    click BicepHelm "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/helm/graphrag/values.yaml"
    click DeployScripts "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/main.bicep"
    click DeployScripts "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/deploy.sh"
    click DeployScripts "https://github.com/azure-samples/graphrag-accelerator/blob/main/infra/deploy.parameters.json"
    click CI "https://github.com/azure-samples/graphrag-accelerator/blob/main/.github/workflows/dev.yaml"
    click CI "https://github.com/azure-samples/graphrag-accelerator/blob/main/.github/workflows/tests.yaml"
    click CI "https://github.com/azure-samples/graphrag-accelerator/blob/main/.azdo/azure-pipeline.yaml"
    click CI "https://github.com/azure-samples/graphrag-accelerator/tree/main/.devcontainer/Dockerfile"
    click CI "https://github.com/azure-samples/graphrag-accelerator/blob/main/.devcontainer/devcontainer.json"
    click CI "https://github.com/azure-samples/graphrag-accelerator/blob/main/.devcontainer/entrypoint.sh"
    click QuickstartNB "https://github.com/azure-samples/graphrag-accelerator/blob/main/notebooks/1-Quickstart.ipynb"
    click AdvancedNB "https://github.com/azure-samples/graphrag-accelerator/blob/main/notebooks/2-Advanced_Getting_Started.ipynb"
    click SDKScript "https://github.com/azure-samples/graphrag-accelerator/blob/main/notebooks/get-wiki-articles.py"

    %% Styles
    classDef container fill:#cde8ff,stroke:#0366d6,stroke-width:2px
    classDef paas fill:#d1f2d1,stroke:#238b45,stroke-width:2px
    classDef infra fill:#ffe5b4,stroke:#cc8400,stroke-width:2px
    classDef external fill:#e0e0e0,stroke:#666666,stroke-width:2px
```
