# visheshjain28/insightsql architecture

> Architecture diagram of the GitHub repository visheshjain28/insightsql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/visheshjain28/insightsql
- Repository: https://github.com/visheshjain28/insightsql

## Overview

InsightSQL is a Streamlit natural-language analytics application: a user submits a question, the app generates SQL from database schema context, executes it, and presents tabular, visual, and AI-summary results. The UI also exposes schema exploration and an evaluation-report tab. The sampled engine code supports the generation, execution, and summary links shown; the README describes RAGAS evaluation, but the sampled evaluation UI displays fixed metrics and example rows, so no live evaluation pipeline is inferred.

Main entry points: [`app.py`](https://github.com/visheshjain28/insightsql/blob/main/app.py) (Analytics UI), [`sql_engine.py`](https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py) (SQL Execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Streamlit Interface"]
  node_app["Analytics UI<br/>[app.py]"]
  node_schema_explorer["Schema Explorer<br/>[app.py]"]
  node_eval_report["Evaluation Report<br/>[app.py]"]
end

subgraph group_query["Query Engine"]
  node_db_connection["DB Connection<br/>[sql_engine.py]"]
  node_sql_chain["SQL Chain<br/>[sql_engine.py]"]
  node_schema_context["Schema Context<br/>[sql_engine.py]"]
  node_sql_execution["SQL Execution<br/>[sql_engine.py]"]
end

subgraph group_results["Analytics Results"]
  node_dataframe["Query Results<br/>[sql_engine.py]"]
  node_table_view["Data Table<br/>[app.py]"]
  node_chart_view["Interactive Charts<br/>[app.py]"]
  node_summary["Business Summary<br/>[sql_engine.py]"]
end

subgraph group_external["External Systems"]
  node_mysql[("MySQL Database")]
  node_gemini{{"Gemini"}}
end

node_user(("User"))

node_user -->|"asks question"| node_app
node_app -->|"initializes connection"| node_db_connection
node_app -->|"creates chain"| node_sql_chain
node_app -->|"submits question"| node_sql_execution
node_db_connection -->|"connects"| node_mysql
node_sql_chain -->|"retrieves schema"| node_schema_context
node_schema_context -->|"reads metadata"| node_mysql
node_sql_chain -->|"requests SQL"| node_gemini
node_sql_execution -->|"invokes"| node_sql_chain
node_sql_execution -->|"executes SQL"| node_mysql
node_sql_execution -->|"returns results"| node_dataframe
node_app -->|"renders tables"| node_schema_explorer
node_schema_explorer -->|"inspects schema"| node_mysql
node_app -->|"requests summary"| node_summary
node_summary -->|"summarizes results"| node_gemini
node_dataframe -->|"renders rows"| node_table_view
node_dataframe -->|"plots data"| node_chart_view
node_app -->|"shows report"| node_eval_report

click node_app "https://github.com/visheshjain28/insightsql/blob/main/app.py"
click node_schema_explorer "https://github.com/visheshjain28/insightsql/blob/main/app.py"
click node_eval_report "https://github.com/visheshjain28/insightsql/blob/main/app.py"
click node_db_connection "https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py"
click node_sql_chain "https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py"
click node_schema_context "https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py"
click node_sql_execution "https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py"
click node_dataframe "https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py"
click node_table_view "https://github.com/visheshjain28/insightsql/blob/main/app.py"
click node_chart_view "https://github.com/visheshjain28/insightsql/blob/main/app.py"
click node_summary "https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_schema_explorer,node_eval_report,node_user toneBlue
class node_db_connection,node_sql_chain,node_schema_context,node_sql_execution toneAmber
class node_dataframe,node_table_view,node_chart_view,node_summary toneMint
class node_mysql,node_gemini toneRose
```

## Components

### Streamlit Interface

- [Analytics UI](https://github.com/visheshjain28/insightsql/blob/main/app.py): `app.py`
- [Schema Explorer](https://github.com/visheshjain28/insightsql/blob/main/app.py): `app.py`
- [Evaluation Report](https://github.com/visheshjain28/insightsql/blob/main/app.py): `app.py`

### Query Engine

- [DB Connection](https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py): `sql_engine.py`
- [SQL Chain](https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py): `sql_engine.py`
- [Schema Context](https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py): `sql_engine.py`
- [SQL Execution](https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py): `sql_engine.py`

### Analytics Results

- [Query Results](https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py): `sql_engine.py`
- [Data Table](https://github.com/visheshjain28/insightsql/blob/main/app.py): `app.py`
- [Interactive Charts](https://github.com/visheshjain28/insightsql/blob/main/app.py): `app.py`
- [Business Summary](https://github.com/visheshjain28/insightsql/blob/main/sql_engine.py): `sql_engine.py`

### External Systems

- **MySQL Database**
- **Gemini**

### Other components

- **User**

## Connections

- User → Analytics UI: asks question
- Analytics UI → DB Connection: initializes connection
- Analytics UI → SQL Chain: creates chain
- Analytics UI → SQL Execution: submits question
- DB Connection → MySQL Database: connects
- SQL Chain → Schema Context: retrieves schema
- Schema Context → MySQL Database: reads metadata
- SQL Chain → Gemini: requests SQL
- SQL Execution → SQL Chain: invokes
- SQL Execution → MySQL Database: executes SQL
- SQL Execution → Query Results: returns results
- Analytics UI → Schema Explorer: renders tables
- Schema Explorer → MySQL Database: inspects schema
- Analytics UI → Business Summary: requests summary
- Business Summary → Gemini: summarizes results
- Query Results → Data Table: renders rows
- Query Results → Interactive Charts: plots data
- Analytics UI → Evaluation Report: shows report