# aswinpookkatt/genieverse architecture

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

- Interactive diagram: https://gitdiagram.com/aswinpookkatt/genieverse
- Repository: https://github.com/aswinpookkatt/genieverse

## Overview

##### Project type and purpose
- **Type**: Full-stack, voice-enabled data analysis application built with Streamlit.
- **Purpose**: Convert user voice or text input into SQL queries, execute them against DuckDB or Databricks, and render analytic visualizations. It includes user authentication, session management, SQL sanitization, data profiling, and AI-powered query generation via Google Gemini.

##### File structure
- **Top-level scripts**:
- login.py, home.py → Authentication and landing pages
- app.py, app_01.py, test.py → Voice and text query entry points
- ui.py → Shared UI helper functions
- router.py → Directs an NL request to the appropriate AI agent
- agents.py → Implements “Data Engineer” & “Visualization” agents
- prompts.py → Templates for AI prompts
- utils.py → Database connection, query execution, sanitization
- **Folders**:
- data/ → Sample CSVs, DuckDB files, and database-setup scripts
- data_scanner/ → Data profiling (anomaly detection) & data quality checks
- static/ → Images and assets (e.g., the logo)
- .streamlit/ → Streamlit config and secrets for API keys & DB paths
- **Configs & dependencies**: requirements.txt, .streamlit/config.toml, .streamlit/secrets.toml

##### README for additional insights
- Architecture callouts: Authentication, AI agents, voice features, data analysis, UI components, configuration.
- External dependencies: Google Gemini API, DuckDB or Databricks, Plotly, streamlit-mic-recorder.

