# oam11/querystream architecture

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

- Interactive diagram: https://gitdiagram.com/oam11/querystream
- Repository: https://github.com/oam11/querystream

## Overview

##### Project Type and Purpose
- This is a Python-based database query generation tool (an open-source “utility” or small web app), built primarily with Streamlit (inferred from `st.session_state` references) and designed to:
- Extract database schemas from SQLite (and potentially PostgreSQL/MySQL) files
- Generate SQL queries and insights via an LLM (the Groq Mixtral model)
- Present results in a simple UI (see `index.html` or Streamlit front end)
- Key goal: simplify schema analysis, automate SQL generation, and handle exceptions robustly.

##### File Structure Analysis
- Top level:
- `Querystream.py` – main entry point / Streamlit app
- `requirements.txt` – Python dependencies (e.g., streamlit, pandas, groq client, sqlite3)
- `index.html` – static landing or embedded UI template
- `sample_databases/` – contains example SQLite DBs for testing
- (Implicit) Modules referenced in README:
- `db_query_generator.py` – schema extraction and SQL-generation logic
- `llm_models.py` – wraps the ChatGroq (Groq Mixtral) LLM client

##### README Insights
- Core functions:
- `get_database_schema(db_file_path)` – reads table/column metadata via `PRAGMA`
- `initialize_groq_mixtral(api_key)` – sets up the LLM model
- Dependencies:
- Python standard libs: `os`, `sqlite3`
- Third-party: `pandas`, `streamlit`, Groq Python SDK

a. Main Components
1. UI Layer (Streamlit app / `index.html` front end)
2. Business Logic Layer
- Schema Extractor (`db_query_generator.py`)
- Query Generator (LLM integration via `llm_models.py`)
3. Data Layer
- Local SQLite databases (`sample_databases/*.db`)
- Potential extensions: PostgreSQL/MySQL
4. External Service
- Groq Mixtral LLM API
b. Relationships & Data Flows
- UI → (uploads DB file) → Schema Extractor
- Schema Extractor → (returns schema dict) → UI & Query Generator
- UI → (user prompts) → Query Generator → (calls Groq API) →
receives generated SQL → displays in UI
- UI or Logic → (executes SQL) → DB → returns query results → UI
c. Architectural Patterns & Principles
- Layered architecture: clear separation of UI, logic, data
- Single-responsibility modules: one module per core concern
- Extensibility: support for multiple DB backends & LLM providers
d. Key Technologies
- Python + Streamlit (UI)
- SQLite (local storage) + adapters for PostgreSQL/MySQL
- Pandas (data framing & analysis)
- Groq Mixtral (LLM for SQL generation)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        UI1["Streamlit UI\n(Querystream.py)"]:::ui
        UI2["Static Template\n(index.html)"]:::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        Schema["SchemaExtractor\n(db_query_generator.py)"]:::logic
        QueryGen["QueryGenerator\n(llm_models.py)"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        DataFolder["sample_databases/"]:::data
        Chinook["chinook.db"]:::data
        Ecommerce["ecommerce.db"]:::data
        Employees["employees.db"]:::data
        Library["library.db"]:::data
    end

    %% External Service
    subgraph "External Service"
        Groq["Groq Mixtral API"]:::external
    end

    %% Connections
    UI1 -->|"upload DB file"| Schema
    Schema -->|"schema dict"| UI1
    Schema -->|"schema dict"| QueryGen
    UI1 -->|"user prompts"| QueryGen
    QueryGen -->|"LLM request"| Groq
    Groq -->|"generated SQL"| QueryGen
    QueryGen -->|"SQL string"| UI1
    UI1 -->|"execute SQL"| DataFolder
    DataFolder -->|"query results"| UI1

    %% Sample DB files inside folder
    DataFolder --> Chinook
    DataFolder --> Ecommerce
    DataFolder --> Employees
    DataFolder --> Library

    %% Click Events
    click UI1 "https://github.com/oam11/querystream/blob/main/Querystream.py"
    click UI2 "https://github.com/oam11/querystream/blob/main/index.html"
    click DataFolder "https://github.com/oam11/querystream/tree/main/sample_databases/"
    click Chinook "https://github.com/oam11/querystream/blob/main/sample_databases/chinook.db"
    click Ecommerce "https://github.com/oam11/querystream/blob/main/sample_databases/ecommerce.db"
    click Employees "https://github.com/oam11/querystream/blob/main/sample_databases/employees.db"
    click Library "https://github.com/oam11/querystream/blob/main/sample_databases/library.db"
    click requirements_txt "https://github.com/oam11/querystream/blob/main/requirements.txt"
    click LICENSE "https://github.com/oam11/querystream/tree/main/LICENSE"
    click README_md "https://github.com/oam11/querystream/blob/main/README.md"

    %% Dependencies node for click events
    requirements_txt["requirements.txt"]:::data
    LICENSE["LICENSE"]:::data
    README_md["README.md"]:::data

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000
    classDef logic fill:#90EE90,stroke:#000
    classDef data fill:#FFA500,stroke:#000
    classDef external fill:#DDA0DD,stroke:#000
```
