# mahnoorahmed-dev/nl2sql-crewai architecture

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

- Interactive diagram: https://gitdiagram.com/mahnoorahmed-dev/nl2sql-crewai
- Repository: https://github.com/mahnoorahmed-dev/nl2sql-crewai

## Overview

This is a natural-language-to-SQL application with a Streamlit interface, CrewAI orchestration, and a custom SQL Server tool. Its main workflow accepts a question, retrieves schema context, asks GPT-4 for SQL, executes the query, formats the result, and returns it to the user. The tool’s source shows the schema, prompting, LLM, execution, and formatting stages; the README documents the agent workflow. The CSV’s role is not established by the sampled source, so it is omitted.

Main entry points: [`text_to_sql_tool.py`](https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py) (SQL tool), [`app.py`](https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/app.py) (Streamlit UI), [`run_crew.py`](https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/run_crew.py) (Crew runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
end

subgraph group_orchestration["Crew orchestration"]
  node_runner["Crew runner<br/>[run_crew.py]"]
  node_crew_runtime["CrewAI runtime"]
end

subgraph group_translation["SQL translation"]
  node_tool["SQL tool"]
  node_schema["Schema retrieval"]
  node_prompt["Prompt building"]
  node_llm_call["SQL generation"]
  node_execution["Query execution"]
  node_formatting["Result formatting"]
end

subgraph group_data["External systems"]
  node_sqlserver[("SQL Server")]
  node_openai["OpenAI GPT-4"]
end

node_user(("User"))

node_user -->|"enters question"| node_streamlit
node_streamlit -->|"calls query"| node_runner
node_runner -->|"starts crew"| node_crew_runtime
node_crew_runtime -->|"dispatches tool"| node_tool
node_tool -->|"retrieves schema"| node_schema
node_schema -->|"reads metadata"| node_sqlserver
node_tool -->|"builds prompt"| node_prompt
node_prompt -->|"provides context"| node_llm_call
node_llm_call -->|"requests SQL"| node_openai
node_openai -->|"returns SQL"| node_llm_call
node_tool -->|"executes SQL"| node_execution
node_execution -->|"runs query"| node_sqlserver
node_tool -->|"formats rows"| node_formatting
node_formatting -->|"returns results"| node_crew_runtime
node_crew_runtime -->|"returns answer"| node_runner
node_runner -->|"returns result"| node_streamlit
node_streamlit -->|"shows result"| node_user

click node_streamlit "https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/app.py"
click node_runner "https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/run_crew.py"
click node_tool "https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py"
click node_schema "https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py"
click node_prompt "https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py"
click node_llm_call "https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py"
click node_execution "https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py"
click node_formatting "https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.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_user toneBlue
class node_runner,node_crew_runtime toneAmber
class node_tool,node_schema,node_prompt,node_llm_call,node_execution,node_formatting toneMint
class node_sqlserver,node_openai toneRose
```

## Components

### User interface

- [Streamlit UI](https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/app.py): `app.py`

### Crew orchestration

- [Crew runner](https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/run_crew.py): `run_crew.py`
- **CrewAI runtime**

### SQL translation

- [SQL tool](https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py): `text_to_sql_tool.py`
- [Schema retrieval](https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py): `text_to_sql_tool.py`
- [Prompt building](https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py): `text_to_sql_tool.py`
- [SQL generation](https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py): `text_to_sql_tool.py`
- [Query execution](https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py): `text_to_sql_tool.py`
- [Result formatting](https://github.com/mahnoorahmed-dev/nl2sql-crewai/blob/master/text_to_sql_tool.py): `text_to_sql_tool.py`

### External systems

- **SQL Server**
- **OpenAI GPT-4**

### Other components

- **User**

## Connections

- User → Streamlit UI: enters question
- Streamlit UI → Crew runner: calls query
- Crew runner → CrewAI runtime: starts crew
- CrewAI runtime → SQL tool: dispatches tool
- SQL tool → Schema retrieval: retrieves schema
- Schema retrieval → SQL Server: reads metadata
- SQL tool → Prompt building: builds prompt
- Prompt building → SQL generation: provides context
- SQL generation → OpenAI GPT-4: requests SQL
- OpenAI GPT-4 → SQL generation: returns SQL
- SQL tool → Query execution: executes SQL
- Query execution → SQL Server: runs query
- SQL tool → Result formatting: formats rows
- Result formatting → CrewAI runtime: returns results
- CrewAI runtime → Crew runner: returns answer
- Crew runner → Streamlit UI: returns result
- Streamlit UI → User: shows result