# chaithanyabs441-ux/text2sql-with-guardrails architecture

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

- Interactive diagram: https://gitdiagram.com/chaithanyabs441-ux/text2sql-with-guardrails
- Repository: https://github.com/chaithanyabs441-ux/text2sql-with-guardrails

## Overview

SafeQuery AI turns authenticated natural-language questions into policy-checked, read-only SQL, then verifies results and returns an answer, warning, or abstention. Its major product areas also include role-based administration, dataset selection/import, schema visualization, and query history. The request flow is documented in the README and supported by the API and generation excerpts; some UI and auxiliary capability wiring is documented but not shown in source excerpts.

Main entry points: [`src/t2s/api/main.py`](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/api/main.py) (FastAPI service), [`src/t2s/generation/generator.py`](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/generation/generator.py) (SQL generation), [`frontend/app.py`](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/frontend/app.py) (Web interface), [`src/t2s/llm/openai_adapter.py`](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/llm/openai_adapter.py) (LLM adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_frontend["Web interface<br/>[app.py]"]
  node_api["FastAPI service<br/>[main.py]"]
end

subgraph group_access["Access and datasets"]
  node_auth[("Identity and grants<br/>[store.py]")]
  node_permissions["Role permissions<br/>[permissions.py]"]
  node_dataset["Dataset import<br/>[main.py]"]
end

subgraph group_query["Query construction and execution"]
  node_schema["Schema introspection<br/>[introspector.py]"]
  node_retriever["Schema retrieval<br/>[retriever.py]"]
  node_generator["SQL generation<br/>[generator.py]"]
  node_prompt["Prompt building<br/>[prompt_builder.py]"]
  node_llm["LLM adapter<br/>[openai_adapter.py]"]
  node_policy["SQL policy<br/>[policy.py]"]
  node_sandbox["Read-only sandbox<br/>[executor.py]"]
  node_database[("PostgreSQL")]
end

subgraph group_trust["Verification and decisions"]
  node_agreement["Candidate agreement<br/>[agreement.py]"]
  node_backtranslation["Back-translation"]
  node_sanity["Result sanity<br/>[sanity_checks.py]"]
  node_comparison["Result comparison"]
  node_calibration["Confidence calibration<br/>[calibration.py]"]
  node_abstention["Answer decision<br/>[abstention.py]"]
end

node_user(("Questioner"))

node_user -->|"asks"| node_frontend
node_frontend -->|"submits queries"| node_api
node_api -->|"checks login and grants"| node_auth
node_api -->|"checks roles"| node_permissions
node_api -->|"selects or imports"| node_dataset
node_api -->|"requests SQL"| node_generator
node_generator -->|"loads schema"| node_schema
node_generator -->|"retrieves context"| node_retriever
node_generator -->|"builds prompt"| node_prompt
node_generator -->|"requests candidates"| node_llm
node_llm -.->|"calls provider"| node_database
node_generator -->|"validates SQL"| node_policy
node_api -->|"executes validated SQL"| node_sandbox
node_sandbox -->|"reads rows"| node_database
node_api -->|"measures agreement"| node_agreement
node_agreement -->|"compares results"| node_comparison
node_api -->|"gets similarity signal"| node_backtranslation
node_api -->|"checks results"| node_sanity
node_api -->|"scores confidence"| node_calibration
node_api -->|"chooses response"| node_abstention
node_api -->|"returns results and history"| node_frontend
node_frontend -->|"requests schema and history"| node_api
node_api -->|"persists account and audit state"| node_database

click node_frontend "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/frontend/app.py"
click node_api "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/api/main.py"
click node_auth "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/auth/store.py"
click node_permissions "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/auth/permissions.py"
click node_dataset "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/api/main.py"
click node_schema "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/schema/introspector.py"
click node_retriever "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/schema/retriever.py"
click node_generator "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/generation/generator.py"
click node_prompt "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/generation/prompt_builder.py"
click node_llm "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/llm/openai_adapter.py"
click node_policy "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/guardrails/policy.py"
click node_sandbox "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/sandbox/executor.py"
click node_agreement "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/agreement.py"
click node_backtranslation "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/back_translation.py"
click node_sanity "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/sanity_checks.py"
click node_comparison "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/result_comparison.py"
click node_calibration "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/calibration.py"
click node_abstention "https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/abstention.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_frontend,node_api toneBlue
class node_auth,node_permissions,node_dataset toneAmber
class node_schema,node_retriever,node_generator,node_prompt,node_llm,node_policy,node_sandbox,node_database toneMint
class node_agreement,node_backtranslation,node_sanity,node_comparison,node_calibration,node_abstention toneRose
class node_user toneIndigo
```

## Components

### User interaction

- [Web interface](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/frontend/app.py): `frontend/app.py`
- [FastAPI service](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/api/main.py): `src/t2s/api/main.py`

### Access and datasets

- [Identity and grants](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/auth/store.py): `src/t2s/auth/store.py`
- [Role permissions](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/auth/permissions.py): `src/t2s/auth/permissions.py`
- [Dataset import](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/api/main.py): `src/t2s/api/main.py`

### Query construction and execution

- [Schema introspection](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/schema/introspector.py): `src/t2s/schema/introspector.py`
- [Schema retrieval](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/schema/retriever.py): `src/t2s/schema/retriever.py`
- [SQL generation](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/generation/generator.py): `src/t2s/generation/generator.py`
- [Prompt building](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/generation/prompt_builder.py): `src/t2s/generation/prompt_builder.py`
- [LLM adapter](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/llm/openai_adapter.py): `src/t2s/llm/openai_adapter.py`
- [SQL policy](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/guardrails/policy.py): `src/t2s/guardrails/policy.py`
- [Read-only sandbox](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/sandbox/executor.py): `src/t2s/sandbox/executor.py`
- **PostgreSQL**

### Verification and decisions

- [Candidate agreement](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/agreement.py): `src/t2s/verification/agreement.py`
- [Back-translation](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/back_translation.py): `src/t2s/verification/back_translation.py`
- [Result sanity](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/sanity_checks.py): `src/t2s/verification/sanity_checks.py`
- [Result comparison](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/result_comparison.py): `src/t2s/verification/result_comparison.py`
- [Confidence calibration](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/calibration.py): `src/t2s/verification/calibration.py`
- [Answer decision](https://github.com/chaithanyabs441-ux/text2sql-with-guardrails/blob/main/src/t2s/verification/abstention.py): `src/t2s/verification/abstention.py`

### Other components

- **Questioner**

## Connections

- Questioner → Web interface: asks (evidence: `README.md`)
- Web interface → FastAPI service: submits queries (evidence: `README.md`)
- FastAPI service → Identity and grants: checks login and grants (evidence: `src/t2s/api/main.py`)
- FastAPI service → Role permissions: checks roles (evidence: `src/t2s/api/main.py`)
- FastAPI service → Dataset import: selects or imports (evidence: `README.md`)
- FastAPI service → SQL generation: requests SQL (evidence: `README.md`)
- SQL generation → Schema introspection: loads schema (evidence: `src/t2s/generation/generator.py`)
- SQL generation → Schema retrieval: retrieves context (evidence: `src/t2s/generation/generator.py`)
- SQL generation → Prompt building: builds prompt (evidence: `src/t2s/generation/generator.py`)
- SQL generation → LLM adapter: requests candidates (evidence: `src/t2s/generation/generator.py`)
- LLM adapter → PostgreSQL: calls provider
- SQL generation → SQL policy: validates SQL (evidence: `src/t2s/generation/generator.py`)
- FastAPI service → Read-only sandbox: executes validated SQL (evidence: `README.md`)
- Read-only sandbox → PostgreSQL: reads rows (evidence: `src/t2s/sandbox/executor.py`)
- FastAPI service → Candidate agreement: measures agreement (evidence: `README.md`)
- Candidate agreement → Result comparison: compares results (evidence: `src/t2s/verification/agreement.py`)
- FastAPI service → Back-translation: gets similarity signal (evidence: `README.md`)
- FastAPI service → Result sanity: checks results (evidence: `README.md`)
- FastAPI service → Confidence calibration: scores confidence (evidence: `README.md`)
- FastAPI service → Answer decision: chooses response (evidence: `README.md`)
- FastAPI service → Web interface: returns results and history (evidence: `README.md`)
- Web interface → FastAPI service: requests schema and history (evidence: `README.md`)
- FastAPI service → PostgreSQL: persists account and audit state