# azure-samples/azure-vector-database-samples architecture

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

- Interactive diagram: https://gitdiagram.com/azure-samples/azure-vector-database-samples
- Repository: https://github.com/azure-samples/azure-vector-database-samples

## Overview

##### Main Components
- Code Samples Modules – These are grouped by the specific Azure service used (e.g., Azure AI Search, Azure Cosmos DB for MongoDB vCore, Azure Cosmos DB for PostgreSQL, Azure Database for PostgreSQL, Azure Redis Cache, Fabric Real-Time Analytics (Kusto)). Each of these modules demonstrates similar flows but cater to different underlying vector database technologies.
- Evaluation Samples – Separate components that show how to verify/document performance, query accuracy, or compare data chunking methods.
- Infrastructure-as-Code (IaC) Artifacts – Bicep files and parameter templates that provision Azure resources such as Cognitive Search, PostgreSQL, Redis, Cosmos DB, and the virtual networks (vnet).
- Data Pipelines & Embeddings Ingestion – Jupyter Notebook scripts and environment files (Conda environment YAML files) that orchestrate the process of ingesting and querying embeddings.
- Best Practices – Documentation and guidelines available in the “best_practices” directory which provide supporting standards and directions.

##### Relationships and Interactions
- Data sources (documents, images, text) feed into pre-processing pipelines (as highlighted by the notebooks) to generate embeddings.
- Infrastructure components (IaC using Bicep) are used to deploy the necessary Azure services – link these resources to their controlling code samples.
- Evaluation samples interact with the deployed infrastructure by running queries or validation steps to measure performance and accuracy.
- Best practices overlay as a guide that informs the design and execution of these code samples and pipelines.

