# azure/gpt-rag architecture

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

- Interactive diagram: https://gitdiagram.com/azure/gpt-rag
- Repository: https://github.com/azure/gpt-rag

## Overview

##### Project’s Main Components
- Infrastructure Provisioning:
– Bicep templates (found under the “infra” directory) that deploy core Azure resources: AI services, Cosmos DB, App Insights, App Service (including Functions, App Service Plan, and App Service Environment), Virtual Networks, Private Endpoints, and Security components (KeyVault, role assignments, etc.).
– These templates are arranged into logical groups (ai, db, host, load testing, network, search, security, storage, vm, and util) that indicate a tightly defined infrastructure layer.
- CI/CD and Automation:
– Azure DevOps and GitHub workflows (under “.azdo” and “.github”) that define build, deployment, load testing, and provisioning pipelines.
- Application Components and Data Flow:
– Orchestrator: The heart of the solution (with options for Functional using Semantic Kernel functions or Agentic via AutoGen).
– Data Ingestion (separately referenced, residing in its own repository) that handles document chunking, indexing, and data updates.
– App Front-End: Implements a backend-for-frontend pattern to present the service over a web interface.
- Supporting Artifacts:
– Scripts (in “scripts”) aid in component cleanup, provisioning, and post/pre-deployment automation.
– Documentation (in “docs”) explaining deployment (including both Basic and Zero Trust architectures), customization, troubleshooting, and performance testing.
- Ancillary/Optional Components:
– Load testing artifacts (in “loadtest”) that can be used to verify system performance under various loads.

##### Mapping Relationships and Interactions
– Start with the cloud deployment environment (Azure) where the infrastructure is provisioned using Bicep files.
– Show CI/CD pipelines triggering the deployment (the “azure.yml” and pipelines in “.azdo”/“.github”) to the provisioning layer.
– Optionally note how security configurations (KeyVault, network isolation in Zero Trust setups) mediate communication among components.

##### Architectural Patterns and Principles
- Modular Architecture: Clearly separate Data Ingestion, the Orchestrator (with dual deployment options), and the App Front-End components.
- CI/CD and Infrastructure as Code (IaC): Illustrate the integration of pipelines with Bicep-based resource deployment, emphasizing automated provisioning and updates.
- Zero Trust Security: If designing for production, include additional layers for network isolation, Identity management (via Azure Entra ID), and secure role assignments (as pointed out in key security bicep templates).
- Backends-for-Frontends (BFF): Clearly illustrate the web interface’s dedicated API layer, which is designed to optimize the front-end’s scalability and responsiveness.

##### Relevant Technologies and Frameworks to Annotate
- Azure services (App Service, Functions, Cosmos DB, KeyVault, AI Services, AI Search, VNet, etc.)
- Deployment/configuration using Bicep templates.
- CI/CD orchestration via Azure Developer CLI (azd), Azure DevOps, and GitHub Actions.
- Scripting (Powershell, Bash) to support automation.
- Languages: Bicep, Powershell, Node.js, and Python within the orchestration and application logic.

##### Essential Elements
- Use clear, descriptive labels for each component (e.g., “App Service – Orchestrator (Agentic/Functional)”, “Cosmos DB”, “Storage Account for Document Upload”, “Azure AI Search Service”).
- Interactions that are security-critical (such as key vault accesses and role assignments) to emphasize the Zero Trust considerations.

Final Note:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD and Automation Layer
    subgraph "CI/CD and Automation"
        A1["Azure DevOps Pipelines (.azdo)"]
        A2["GitHub Workflows (.github)"]
    end

    %% Infrastructure Provisioning Layer
    subgraph "Infrastructure Provisioning (Azure Resources)"
        B0["Bicep Templates"]
        B1["AI Services"]
        B2["Cosmos DB"]
        B3["App Service (Orchestrator)"]
        B4["Functions (Orchestrator)"]
        B5["VNet & Private Endpoints"]
        B6["Search Services"]
        B7["KeyVault & Security"]
    end

    %% Application Components Layer
    subgraph "Application Components"
        C1["Data Ingestion Service"]
        C2["Orchestrator API (Agentic/Functional)"]
        C3["App Front-End (BFF)"]
    end

    %% Supporting Artifacts
    subgraph "Supporting Artifacts"
        D1["Scripts & Automation"]
        D2["Documentation"]
        D3["Load Testing Artifacts"]
    end

    %% CI/CD to Infrastructure
    A1 --> B0
    A2 --> B0
    D1 --> B0

    %% Infrastructure: Bicep Templates deploy to Azure Resources
    B0 --> B1
    B0 --> B2
    B0 --> B3
    B0 --> B4
    B0 --> B5
    B0 --> B6
    B0 --> B7

    %% Infrastructure to Application Layer (Orchestrator API deployment)
    B3 -->|"deploys_API"| C2
    B4 -->|"deploys_API"| C2

    %% Data flow from Data Ingestion to data stores
    C1 -->|"indexes_data"| B2
    C1 -->|"queries_data"| B6

    %% App Front-End calls Orchestrator API
    C3 -->|"calls_API"| C2

    %% Orchestrator API secures communications via KeyVault
    C2 -->|"secures"| B7

    %% Optional: Load Testing targets App Front-End
    D3 -->|"tests_performance"| C3

    %% Click Events for Infrastructure Provisioning
    click B0 "https://github.com/azure/gpt-rag/tree/main/infra"
    click B1 "https://github.com/azure/gpt-rag/blob/main/infra/core/ai/aiservices.bicep"
    click B2 "https://github.com/azure/gpt-rag/blob/main/infra/core/db/cosmos.bicep"
    click B3 "https://github.com/azure/gpt-rag/blob/main/infra/core/host/appservice.bicep"
    click B4 "https://github.com/azure/gpt-rag/blob/main/infra/core/host/functions.bicep"
    click B5 "https://github.com/azure/gpt-rag/blob/main/infra/core/network/vnet.bicep"
    click B6 "https://github.com/azure/gpt-rag/blob/main/infra/core/search/search-services.bicep"
    click B7 "https://github.com/azure/gpt-rag/blob/main/infra/core/security/keyvault.bicep"

    %% Click Events for CI/CD and Automation
    click A1 "https://github.com/azure/gpt-rag/blob/main/.azdo/azure-dev.yml"
    click A2 "https://github.com/azure/gpt-rag/blob/main/.github/azure-dev.yml"

    %% Click Events for Supporting Artifacts
    click D1 "https://github.com/azure/gpt-rag/tree/main/scripts"
    click D2 "https://github.com/azure/gpt-rag/tree/main/docs"
    click D3 "https://github.com/azure/gpt-rag/tree/main/loadtest"

    %% Styles
    classDef cicd fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
    classDef infra fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef app fill:#d6eaf8,stroke:#2e86c1,stroke-width:2px;
    classDef support fill:#fadbd8,stroke:#c0392b,stroke-width:2px;

    class A1,A2 cicd;
    class B0,B1,B2,B3,B4,B5,B6,B7 infra;
    class C1,C2,C3 app;
    class D1,D2,D3 support;
```
