# aditihnayak/text-to-sql-guardrails architecture

> Architecture diagram of the GitHub repository aditihnayak/text-to-sql-guardrails, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aditihnayak/text-to-sql-guardrails
- Repository: https://github.com/aditihnayak/text-to-sql-guardrails

## Overview

This is a Text-to-SQL API: a question is matched to relevant database tables, turned into a prompt, and sent to an LLM for SQL generation. The API validates and bounds the SQL before read-only execution, then checks the result through back-translation, sanity checks, and an independently generated query before returning rows and a confidence score. Schema discovery, retrieval, generation, execution, and confidence assessment are distinct stages. The excerpts show the API pipeline and its principal calls; the frontend and some integrations were not sampled, so their connections are omitted.

Main entry points: [`app/main.py`](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/main.py) (Query API), [`app/schema_filter.py`](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/schema_filter.py) (Table retrieval), [`app/back_translation.py`](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/back_translation.py) (Back-translation), [`app/llm_client.py`](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/llm_client.py) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API orchestration"]
  node_api["Query API<br/>[main.py]"]
  node_metrics["Query metrics<br/>[metrics.py]"]
end

subgraph group_schema["Schema and prompting"]
  node_schema_introspection["Schema discovery"]
  node_schema_filter["Table retrieval<br/>[schema_filter.py]"]
  node_embeddings["Text embeddings<br/>[embeddings.py]"]
  node_schema_metadata["Table descriptions<br/>[schema_metadata.py]"]
  node_prompt["Prompt construction"]
  node_few_shot["Example prompts"]
end

subgraph group_generation["SQL generation and safety"]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_guardrail["SQL guardrails<br/>[guardrail.py]"]
  node_sql_validator["SQL validation<br/>[sql_validator.py]"]
end

subgraph group_verification["Result verification"]
  node_back_translation["Back-translation"]
  node_sanity["Result sanity<br/>[sanity_checker.py]"]
  node_alternatives["Alternative queries"]
  node_confidence["Confidence scoring"]
end

subgraph group_storage["Database access"]
  node_executor["Read-only execution<br/>[query_executor.py]"]
  node_db_engine["Database engine<br/>[db.py]"]
end

node_user(("Questioner"))
node_groq["Groq service"]
node_database[("PostgreSQL database")]

node_user -->|"submits question"| node_api
node_api -->|"discovers schema"| node_schema_introspection
node_api -->|"retrieves tables"| node_schema_filter
node_schema_filter -->|"embeds text"| node_embeddings
node_schema_filter -->|"reads descriptions"| node_schema_metadata
node_api -->|"builds prompt"| node_prompt
node_prompt -->|"uses examples"| node_few_shot
node_api -->|"generates SQL"| node_llm
node_llm -->|"requests generation"| node_groq
node_api -->|"checks SQL"| node_guardrail
node_guardrail -->|"validates SQL"| node_sql_validator
node_api -->|"executes SQL"| node_executor
node_executor -->|"opens connection"| node_db_engine
node_db_engine -.->|"connects to"| node_database
node_api -->|"checks alignment"| node_back_translation
node_back_translation -->|"requests translation"| node_llm
node_back_translation -->|"compares meaning"| node_embeddings
node_api -->|"checks rows"| node_sanity
node_api -->|"builds comparison"| node_alternatives
node_api -->|"scores confidence"| node_confidence
node_api -->|"records queries"| node_metrics