##### Important Architectural Patterns and Technologies
- Separation of concerns: Different directories isolate the sample implementations while common pipelines and environment templates help unify dependency management across samples.
- IaC pattern: Use of Bicep scripts for automated resource provisioning.
- Data ingestion workflow: Use of Python notebooks and Conda environments to define a reproducible pipeline for generating and querying embeddings.
- Modular design: Each Azure service sample acts as a modular component that can be deployed, tested, and scaled independently.
- External actors: Although not part of the typical running system, note that the repository explicitly does not cover LLM app development, so the focus is solely on vector embedding ingestion and database querying.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources and Ingestion Pipeline
    DS["Data Sources: Documents, Images, Text"]:::datasource
    DP["Embeddings Ingestion Pipeline (Jupyter & Conda)"]:::pipeline
    CommonDP["Common Embeddings Notebook"]:::pipeline
    DS -->|"feeds"| DP
    DP -->|"generates embeddings"| CommonDP

    %% Common Shared Functionalities Module
    Common["Common Shared Functionalities Module"]:::code
    CommonDP -->|"supports"| Common

    %% Code Samples Modules
    subgraph "Vector Database Samples"
        direction TB
        AIS["Azure AI Search Module"]:::code
        CosmosMongo["Azure Cosmos DB (MongoDB) Module"]:::code
        CosmosPostgres["Azure Cosmos DB (PostgreSQL) Module"]:::code
        AZPostgres["Azure Database for PostgreSQL Module"]:::code
        Redis["Azure Redis Cache Module"]:::code
        Kusto["Fabric Real-Time Analytics (Kusto) Module"]:::code
    end

    %% Connect Common Shared to each Sample Module
    Common -->|"shared functionalities"| AIS
    Common -->|"shared functionalities"| CosmosMongo
    Common -->|"shared functionalities"| CosmosPostgres
    Common -->|"shared functionalities"| AZPostgres
    Common -->|"shared functionalities"| Redis
    Common -->|"shared functionalities"| Kusto

    %% Data Pipeline Notebooks for each Code Sample
    AIS_DP["AI Search Data Pipeline Notebook"]:::pipeline
    CosmosMongo_DP["Cosmos Mongo Data Pipeline Notebook"]:::pipeline
    CosmosPostgres_DP["Cosmos Postgres Data Pipeline Notebook"]:::pipeline
    AZPostgres_DP["PostgreSQL Data Pipeline Notebook"]:::pipeline
    Redis_DP["Redis Data Pipeline Notebook"]:::pipeline
    Kusto_DP["Kusto Data Pipeline Notebook"]:::pipeline

    CommonDP -->|"triggers"| AIS_DP
    CommonDP -->|"triggers"| CosmosMongo_DP
    CommonDP -->|"triggers"| CosmosPostgres_DP
    CommonDP -->|"triggers"| AZPostgres_DP
    CommonDP -->|"triggers"| Redis_DP
    CommonDP -->|"triggers"| Kusto_DP

    %% Link Data Pipeline Notebooks to their corresponding Modules
    AIS_DP -->|"ingests data into"| AIS
    CosmosMongo_DP -->|"ingests data into"| CosmosMongo
    CosmosPostgres_DP -->|"ingests data into"| CosmosPostgres
    AZPostgres_DP -->|"ingests data into"| AZPostgres
    Redis_DP -->|"ingests data into"| Redis
    Kusto_DP -->|"ingests data into"| Kusto

    %% Infrastructure-as-Code (IaC) nodes for each module
    AIS_IaC["Azure AI Search Infrastructure (Bicep)"]:::infrastructure
    CosmosMongo_IaC["Cosmos DB (MongoDB) Infrastructure (Bicep)"]:::infrastructure
    CosmosPostgres_IaC["Cosmos DB (PostgreSQL) Infrastructure (Bicep)"]:::infrastructure
    AZPostgres_IaC["Azure PostgreSQL Infrastructure (Bicep)"]:::infrastructure
    Redis_IaC["Azure Redis Cache Infrastructure (Bicep)"]:::infrastructure
    Common_IaC["Common Infrastructure (Bicep)"]:::infrastructure

    AIS -->|"provisioned by"| AIS_IaC
    CosmosMongo -->|"provisioned by"| CosmosMongo_IaC
    CosmosPostgres -->|"provisioned by"| CosmosPostgres_IaC
    AZPostgres -->|"provisioned by"| AZPostgres_IaC
    Redis -->|"provisioned by"| Redis_IaC
    Common -->|"supports with"| Common_IaC

    %% Evaluation and Best Practices
    Eval["Evaluation Samples Component"]:::evaluation
    BestPractices["Best Practices Documentation"]:::bestpractices

    %% Link Data Pipeline outputs to Evaluation Samples
    AIS_DP -->|"results"| Eval
    CosmosMongo_DP -->|"results"| Eval
    CosmosPostgres_DP -->|"results"| Eval
    AZPostgres_DP -->|"results"| Eval
    Redis_DP -->|"results"| Eval
    Kusto_DP -->|"results"| Eval

    %% Best Practices guides the Code Samples Modules
    BestPractices -.->|"guides"| AIS
    BestPractices -.->|"guides"| CosmosMongo
    BestPractices -.->|"guides"| CosmosPostgres
    BestPractices -.->|"guides"| AZPostgres
    BestPractices -.->|"guides"| Redis
    BestPractices -.->|"guides"| Kusto

    %% Click Events for Code Samples Modules
    click AIS "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/azure_ai_search"
    click CosmosMongo "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/azure_cosmosdb_mongo"
    click CosmosPostgres "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/azure_cosmosdb_postgresql"
    click AZPostgres "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/azure_postgresql"
    click Redis "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/azure_redis_cache"
    click Kusto "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/fabric_kusto"
    click Common "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/common"

    %% Click Events for IaC Artifacts
    click AIS_IaC "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/azure_ai_search/infrastructure"
    click CosmosMongo_IaC "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/azure_cosmosdb_mongo/infrastructure"
    click CosmosPostgres_IaC "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/azure_cosmosdb_postgresql/infrastructure"
    click AZPostgres_IaC "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/azure_postgresql/infrastructure"
    click Redis_IaC "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/azure_redis_cache/infrastructure"
    click Common_IaC "https://github.com/azure-samples/azure-vector-database-samples/tree/main/code_samples/common/infrastructure"

    %% Click Events for Data Pipelines Notebooks
    click AIS_DP "https://github.com/azure-samples/azure-vector-database-samples/blob/main/code_samples/azure_ai_search/python_sdk_sample/ai_search_sdk_data_pipeline.ipynb"
    click CosmosMongo_DP "https://github.com/azure-samples/azure-vector-database-samples/blob/main/code_samples/azure_cosmosdb_mongo/mongo_data_pipeline.ipynb"
    click CosmosPostgres_DP "https://github.com/azure-samples/azure-vector-database-samples/blob/main/code_samples/azure_cosmosdb_postgresql/azure_cosmosdb_postgresql_data_pipeline.ipynb"
    click AZPostgres_DP "https://github.com/azure-samples/azure-vector-database-samples/blob/main/code_samples/azure_postgresql/postgresql_data_pipeline.ipynb"
    click Redis_DP "https://github.com/azure-samples/azure-vector-database-samples/blob/main/code_samples/azure_redis_cache/redis_data_pipeline.ipynb"
    click Kusto_DP "https://github.com/azure-samples/azure-vector-database-samples/blob/main/code_samples/fabric_kusto/fabric_kusto_data_pipeline.ipynb"
    click CommonDP "https://github.com/azure-samples/azure-vector-database-samples/blob/main/code_samples/common/generate_embeddings.ipynb"

    %% Click Events for Evaluation and Best Practices
    click Eval "https://github.com/azure-samples/azure-vector-database-samples/tree/main/evaluation_samples"
    click BestPractices "https://github.com/azure-samples/azure-vector-database-samples/tree/main/best_practices"

    %% Styles
    classDef datasource fill:#FFFACD,stroke:#FFD700,stroke-width:2px;
    classDef pipeline fill:#E6FFFA,stroke:#00BFA5,stroke-width:2px;
    classDef code fill:#FFE6E6,stroke:#FF5733,stroke-width:2px;
    classDef infrastructure fill:#E6E6FF,stroke:#0000FF,stroke-width:2px;
    classDef evaluation fill:#E6FFE6,stroke:#28A745,stroke-width:2px;
    classDef bestpractices fill:#F0E68C,stroke:#B8860B,stroke-width:2px;
```
