# mirudhula-dhanaraj/llm-data-agent architecture

> Architecture diagram of the GitHub repository mirudhula-dhanaraj/llm-data-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mirudhula-dhanaraj/llm-data-agent
- Repository: https://github.com/mirudhula-dhanaraj/llm-data-agent

## Overview

This is a natural-language-to-SQL agent with Streamlit and FastAPI entry points. A question invokes a LangGraph workflow that generates SQL with Groq, validates it, executes it against SQLite, and retries failures. The Streamlit interface displays SQL, retry information, and results; the API returns the workflow state. The README also describes a health endpoint. The tree and excerpts show app.py as the Streamlit implementation, rather than the README’s mentioned streamlit_app.py. The graph reflects only relationships visible in the excerpts or README.

Main entry points: [`app/graph.py`](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/graph.py) (LangGraph Workflow), [`app.py`](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app.py) (Streamlit UI), [`app/main.py`](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/main.py) (FastAPI API), [`app/database.py`](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/database.py) (Schema and Seeding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
  node_api["FastAPI API<br/>[main.py]"]
  node_results["Query Results"]
  node_health["Health Check<br/>[main.py]"]
end

subgraph group_agent["SQL Agent"]
  node_workflow["LangGraph Workflow<br/>[graph.py]"]
  node_generation["SQL Generation<br/>[graph.py]"]
  node_groq["Groq LLM"]
  node_execution["SQL Execution<br/>[graph.py]"]
  node_state["Agent State<br/>[state.py]"]
end

subgraph group_data["Safety and Data"]
  node_validation["SQL Validation<br/>[guardrails.py]"]
  node_database["Schema and Seeding<br/>[database.py]"]
  node_sqlite[("SQLite Database<br/>[enterprise.db]")]
end

node_user(("Questioner"))
node_api_client(("API Client"))

node_user -->|"asks"| node_streamlit
node_streamlit -->|"initializes"| node_database
node_streamlit -->|"invokes"| node_workflow
node_api_client -->|"submits query"| node_api
node_api -->|"initializes"| node_database
node_api -->|"invokes"| node_workflow
node_workflow -->|"starts at"| node_generation
node_generation -->|"reads schema"| node_database
node_generation -->|"requests SQL"| node_groq
node_generation -->|"routes to"| node_validation
node_validation -->|"valid SQL routes"| node_execution
node_validation -->|"invalid SQL retries"| node_generation
node_execution -->|"runs query"| node_sqlite
node_execution -->|"errors retry"| node_generation
node_database -->|"seeds and reads schema"| node_sqlite
node_workflow -->|"uses shared schema"| node_state
node_workflow -->|"returns state"| node_results
node_workflow -->|"returns state"| node_api
node_streamlit -->|"renders results"| node_results
node_api_client -->|"checks health"| node_health

click node_streamlit "https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app.py"
click node_api "https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/main.py"
click node_workflow "https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/graph.py"
click node_generation "https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/graph.py"
click node_validation "https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/guardrails.py"
click node_execution "https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/graph.py"
click node_state "https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/state.py"
click node_database "https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/database.py"
click node_sqlite "https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/data/enterprise.db"
click node_health "https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/main.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_streamlit,node_api,node_results,node_health,node_api_client toneBlue
class node_workflow,node_generation,node_groq,node_execution,node_state toneAmber
class node_validation,node_database,node_sqlite toneMint
class node_user toneIndigo
```

## Components

### User Interfaces

- [Streamlit UI](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app.py): `app.py`
- [FastAPI API](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/main.py): `app/main.py`
- **Query Results**
- [Health Check](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/main.py): `app/main.py`

### SQL Agent

- [LangGraph Workflow](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/graph.py): `app/graph.py`
- [SQL Generation](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/graph.py): `app/graph.py`
- **Groq LLM**
- [SQL Execution](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/graph.py): `app/graph.py`
- [Agent State](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/state.py): `app/state.py`

### Safety and Data

- [SQL Validation](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/guardrails.py): `app/guardrails.py`
- [Schema and Seeding](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/app/database.py): `app/database.py`
- [SQLite Database](https://github.com/mirudhula-dhanaraj/llm-data-agent/blob/main/data/enterprise.db): `data/enterprise.db`

### Other components

- **Questioner**
- **API Client**

## Connections

- Questioner → Streamlit UI: asks (evidence: `app.py`)
- Streamlit UI → Schema and Seeding: initializes (evidence: `app.py`)
- Streamlit UI → LangGraph Workflow: invokes (evidence: `app.py`)
- API Client → FastAPI API: submits query (evidence: `app/main.py`)
- FastAPI API → Schema and Seeding: initializes (evidence: `app/main.py`)
- FastAPI API → LangGraph Workflow: invokes (evidence: `app/main.py`)
- LangGraph Workflow → SQL Generation: starts at (evidence: `app/graph.py`)
- SQL Generation → Schema and Seeding: reads schema (evidence: `app/graph.py`)
- SQL Generation → Groq LLM: requests SQL (evidence: `app/graph.py`)
- SQL Generation → SQL Validation: routes to (evidence: `app/graph.py`)
- SQL Validation → SQL Execution: valid SQL routes (evidence: `app/graph.py`)
- SQL Validation → SQL Generation: invalid SQL retries (evidence: `app/graph.py`)
- SQL Execution → SQLite Database: runs query (evidence: `app/graph.py`)
- SQL Execution → SQL Generation: errors retry (evidence: `app/graph.py`)
- Schema and Seeding → SQLite Database: seeds and reads schema (evidence: `app/database.py`)
- LangGraph Workflow → Agent State: uses shared schema (evidence: `app/graph.py`)
- LangGraph Workflow → Query Results: returns state
- LangGraph Workflow → FastAPI API: returns state (evidence: `app/main.py`)
- Streamlit UI → Query Results: renders results (evidence: `app.py`)
- API Client → Health Check: checks health (evidence: `README.md`)
