# wilson101xx/vannaai-azure-snowflake architecture

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

- Interactive diagram: https://gitdiagram.com/wilson101xx/vannaai-azure-snowflake
- Repository: https://github.com/wilson101xx/vannaai-azure-snowflake

## Overview

##### Project type and purpose
- This is a full-stack AI-powered SQL assistant that exposes a FastAPI backend and a Streamlit frontend. It integrates Vanna.AI’s prompt-to-SQL capabilities with Azure AI Search as a vector database, and Snowflake as the data warehouse.
- Purpose: allow users to train on schemas, docs, prompt-SQL pairs and then ask natural-language questions to generate and run SQL, returning results and summaries.

##### File structure
- Top-level:
- src/api: FastAPI entrypoint (main.py), Pydantic schemas, routers for training and querying
- src/config: environment-variable loader
- src/core: implementation of Azure Search client, custom vector store handler, Snowflake handler, and a “Vanna” orchestrator
- src/services: business-logic helpers (Snowflake queries, training orchestration, Azure calls)
- src/tests: workflow tests
- streamlit-ui: Streamlit app that consumes the API
- Config files: example.env, requirements.txt, .gitignore
- Deployment: uvicorn run command in README

##### README for additional insights
- Tech stack: FastAPI, Pydantic, Snowflake Python connector, Azure AI Search vector store, Azure OpenAI embeddings, Streamlit
- Features: training endpoints (base data, documents, prompt/SQL, DDL), query endpoints (ask, suggested questions)
- Described custom vector store methods in azure_vectorstore.py (though filename in README differs slightly from file tree azure_custom_db.py)

##### Elements
- UI → API
- API → Service → Core → External
- External → Core → Service → API → UI
- Frontend: light blue rectangle
- API & Services: blue rectangles
- Core integrations: orange rectangles

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["Streamlit UI"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        Main["FastAPI Entrypoint\n(src/api/main.py)"]:::api
        RouterTrain["/training Routers"]:::api
        RouterQuery["/query Routers"]:::api
        Schemas["Pydantic Schemas"]:::api
        Config["Env Loader"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        ServiceTrain["Training Orchestration Service"]:::service
        ServiceAsk["Asking Snowflake Service"]:::service
        ServiceVanna["Vanna Calls Service"]:::service
    end

    %% Core Layer
    subgraph "Core Layer"
        AzureClient["Azure AI Search Client"]:::core
        AzureCustom["Custom Vector Store Handler"]:::core
        SFHandler["Snowflake Handler"]:::core
        VannaCore["Vanna Orchestrator"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        AzureSearch["Azure AI Search"]:::external
        AzureOpenAI["Azure OpenAI"]:::external
        SnowflakeDB["Snowflake"]:::external
    end

    %% Testing
    subgraph "Testing"
        Tests["Workflow Tests"]:::test
    end

    %% Connections: Frontend to API
    UI -->|"HTTP Requests"| Main

    %% API internal flows
    Main --> RouterTrain
    Main --> RouterQuery
    Main --> Config
    RouterTrain --> Schemas
    RouterQuery --> Schemas

    %% API to Services
    RouterTrain -->|"train pipeline"| ServiceTrain
    RouterQuery -->|"query pipeline"| ServiceAsk

    %% Service orchestration
    ServiceTrain --> ServiceVanna
    ServiceAsk --> ServiceVanna

    %% Services to Core
    ServiceTrain --> AzureClient
    ServiceTrain --> AzureCustom
    ServiceTrain --> SFHandler
    ServiceAsk --> AzureClient
    ServiceAsk --> AzureCustom
    ServiceAsk --> SFHandler
    ServiceVanna --> VannaCore

    %% Core to External
    AzureClient -->|"vector ops"| AzureSearch
    AzureCustom -->|"index/search"| AzureSearch
    VannaCore -->|"embeddings/chat"| AzureOpenAI
    SFHandler -->|"SQL exec"| SnowflakeDB

    %% Response flow back to UI
    SFHandler --> ServiceAsk
    ServiceAsk --> RouterQuery
    RouterQuery --> Main
    Main --> UI

    %% Tests
    Tests --> Main

    %% Click Events
    click UI "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/streamlit-ui/app.py"
    click Main "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/api/main.py"
    click RouterTrain "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/api/routers/training.py"
    click RouterQuery "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/api/routers/query.py"
    click Schemas "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/api/schemas.py"
    click Config "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/config/local_env.py"
    click AzureClient "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/core/azure_client.py"
    click AzureCustom "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/core/azure_custom_db.py"
    click SFHandler "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/core/sf_handler.py"
    click VannaCore "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/core/vanna.py"
    click ServiceAsk "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/services/asking_snowflake.py"
    click ServiceTrain "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/services/training.py"
    click ServiceVanna "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/services/vanna_calls.py"
    click Tests "https://github.com/wilson101xx/vannaai-azure-snowflake/blob/main/src/tests/workflow.py"

    %% Styles
    classDef frontend fill:#D0EFFF,stroke:#333,stroke-width:1px
    classDef api fill:#B0D0FF,stroke:#333,stroke-width:1px
    classDef service fill:#E0E0FF,stroke:#333,stroke-width:1px
    classDef core fill:#FFD580,stroke:#333,stroke-width:1px
    classDef external fill:#C0FFC0,stroke:#333,stroke-width:1px
    classDef test fill:#F0F0F0,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
```
