# vanna-ai/vanna-streamlit architecture

> Architecture diagram of the GitHub repository vanna-ai/vanna-streamlit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vanna-ai/vanna-streamlit
- Repository: https://github.com/vanna-ai/vanna-streamlit

## Overview

##### Project type and purpose
- This is a lightweight full-stack web application built with Streamlit.
- Purpose: Provide a web UI (“app.py”) that collects user input, calls the Vanna.AI API using functions in “vanna_calls.py”, and renders the results in the browser.

##### File structure
- Top level:
- app.py (Streamlit entry point / UI layer)
- vanna_calls.py (business logic / API-integration layer)
- assets/ (static images and demo GIF)
- .streamlit/config.toml (runtime configuration & secrets)
- requirements.txt (Python dependencies)
- No database or persistent storage—purely an API-driven app.

##### Key insights from the README
- Streamlit front end is run via “streamlit run app.py.”
- Vanna credentials are configured in .streamlit/secrets.toml and accessed via st.secrets.
- vanna_calls.setup_vanna() is where the API client is configured.

##### Main components
a. User (Web Browser)
b. Streamlit Server (app.py)
c. Business Logic Module (vanna_calls.py)
d. Configuration / Secrets Store (.streamlit/secrets.toml)
e. External Vanna.AI API Service
f. Static Asset Store (assets folder)

##### Relationships and data flow
1. User opens a browser and navigates to the local Streamlit server.
2. Streamlit Server (app.py) renders UI elements and serves static assets (assets/).
3. On user action, app.py calls functions in vanna_calls.py.
4. vanna_calls reads API keys from .streamlit/secrets.toml (via Streamlit secrets API).
5. vanna_calls makes HTTP requests to the Vanna.AI API.
6. Vanna.AI processes the requests and returns responses.
7. vanna_calls parses the response and returns structured data to app.py.
8. app.py updates the UI with results, which the browser displays.

##### Architectural patterns and principles
- Separation of concerns: UI layer (app.py) vs. API logic layer (vanna_calls.py) vs. configuration.
- External service integration: clear boundary between your code and Vanna.AI API.
- No database layer or caching—stateless per request.

##### Technologies and frameworks
- Streamlit for UI and serving.
- Python 3 virtual environment (requirements.txt).
- HTTP REST calls to Vanna.AI.
- Streamlit secrets for secure configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["User Browser"]:::external
    Streamlit["Streamlit App (app.py)"]:::frontend
    Assets["Assets Folder"]:::frontend
    VannaCalls["Vanna Calls Module (vanna_calls.py)"]:::logic
    Secrets[".streamlit/config.toml"]:::config
    VannaAPI["Vanna.AI API"]:::external

    Browser -->|"HTTP GET"| Streamlit
    Streamlit -->|"serves assets"| Assets
    Streamlit -->|"calls setup_vanna()/ask"| VannaCalls
    VannaCalls -->|"reads secrets"| Secrets
    VannaCalls -->|"REST request"| VannaAPI
    VannaAPI -->|"REST response"| VannaCalls
    VannaCalls -->|"returns data"| Streamlit
    Streamlit -->|"renders UI"| Browser

    click Streamlit "https://github.com/vanna-ai/vanna-streamlit/blob/main/app.py"
    click Assets "https://github.com/vanna-ai/vanna-streamlit/tree/main/assets/"
    click VannaCalls "https://github.com/vanna-ai/vanna-streamlit/blob/main/vanna_calls.py"
    click Secrets "https://github.com/vanna-ai/vanna-streamlit/blob/main/.streamlit/config.toml"

    classDef frontend fill:#ADD8E6,stroke:#000
    classDef logic fill:#90EE90,stroke:#000
    classDef config fill:#D3D3D3,stroke:#000
    classDef external fill:#FFA500,stroke:#000
```