a. **Main components**
- **User Interface (Streamlit Frontend)**
- Login page → Session manager
- Home/dashboard → Buttons for text/voice input
- Visualization canvas (Plotly charts)
- **Voice/Text Input Processing**
- streamlit-mic-recorder (voice) → Speech-to-text conversion
- **Application Logic Layer**
- router.py → Routes request to correct agent
- agents.py →
– Data Engineer Agent (generates SQL)
– Visualization Agent (chooses chart type, builds JSON config)
- prompts.py → AI-prompt templates
- **AI Service**
- Google Gemini (external API)
- **Data Access Layer**
- utils.py → DB connection pool, query execution, sanitization, modification detection
- Data Scanner micro-service → data_profiler.py & data_quality.py
- **Persistence**
- DuckDB (local .duckdb files) or Databricks SQL Warehouse
- users_db.duckdb for authentication and chat history
- **Static Assets**
- static/ for images
b. **Relationships and data flow**
1. User interacts with Streamlit UI → selects voice or text mode.
3. router.py receives input → picks an agent based on context.
4. Agent sends prompt + schema info to Google Gemini → receives SQL or visualization instructions.
5. utils.py executes SQL against DuckDB/Databricks → returns result set.
6. Visualization Agent formats results into Plotly charts → UI renders them.
7. Data Scanner can be invoked for profiling → writes reports back to UI.
8. Session data & chat history stored in users_db.duckdb.
c. **Architectural patterns**
- **Layered architecture**: UI → Application logic → Data access → Storage
- **Micro-services style**: Data Scanner as a self-contained component
- **API integration**: External AI service (Google Gemini) decoupled via router
d. **Key technologies**
- Streamlit (UI)
- streamlit-mic-recorder (voice capture)
- Google Gemini API (NLP → SQL)
- DuckDB / Databricks (storage & analytics)
- Plotly (visualizations)
- Python modules: agents.py, router.py, utils.py, data_scanner/*

##### Elements
- **Clear labels**: name each module (e.g., “Data Engineer Agent”)
- Blue rectangles for components/modules
- Orange parallelogram for static assets

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Streamlit UI)"
        direction TB
        LoginPage["Login Page"]:::frontend
        Home["Home / Dashboard"]:::frontend
        VoiceRecorder["Voice Input (streamlit-mic-recorder)"]:::frontend
        TextInput["Text Input Box"]:::frontend
        UIHelpers["Shared UI Helpers"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Application Logic)"
        direction TB
        Router["Request Router"]:::backend
        DataEngineerAgent["Data Engineer Agent"]:::backend
        VizAgent["Visualization Agent"]:::backend
        Prompts["AI Prompt Templates"]:::backend
        Utils["Database Utilities"]:::backend
    end

    %% Data Scanner Micro-service
    subgraph "Data Scanner Service"
        direction TB
        DataProfiler["data_profiler.py"]:::backend
        DataQuality["data_quality.py"]:::backend
    end

    %% Persistence Layer
    subgraph "Persistence"
        direction TB
        DuckDBLocal["DuckDB (.duckdb files)"]:::db
        UsersDB["Authentication & Chat History DB"]:::db
        Databricks["Databricks SQL Warehouse (optional)"]:::db
    end

    %% External Services
    GoogleGemini["Google Gemini API"]:::external

    %% Static Assets and Config
    StaticAssets["Static Assets"]:::asset
    Config["Streamlit Config"]:::asset

    %% Connections
    LoginPage -->|auth flow| Router
    Home -->|select mode| VoiceRecorder
    Home -->|select mode| TextInput
    VoiceRecorder -->|raw text| Router
    TextInput -->|raw text| Router
    UIHelpers -.-> LoginPage
    UIHelpers -.-> Home

    Router -->|route to| DataEngineerAgent
    Router -->|route to| VizAgent
    Prompts -->|provide templates| DataEngineerAgent
    Prompts -->|provide templates| VizAgent

    DataEngineerAgent -->|generate SQL| GoogleGemini
    VizAgent -->|generate chart config| GoogleGemini

    GoogleGemini -->|SQL query| DataEngineerAgent
    GoogleGemini -->|chart instructions| VizAgent

    DataEngineerAgent -->|execute query| Utils
    Utils -->|results| DataEngineerAgent
    Utils -->|execute query| DuckDBLocal
    Utils -->|execute query| Databricks
    Utils -->|log session| UsersDB

    DataProfiler -->|profiling report| Home
    DataQuality -->|quality report| Home

    Home -->|invoke profiling| DataProfiler
    Home -->|invoke quality checks| DataQuality

    DataEngineerAgent -->|pass data| VizAgent
    VizAgent -->|render chart| Home

    %% Click Events
    click LoginPage "https://github.com/aswinpookkatt/genieverse/blob/master/login.py"
    click Home "https://github.com/aswinpookkatt/genieverse/blob/master/home.py"
    click VoiceRecorder "https://github.com/aswinpookkatt/genieverse/blob/master/app.py"
    click TextInput "https://github.com/aswinpookkatt/genieverse/blob/master/app_01.py"
    click TextInput "https://github.com/aswinpookkatt/genieverse/blob/master/test.py"
    click UIHelpers "https://github.com/aswinpookkatt/genieverse/blob/master/ui.py"
    click Router "https://github.com/aswinpookkatt/genieverse/blob/master/router.py"
    click DataEngineerAgent "https://github.com/aswinpookkatt/genieverse/blob/master/agents.py"
    click VizAgent "https://github.com/aswinpookkatt/genieverse/blob/master/agents.py"
    click Prompts "https://github.com/aswinpookkatt/genieverse/blob/master/prompts.py"
    click Utils "https://github.com/aswinpookkatt/genieverse/blob/master/utils.py"
    click DataProfiler "https://github.com/aswinpookkatt/genieverse/blob/master/data_scanner/data_profiler.py"
    click DataQuality "https://github.com/aswinpookkatt/genieverse/blob/master/data_scanner/data_quality.py"
    click StaticAssets "https://github.com/aswinpookkatt/genieverse/tree/master/static/"
    click Config "https://github.com/aswinpookkatt/genieverse/blob/master/.streamlit/config.toml"
    click Config "https://github.com/aswinpookkatt/genieverse/blob/master/.streamlit/secrets.toml"
    click DuckDBLocal "https://github.com/aswinpookkatt/genieverse/blob/master/data/amazon.duckdb"
    click UsersDB "https://github.com/aswinpookkatt/genieverse/blob/master/data/users_db.duckdb"
    click DuckDBLocal "https://github.com/aswinpookkatt/genieverse/blob/master/data/trans_dim.csv"
    click DuckDBLocal "https://github.com/aswinpookkatt/genieverse/blob/master/data/amazon.csv"
    click DuckDBLocal "https://github.com/aswinpookkatt/genieverse/blob/master/data/fact_table.csv"
    click DuckDBLocal "https://github.com/aswinpookkatt/genieverse/blob/master/data/database_setup_amazon.py"
    click DuckDBLocal "https://github.com/aswinpookkatt/genieverse/blob/master/data/database_setup_multitable.py"
    click DuckDBLocal "https://github.com/aswinpookkatt/genieverse/blob/master/data/users_setup.py"
    click Databricks "https://github.com/aswinpookkatt/genieverse/blob/master/requirements.txt"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#0288D1,stroke-width:2px;
    classDef backend fill:#BBDEFB,stroke:#1976D2,stroke-width:2px;
    classDef db fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef external fill:#F0F4C3,stroke:#F9A825,stroke-width:2px;
    classDef asset fill:#FFECB3,stroke:#F57F17,stroke-width:2px;
```
