# vaibhavburad15/query-genie architecture

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

- Interactive diagram: https://gitdiagram.com/vaibhavburad15/query-genie
- Repository: https://github.com/vaibhavburad15/query-genie

## Overview

Query Genie is a natural-language database assistant. Users sign in, connect a database or uploaded file, browse metadata, ask questions, and receive read-only SQL results for tables or charts; they can also save favorites, manage chat history, and build custom dashboards. The React frontend communicates with a FastAPI backend, which handles authentication, source sessions, query generation and execution, and persisted user features. The README documents the major backend capabilities and provider options; backend excerpts are partial, so internal call relationships beyond those documented are not inferred.

Main entry points: [`backend/backend.py`](https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py) (HTTP API and orchestration), [`Query-frontend/src/App.tsx`](https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/App.tsx) (Route and state shell), [`Query-frontend/src/pages/DashboardPage.tsx`](https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/pages/DashboardPage.tsx) (Chat dashboard), [`Query-frontend/src/services/api.ts`](https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/services/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_authui["Sign in / signup<br/>[AuthPage.tsx]"]
  node_app["Route and state shell<br/>[App.tsx]"]
  node_connectui["Source connection UI"]
  node_chatui["Chat dashboard<br/>[DashboardPage.tsx]"]
  node_chatview["Chat and results UI<br/>[ChatWindow.tsx]"]
  node_resultview["Tables and charts"]
  node_customdash["Custom dashboards"]
  node_api["API client<br/>[api.ts]"]
end

subgraph group_backend["FastAPI services"]
  node_backend["HTTP API and orchestration<br/>[backend.py]"]
  node_auth["Authentication and OTP<br/>[backend.py]"]
  node_sources["Source sessions and metadata<br/>[backend.py]"]
end

subgraph group_query["Query execution"]
  node_prompt["SQL prompt rules"]
  node_generation["LLM SQL generation<br/>[backend.py]"]
  node_execution["Read-only SQL execution<br/>[backend.py]"]
end

subgraph group_persistence["Persistence"]
  node_features[("Favorites, history, settings<br/>[extended_models.py]")]
  node_dashboards[("Saved dashboards<br/>[backend.py]")]
end

node_user(("User"))
node_source[("User data sources")]
node_providers["Ollama / Groq"]
node_internaldb[("Internal database")]
node_email["Email delivery"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_chatui
node_app -->|"routes to"| node_customdash
node_authui -->|"authenticates via"| node_api
node_chatui -->|"opens connection"| node_connectui
node_chatui -->|"renders"| node_chatview
node_chatui -->|"confirms SQL via"| node_api
node_chatview -.->|"presents results"| node_resultview
node_customdash -->|"loads and saves via"| node_api
node_api -->|"calls REST API"| node_backend
node_backend -->|"handles authentication"| node_auth
node_backend -->|"manages connections"| node_sources
node_backend -->|"orchestrates chat"| node_generation
node_backend -->|"executes validated SQL"| node_execution
node_backend -->|"persists user features"| node_features
node_backend -->|"persists dashboards"| node_dashboards
node_backend -->|"stores application data"| node_internaldb
node_auth -->|"sends signup OTP"| node_email
node_sources -->|"connects to"| node_source
node_generation -->|"uses rules"| node_prompt
node_generation -->|"requests SQL"| node_providers
node_execution -->|"queries"| node_source

click node_authui "https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/pages/AuthPage.tsx"
click node_app "https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/App.tsx"
click node_connectui "https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/components/dashboard/DatabaseConnectionModal.tsx"
click node_chatui "https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/pages/DashboardPage.tsx"
click node_chatview "https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/components/dashboard/ChatWindow.tsx"
click node_resultview "https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/components/dashboard/EnhancedDataTableV2.tsx"
click node_customdash "https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/pages/Customdashboard.tsx"
click node_api "https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/services/api.ts"
click node_backend "https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py"
click node_auth "https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py"
click node_sources "https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py"
click node_prompt "https://github.com/vaibhavburad15/query-genie/blob/main/backend/sql_system_prompt.py"
click node_generation "https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py"
click node_execution "https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py"
click node_features "https://github.com/vaibhavburad15/query-genie/blob/main/backend/extended_models.py"
click node_dashboards "https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.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_authui,node_app,node_connectui,node_chatui,node_chatview,node_resultview,node_customdash,node_api,node_user toneBlue
class node_backend,node_auth,node_sources,node_source,node_internaldb toneAmber
class node_prompt,node_generation,node_execution toneMint
class node_features,node_dashboards toneRose
class node_providers,node_email toneIndigo
```

## Components

### React frontend

- [Sign in / signup](https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/pages/AuthPage.tsx): `Query-frontend/src/pages/AuthPage.tsx`
- [Route and state shell](https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/App.tsx): `Query-frontend/src/App.tsx`
- [Source connection UI](https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/components/dashboard/DatabaseConnectionModal.tsx): `Query-frontend/src/components/dashboard/DatabaseConnectionModal.tsx`
- [Chat dashboard](https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/pages/DashboardPage.tsx): `Query-frontend/src/pages/DashboardPage.tsx`
- [Chat and results UI](https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/components/dashboard/ChatWindow.tsx): `Query-frontend/src/components/dashboard/ChatWindow.tsx`
- [Tables and charts](https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/components/dashboard/EnhancedDataTableV2.tsx): `Query-frontend/src/components/dashboard/EnhancedDataTableV2.tsx`
- [Custom dashboards](https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/pages/Customdashboard.tsx): `Query-frontend/src/pages/Customdashboard.tsx`
- [API client](https://github.com/vaibhavburad15/query-genie/blob/main/Query-frontend/src/services/api.ts): `Query-frontend/src/services/api.ts`

### FastAPI services

- [HTTP API and orchestration](https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py): `backend/backend.py`
- [Authentication and OTP](https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py): `backend/backend.py`
- [Source sessions and metadata](https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py): `backend/backend.py`

### Query execution

- [SQL prompt rules](https://github.com/vaibhavburad15/query-genie/blob/main/backend/sql_system_prompt.py): `backend/sql_system_prompt.py`
- [LLM SQL generation](https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py): `backend/backend.py`
- [Read-only SQL execution](https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py): `backend/backend.py`

### Persistence

- [Favorites, history, settings](https://github.com/vaibhavburad15/query-genie/blob/main/backend/extended_models.py): `backend/extended_models.py`
- [Saved dashboards](https://github.com/vaibhavburad15/query-genie/blob/main/backend/backend.py): `backend/backend.py`

### Other components

- **User**
- **User data sources**
- **Ollama / Groq**
- **Internal database**
- **Email delivery**

## Connections

- User → Route and state shell: uses (evidence: `README.md`)
- Route and state shell → Sign in / signup: routes to (evidence: `Query-frontend/src/App.tsx`)
- Route and state shell → Chat dashboard: routes to (evidence: `Query-frontend/src/App.tsx`)
- Route and state shell → Custom dashboards: routes to (evidence: `Query-frontend/src/App.tsx`)
- Sign in / signup → API client: authenticates via (evidence: `README.md`)
- Chat dashboard → Source connection UI: opens connection (evidence: `Query-frontend/src/pages/DashboardPage.tsx`)
- Chat dashboard → Chat and results UI: renders (evidence: `Query-frontend/src/pages/DashboardPage.tsx`)
- Chat dashboard → API client: confirms SQL via (evidence: `Query-frontend/src/pages/DashboardPage.tsx`)
- Chat and results UI → Tables and charts: presents results
- Custom dashboards → API client: loads and saves via (evidence: `README.md`)
- API client → HTTP API and orchestration: calls REST API (evidence: `README.md`)
- HTTP API and orchestration → Authentication and OTP: handles authentication (evidence: `README.md`)
- HTTP API and orchestration → Source sessions and metadata: manages connections (evidence: `README.md`)
- HTTP API and orchestration → LLM SQL generation: orchestrates chat (evidence: `README.md`)
- HTTP API and orchestration → Read-only SQL execution: executes validated SQL (evidence: `README.md`)
- HTTP API and orchestration → Favorites, history, settings: persists user features (evidence: `README.md`)
- HTTP API and orchestration → Saved dashboards: persists dashboards (evidence: `README.md`)
- HTTP API and orchestration → Internal database: stores application data (evidence: `README.md`)
- Authentication and OTP → Email delivery: sends signup OTP (evidence: `README.md`)
- Source sessions and metadata → User data sources: connects to (evidence: `README.md`)
- LLM SQL generation → SQL prompt rules: uses rules (evidence: `backend/backend.py`)
- LLM SQL generation → Ollama / Groq: requests SQL (evidence: `README.md`)
- Read-only SQL execution → User data sources: queries (evidence: `README.md`)