click node_api "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/main.py"
click node_metrics "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/metrics.py"
click node_schema_introspection "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/schema_introspection.py"
click node_schema_filter "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/schema_filter.py"
click node_embeddings "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/embeddings.py"
click node_schema_metadata "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/schema_metadata.py"
click node_prompt "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/prompt_constructor.py"
click node_few_shot "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/few_shot_examples.py"
click node_llm "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/llm_client.py"
click node_guardrail "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/guardrail.py"
click node_sql_validator "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/sql_validator.py"
click node_executor "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/query_executor.py"
click node_db_engine "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/db.py"
click node_back_translation "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/back_translation.py"
click node_sanity "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/sanity_checker.py"
click node_alternatives "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/multi_query_validator.py"
click node_confidence "https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/confidence_scorer.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_api,node_metrics toneBlue
class node_schema_introspection,node_schema_filter,node_embeddings,node_schema_metadata,node_prompt,node_few_shot,node_database toneAmber
class node_llm,node_guardrail,node_sql_validator toneMint
class node_back_translation,node_sanity,node_alternatives,node_confidence toneRose
class node_executor,node_db_engine,node_user,node_groq toneIndigo
```

## Components

### API orchestration

- [Query API](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/main.py): `app/main.py`
- [Query metrics](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/metrics.py): `app/metrics.py`

### Schema and prompting

- [Schema discovery](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/schema_introspection.py): `app/schema_introspection.py`
- [Table retrieval](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/schema_filter.py): `app/schema_filter.py`
- [Text embeddings](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/embeddings.py): `app/embeddings.py`
- [Table descriptions](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/schema_metadata.py): `app/schema_metadata.py`
- [Prompt construction](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/prompt_constructor.py): `app/prompt_constructor.py`
- [Example prompts](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/few_shot_examples.py): `app/few_shot_examples.py`

### SQL generation and safety

- [LLM client](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/llm_client.py): `app/llm_client.py`
- [SQL guardrails](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/guardrail.py): `app/guardrail.py`
- [SQL validation](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/sql_validator.py): `app/sql_validator.py`

### Result verification

- [Back-translation](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/back_translation.py): `app/back_translation.py`
- [Result sanity](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/sanity_checker.py): `app/sanity_checker.py`
- [Alternative queries](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/multi_query_validator.py): `app/multi_query_validator.py`
- [Confidence scoring](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/confidence_scorer.py): `app/confidence_scorer.py`

### Database access

- [Read-only execution](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/query_executor.py): `app/query_executor.py`
- [Database engine](https://github.com/aditihnayak/text-to-sql-guardrails/blob/main/app/db.py): `app/db.py`

### Other components

- **Questioner**
- **Groq service**
- **PostgreSQL database**

## Connections

- Questioner → Query API: submits question (evidence: `app/main.py`)
- Query API → Schema discovery: discovers schema (evidence: `app/main.py`)
- Query API → Table retrieval: retrieves tables (evidence: `app/main.py`)
- Table retrieval → Text embeddings: embeds text (evidence: `app/schema_filter.py`)
- Table retrieval → Table descriptions: reads descriptions (evidence: `app/schema_filter.py`)
- Query API → Prompt construction: builds prompt (evidence: `app/main.py`)
- Prompt construction → Example prompts: uses examples (evidence: `app/prompt_constructor.py`)
- Query API → LLM client: generates SQL (evidence: `app/main.py`)
- LLM client → Groq service: requests generation (evidence: `app/llm_client.py`)
- Query API → SQL guardrails: checks SQL (evidence: `app/main.py`)
- SQL guardrails → SQL validation: validates SQL (evidence: `app/guardrail.py`)
- Query API → Read-only execution: executes SQL (evidence: `app/main.py`)
- Read-only execution → Database engine: opens connection (evidence: `app/query_executor.py`)
- Database engine → PostgreSQL database: connects to
- Query API → Back-translation: checks alignment (evidence: `app/main.py`)
- Back-translation → LLM client: requests translation (evidence: `app/back_translation.py`)
- Back-translation → Text embeddings: compares meaning (evidence: `app/back_translation.py`)
- Query API → Result sanity: checks rows (evidence: `app/main.py`)
- Query API → Alternative queries: builds comparison (evidence: `app/main.py`)
- Query API → Confidence scoring: scores confidence (evidence: `app/main.py`)
- Query API → Query metrics: records queries (evidence: `app/main.py`)
