# nandhinikm/text_sql_ai_demo_project architecture

> Architecture diagram of the GitHub repository nandhinikm/text_sql_ai_demo_project, 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/nandhinikm/text_sql_ai_demo_project
- Repository: https://github.com/nandhinikm/text_sql_ai_demo_project

## Overview

This is a conversational text-to-SQL application: users ask in plain language, clarify ambiguous requests, receive generated SQL checked for safety, and see query results. The Streamlit and CLI interfaces both delegate to the shared pipeline, which owns the domain flow and database execution. The README documents the repair loop and mock/offline mode; sampled source confirms the pipeline, clarification, validation, database, configuration, and LLM-client responsibilities. Some pipeline implementation lines were omitted, so only documented workflow links are shown where wiring was not directly visible.

Main entry points: [`src/pipeline.py`](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/pipeline.py) (Text-to-SQL pipeline), [`app.py`](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/app.py) (Streamlit chat), [`cli.py`](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/cli.py) (Terminal chat), [`src/db.py`](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/db.py) (Read-only database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_streamlit_ui["Streamlit chat<br/>[app.py]"]
  node_cli["Terminal chat<br/>[cli.py]"]
end

subgraph group_orchestration["Query orchestration"]
  node_pipeline["Text-to-SQL pipeline<br/>[pipeline.py]"]
  node_clarifier["Clarification engine<br/>[clarifier.py]"]
  node_schema_utils["Schema formatting<br/>[schema_utils.py]"]
end

subgraph group_query_safety["Generation and safety"]
  node_generator["SQL generation and repair<br/>[sql_generator.py]"]
  node_validator["SQL safety validator<br/>[sql_validator.py]"]
end

subgraph group_runtime_services["Runtime services"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_llm_factory["LLM client factory<br/>[llm_client.py]"]
  node_database["Read-only database access<br/>[db.py]"]
end

node_user(("User"))
node_azure["Azure OpenAI"]
node_sqlite[("SQLite database")]

node_user -->|"asks"| node_streamlit_ui
node_user -->|"asks"| node_cli
node_streamlit_ui -->|"submits question"| node_pipeline
node_cli -->|"submits question"| node_pipeline
node_streamlit_ui -->|"loads settings"| node_settings
node_cli -->|"loads settings"| node_settings
node_streamlit_ui -->|"builds client"| node_llm_factory
node_cli -->|"builds client"| node_llm_factory
node_streamlit_ui -->|"opens database"| node_database
node_cli -->|"opens database"| node_database
node_pipeline -->|"reads schema"| node_database
node_database -->|"provides schema"| node_schema_utils
node_pipeline -->|"formats schema"| node_schema_utils
node_pipeline -->|"checks clarity"| node_clarifier
node_clarifier -->|"judges unclear cases"| node_llm_factory
node_pipeline -->|"generates or repairs SQL"| node_generator
node_generator -->|"requests SQL"| node_llm_factory
node_pipeline -->|"validates SQL"| node_validator
node_pipeline -->|"executes safe SQL"| node_database
node_database -->|"reads query results"| node_sqlite
node_pipeline -->|"returns response"| node_streamlit_ui
node_pipeline -->|"returns response"| node_cli
node_llm_factory -.->|"calls when configured"| node_azure

click node_streamlit_ui "https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/app.py"
click node_cli "https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/cli.py"
click node_pipeline "https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/pipeline.py"
click node_clarifier "https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/clarifier.py"
click node_schema_utils "https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/schema_utils.py"
click node_generator "https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/sql_generator.py"
click node_validator "https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/sql_validator.py"
click node_settings "https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/config.py"
click node_llm_factory "https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/llm_client.py"
click node_database "https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/db.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_ui,node_cli,node_user toneBlue
class node_pipeline,node_clarifier,node_schema_utils,node_sqlite toneAmber
class node_generator,node_validator toneMint
class node_settings,node_llm_factory,node_database toneRose
class node_azure toneIndigo
```

## Components

### User interfaces

- [Streamlit chat](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/app.py): `app.py`
- [Terminal chat](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/cli.py): `cli.py`

### Query orchestration

- [Text-to-SQL pipeline](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/pipeline.py): `src/pipeline.py`
- [Clarification engine](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/clarifier.py): `src/clarifier.py`
- [Schema formatting](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/schema_utils.py): `src/schema_utils.py`

### Generation and safety

- [SQL generation and repair](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/sql_generator.py): `src/sql_generator.py`
- [SQL safety validator](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/sql_validator.py): `src/sql_validator.py`

### Runtime services

- [Runtime settings](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/config.py): `src/config.py`
- [LLM client factory](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/llm_client.py): `src/llm_client.py`
- [Read-only database access](https://github.com/nandhinikm/text_sql_ai_demo_project/blob/main/src/db.py): `src/db.py`

### Other components

- **User**
- **Azure OpenAI**
- **SQLite database**

## Connections

- User → Streamlit chat: asks
- User → Terminal chat: asks
- Streamlit chat → Text-to-SQL pipeline: submits question
- Terminal chat → Text-to-SQL pipeline: submits question
- Streamlit chat → Runtime settings: loads settings
- Terminal chat → Runtime settings: loads settings
- Streamlit chat → LLM client factory: builds client
- Terminal chat → LLM client factory: builds client
- Streamlit chat → Read-only database access: opens database
- Terminal chat → Read-only database access: opens database
- Text-to-SQL pipeline → Read-only database access: reads schema
- Read-only database access → Schema formatting: provides schema
- Text-to-SQL pipeline → Schema formatting: formats schema
- Text-to-SQL pipeline → Clarification engine: checks clarity
- Clarification engine → LLM client factory: judges unclear cases
- Text-to-SQL pipeline → SQL generation and repair: generates or repairs SQL
- SQL generation and repair → LLM client factory: requests SQL
- Text-to-SQL pipeline → SQL safety validator: validates SQL
- Text-to-SQL pipeline → Read-only database access: executes safe SQL
- Read-only database access → SQLite database: reads query results
- Text-to-SQL pipeline → Streamlit chat: returns response
- Text-to-SQL pipeline → Terminal chat: returns response
- LLM client factory → Azure OpenAI: calls when configured