# snowflake-labs/sfguide-getting-started-with-cortex-agents architecture

> Architecture diagram of the GitHub repository snowflake-labs/sfguide-getting-started-with-cortex-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snowflake-labs/sfguide-getting-started-with-cortex-agents
- Repository: https://github.com/snowflake-labs/sfguide-getting-started-with-cortex-agents

## Overview

##### Project Type and Purpose
- This is a lightweight full-stack analytics application built in Python, with a Streamlit front-end and Snowflake Cortex Agents powering AI-driven sales conversation analysis and semantic search.
- Key purpose: let sales teams query and analyze conversation transcripts via a simple UI, backed by Snowflake Cortex Search & Cortex Analyst.

##### File Structure
- Top-level files:
- streamlit.py – The Streamlit app entry point (UI + orchestration).
- sales_metrics_model.yaml – Configuration for metric extraction or model parameters.
- setup.sql – DDL/DML to provision Snowflake tables/stages for transcripts & metrics.
- README, LICENSE, .gitignore – Project metadata.
- There are no separate “frontend” and “backend” folders; the Streamlit script combines both layers.

##### Extract Architecture Hints from README
- Uses “Snowflake Cortex Search” for conversation analysis.
- Uses “Cortex Analyst” for semantic search.
- Exposes both via a unified Cortex Agents API.
- UI → Agents API → Snowflake → back to UI.

##### Main Components
a. User Interface (Streamlit App)
- Handles user input, displays charts & tables.
b. Application Logic / Service Layer
- Within streamlit.py:
- Configuration Loader (reads sales_metrics_model.yaml)
- Snowflake Connector & Cortex Agent Client
- Query Builder & Result Formatter
c. Data Layer (Snowflake)
- Tables/Stages provisioned by setup.sql (e.g., transcripts table, metrics table)
- Snowflake Cortex Search service (internal to Snowflake)
- Snowflake Cortex Analyst service
d. External AI/Services
- Cortex Agents API endpoint (wraps both Search & Analyst)
e. Configuration & Scripts
- sales_metrics_model.yaml (model definitions, metric thresholds)
- setup.sql (schema provisioning)

##### Relationships & Data Flow
- User interacts with Streamlit UI → UI triggers Python logic.
- Python logic reads YAML config → constructs Cortex Agents API calls.
- Cortex Agents API calls Snowflake Cortex Search & Analyst services.
- Snowflake returns raw & semantic search results.
- Python logic processes results → UI renders metrics and insights.

##### Architectural Patterns & Principles
- Single-page analytical app (all in streamlit.py) following a simple 3-tier pattern:
- Presentation (Streamlit UI)
- Service (Python Cortex Agent client + config)
- Data (Snowflake)
- Configuration-driven design via YAML.
- Clear separation between query orchestration and data storage/AI services.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Presentation & Service Layer"
        UI["Streamlit Python App (streamlit.py)"]:::ui
        subgraph "Service Layer"
            ConfigLoader["Configuration Loader"]:::service
            AgentClient["Cortex Agent Client"]:::service
            QueryFormatter["Query Builder & Result Formatter"]:::service
        end
    end

    ConfigLoader -->|reads config| salesMetrics["sales_metrics_model.yaml"]:::config
    UI -->|"user input"| ConfigLoader
    UI -->|"invoke API"| AgentClient
    AgentClient -->|formats queries| QueryFormatter

    ServiceLayer -->|REST/HTTP+JSON| CortexAPI["Cortex Agents API"]:::external

    subgraph "Snowflake Data Layer"
        Provisioning["Snowflake Tables/Stages\n(transcripts & metrics)"]:::data
        Search["Snowflake Cortex Search"]:::data
        Analyst["Snowflake Cortex Analyst"]:::data
    end

    setupScript["setup.sql"]:::config --> Provisioning
    CortexAPI --> Search
    CortexAPI --> Analyst
    Search -->|results| AgentClient
    Analyst -->|results| AgentClient
    QueryFormatter -->|processed data| UI

    subgraph "Project Metadata"
        README["README.md"]:::docs
        LICENSE["LICENSE"]:::docs
        GITIGNORE[".gitignore"]:::docs
    end

    %% Click Events
    click UI "https://github.com/snowflake-labs/sfguide-getting-started-with-cortex-agents/blob/main/streamlit.py"
    click salesMetrics "https://github.com/snowflake-labs/sfguide-getting-started-with-cortex-agents/blob/main/sales_metrics_model.yaml"
    click setupScript "https://github.com/snowflake-labs/sfguide-getting-started-with-cortex-agents/blob/main/setup.sql"
    click README "https://github.com/snowflake-labs/sfguide-getting-started-with-cortex-agents/blob/main/README.md"
    click LICENSE "https://github.com/snowflake-labs/sfguide-getting-started-with-cortex-agents/tree/main/LICENSE"
    click GITIGNORE "https://github.com/snowflake-labs/sfguide-getting-started-with-cortex-agents/blob/main/.gitignore"

    %% Styles
    classDef ui fill:#1f77b4,stroke:#000,color:#fff;
    classDef service fill:#adcbe3,stroke:#000,color:#000;
    classDef config fill:#cccccc,stroke:#000,color:#000;
    classDef external fill:#ff7f0e,stroke:#000,color:#000;
    classDef data fill:#98df8a,stroke:#000,color:#000;
    classDef docs fill:#eeeeee,stroke:#000,color:#000;
```
