# dhanyahegdek/ai-data-analyst architecture

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

- Interactive diagram: https://gitdiagram.com/dhanyahegdek/ai-data-analyst
- Repository: https://github.com/dhanyahegdek/ai-data-analyst

## Overview

AI Data Analyst turns a business question into a validated PostgreSQL query, analyzed results, and a visualization for the React UI. The main path runs through the FastAPI analyze endpoint and LangGraph’s documented question-understanding, schema, SQL, execution, analysis, visualization, and response stages. Query history is a separate persistence branch, restored through the history endpoint. Workflow stages and feature links follow the README; source excerpts are partial, so uncertain internal calls are omitted.

Main entry points: [`src/ai_data_analyst/main.py`](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/main.py) (FastAPI application), [`src/ai_data_analyst/agents/routing.py`](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/routing.py) (Validation routing), [`frontend/src/App.jsx`](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/frontend/src/App.jsx) (Question and results UI), [`src/ai_data_analyst/agents/graph.py`](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/graph.py) (LangGraph workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web interface"]
  node_app["Question and results UI<br/>[App.jsx]"]
end

subgraph group_api["API entry points"]
  node_api_app["FastAPI application<br/>[main.py]"]
end

subgraph group_workflow["Analysis workflow"]
  node_graph["LangGraph workflow<br/>[graph.py]"]
  node_understand["Understand question"]
  node_schema["Retrieve schema"]
  node_schema_context["Business schema context<br/>[schema_context.py]"]
  node_generate["Generate SQL<br/>[sql_generator.py]"]
  node_validate["Validate SQL<br/>[sql_validation.py]"]
  node_fix["Correct SQL<br/>[sql_fix.py]"]
  node_route["Validation routing<br/>[routing.py]"]
  node_execute["Execute query<br/>[sql_execution.py]"]
  node_analyze["Analyze results<br/>[result_analysis.py]"]
  node_visualize["Choose visualization<br/>[visualization.py]"]
  node_final["Final response<br/>[final_response.py]"]
end

subgraph group_data["Data and persistence"]
  node_sql_service["SQL execution service<br/>[sql_executor.py]"]
  node_sql_validator["SQL safety checks<br/>[sql_validator.py]"]
  node_business_db[("Business PostgreSQL")]
  node_history_service["Query history service<br/>[query_history.py]"]
  node_history_model["Query history records<br/>[query.py]"]
  node_history_db[("History PostgreSQL<br/>[connection.py]")]
end

node_user(("Business user"))
node_gemini{{"Gemini language model"}}

node_user -->|"asks question"| node_app
node_app -->|"HTTP request"| node_api_app
node_api_app -->|"invokes"| node_graph
node_graph -->|"dispatches"| node_understand
node_understand -->|"continues"| node_schema
node_schema -->|"returns schema"| node_schema_context
node_schema -->|"continues"| node_generate
node_generate -->|"continues"| node_validate
node_validate -->|"routes result"| node_route
node_route -->|"valid query"| node_execute
node_route -->|"invalid; retry"| node_fix
node_fix -->|"revalidates"| node_validate
node_route -->|"retry limit"| node_final
node_execute -->|"returns rows"| node_analyze
node_analyze -->|"continues"| node_visualize
node_visualize -->|"continues"| node_final
node_understand -->|"uses model"| node_gemini
node_generate -->|"uses model"| node_gemini
node_fix -->|"uses model"| node_gemini
node_analyze -->|"uses model"| node_gemini
node_final -->|"uses model"| node_gemini
node_execute -->|"executes SQL"| node_sql_service
node_sql_service -->|"checks SQL"| node_sql_validator
node_sql_service -->|"reads rows"| node_business_db
node_graph -->|"returns result"| node_api_app
node_api_app -->|"saves success; reads history"| node_history_service
node_history_service -->|"maps records"| node_history_model
node_history_service -->|"reads and writes"| node_history_db
node_api_app -->|"returns analysis or history"| node_app
node_app -->|"renders results"| node_user

click node_app "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/frontend/src/App.jsx"
click node_api_app "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/main.py"
click node_graph "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/graph.py"
click node_understand "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/question_understanding.py"
click node_schema "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/schema_retrieval.py"
click node_schema_context "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/schema_context.py"
click node_generate "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/sql_generator.py"
click node_validate "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/sql_validation.py"
click node_fix "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/sql_fix.py"
click node_route "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/routing.py"
click node_execute "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/sql_execution.py"
click node_analyze "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/result_analysis.py"
click node_visualize "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/visualization.py"
click node_final "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/final_response.py"
click node_sql_service "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/services/sql_executor.py"
click node_sql_validator "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/tools/sql_validator.py"
click node_business_db "https://github.com/dhanyahegdek/ai-data-analyst/tree/main/src/ai_data_analyst/models"
click node_history_service "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/services/query_history.py"
click node_history_model "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/models/query.py"
click node_history_db "https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/database/connection.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_user toneBlue
class node_api_app toneAmber
class node_graph,node_understand,node_schema,node_schema_context,node_generate,node_validate,node_fix,node_route,node_execute,node_analyze,node_visualize,node_final toneMint
class node_sql_service,node_sql_validator,node_business_db,node_history_service,node_history_model,node_history_db toneRose
class node_gemini toneIndigo
```

## Components

### Web interface

- [Question and results UI](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### API entry points

- [FastAPI application](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/main.py): `src/ai_data_analyst/main.py`

### Analysis workflow

- [LangGraph workflow](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/graph.py): `src/ai_data_analyst/agents/graph.py`
- [Understand question](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/question_understanding.py): `src/ai_data_analyst/agents/question_understanding.py`
- [Retrieve schema](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/schema_retrieval.py): `src/ai_data_analyst/agents/schema_retrieval.py`
- [Business schema context](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/schema_context.py): `src/ai_data_analyst/agents/schema_context.py`
- [Generate SQL](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/sql_generator.py): `src/ai_data_analyst/agents/sql_generator.py`
- [Validate SQL](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/sql_validation.py): `src/ai_data_analyst/agents/sql_validation.py`
- [Correct SQL](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/sql_fix.py): `src/ai_data_analyst/agents/sql_fix.py`
- [Validation routing](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/routing.py): `src/ai_data_analyst/agents/routing.py`
- [Execute query](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/sql_execution.py): `src/ai_data_analyst/agents/sql_execution.py`
- [Analyze results](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/result_analysis.py): `src/ai_data_analyst/agents/result_analysis.py`
- [Choose visualization](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/visualization.py): `src/ai_data_analyst/agents/visualization.py`
- [Final response](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/agents/final_response.py): `src/ai_data_analyst/agents/final_response.py`

### Data and persistence

- [SQL execution service](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/services/sql_executor.py): `src/ai_data_analyst/services/sql_executor.py`
- [SQL safety checks](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/tools/sql_validator.py): `src/ai_data_analyst/tools/sql_validator.py`
- [Business PostgreSQL](https://github.com/dhanyahegdek/ai-data-analyst/tree/main/src/ai_data_analyst/models): `src/ai_data_analyst/models`
- [Query history service](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/services/query_history.py): `src/ai_data_analyst/services/query_history.py`
- [Query history records](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/models/query.py): `src/ai_data_analyst/models/query.py`
- [History PostgreSQL](https://github.com/dhanyahegdek/ai-data-analyst/blob/main/src/ai_data_analyst/database/connection.py): `src/ai_data_analyst/database/connection.py`

### Other components

- **Business user**
- **Gemini language model**

## Connections

- Business user → Question and results UI: asks question
- Question and results UI → FastAPI application: HTTP request
- FastAPI application → LangGraph workflow: invokes
- LangGraph workflow → Understand question: dispatches
- Understand question → Retrieve schema: continues
- Retrieve schema → Business schema context: returns schema
- Retrieve schema → Generate SQL: continues
- Generate SQL → Validate SQL: continues
- Validate SQL → Validation routing: routes result
- Validation routing → Execute query: valid query
- Validation routing → Correct SQL: invalid; retry
- Correct SQL → Validate SQL: revalidates
- Validation routing → Final response: retry limit
- Execute query → Analyze results: returns rows
- Analyze results → Choose visualization: continues
- Choose visualization → Final response: continues
- Understand question → Gemini language model: uses model
- Generate SQL → Gemini language model: uses model
- Correct SQL → Gemini language model: uses model
- Analyze results → Gemini language model: uses model
- Final response → Gemini language model: uses model
- Execute query → SQL execution service: executes SQL
- SQL execution service → SQL safety checks: checks SQL
- SQL execution service → Business PostgreSQL: reads rows
- LangGraph workflow → FastAPI application: returns result
- FastAPI application → Query history service: saves success; reads history
- Query history service → Query history records: maps records
- Query history service → History PostgreSQL: reads and writes
- FastAPI application → Question and results UI: returns analysis or history
- Question and results UI → Business user: renders results