# devprajwalv/text-to-sql architecture

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

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

## Overview

Query Studio lets an analyst ask questions about Olist marketplace data, inspect generated SQL, and explore results. The main path runs from the Angular query workspace through FastAPI to retrieval, SQL generation, guarded SQLite execution, and a logged response; review-required queries pause for approval before execution. Separate user-facing capabilities include schema browsing, health status, and paginated results. The README documents indexing and data seeding, but their runtime details are not fully excerpted; edges reflect only shown calls or documented relationships.

Main entry points: [`agent/sql_chain.py`](https://github.com/devprajwalv/text-to-sql/blob/main/agent/sql_chain.py) (Query orchestration), [`api/main.py`](https://github.com/devprajwalv/text-to-sql/blob/main/api/main.py) (FastAPI app), [`frontend/src/app/api.ts`](https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/api.ts) (API client), [`frontend/src/app/chat-window.ts`](https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/chat-window.ts) (Query workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Analyst workspace"]
  node_workspace["Workspace<br/>[app.ts]"]
  node_chat["Query workspace<br/>[chat-window.ts]"]
  node_approval["Approval dialog<br/>[approval-modal.ts]"]
  node_sqlview["SQL display<br/>[sql-display.ts]"]
  node_results["Results table<br/>[results-table.ts]"]
  node_schemaexplorer["Schema explorer<br/>[schema-explorer.ts]"]
  node_client["API client<br/>[api.ts]"]
end

subgraph group_api["HTTP API"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_queryroute["Query routes<br/>[query.py]"]
  node_health["Health route<br/>[health.py]"]
  node_schemaroute["Schema route<br/>[schema.py]"]
end

subgraph group_query["Query workflow"]
  node_chain["Query orchestration<br/>[sql_chain.py]"]
  node_retriever["Table retrieval<br/>[retriever.py]"]
  node_semantic["Semantic catalog<br/>[semantic_layer.py]"]
  node_guard["SQL guard<br/>[hitl_guard.py]"]
  node_examples["Worked examples"]
  node_indexbuilder["Index builder<br/>[build_index.py]"]
end

subgraph group_data["Data and metadata"]
  node_seed["Data importer<br/>[seed.py]"]
  node_schema["Table metadata<br/>[schema.py]"]
  node_dbengine["SQLite connections<br/>[database.py]"]
  node_analyticsdb[("Analytics database<br/>[database.py]")]
  node_logdb[("Request log<br/>[schema.py]")]
end

node_analyst(("Analyst"))
node_openai{{"OpenAI models"}}
node_chroma[("Chroma index")]

node_analyst -->|"uses"| node_workspace
node_workspace -->|"loads health and schema"| node_client
node_workspace -->|"shows query workspace"| node_chat
node_workspace -->|"shows schema explorer"| node_schemaexplorer
node_chat -->|"submits and decides"| node_client
node_chat -->|"opens review"| node_approval
node_chat -->|"displays SQL"| node_sqlview
node_chat -->|"displays results"| node_results
node_schemaexplorer -->|"fetches schema"| node_client
node_results -->|"uses API types"| node_client
node_approval -->|"submits decision"| node_client
node_client -->|"calls API"| node_fastapi
node_fastapi -->|"registers route"| node_health
node_fastapi -->|"registers route"| node_schemaroute
node_fastapi -->|"registers route"| node_queryroute
node_queryroute -->|"calls ask and decide"| node_chain
node_schemaroute -->|"serves catalog"| node_semantic
node_health -->|"checks retrieval mode"| node_retriever
node_health -->|"checks database"| node_dbengine
node_chain -->|"retrieves tables"| node_retriever
node_chain -->|"formats schema context"| node_semantic
node_chain -->|"generates SQL"| node_openai
node_chain -->|"loads examples"| node_examples
node_chain -->|"previews and executes SQL"| node_guard
node_chain -->|"logs requests"| node_dbengine
node_chain -->|"queries data"| node_analyticsdb
node_retriever -->|"builds table documents"| node_semantic
node_retriever -->|"queries index"| node_chroma
node_retriever -->|"embeds questions"| node_openai
node_semantic -->|"reads metadata"| node_schema
node_guard -->|"restricts catalog"| node_schema
node_seed -->|"seeds tables"| node_analyticsdb
node_seed -->|"uses metadata"| node_schema
node_dbengine -->|"connects"| node_analyticsdb
node_fastapi -->|"initializes log schema"| node_dbengine
node_fastapi -->|"creates application tables"| node_schema
node_chain -->|"stores request records"| node_logdb
node_indexbuilder -->|"builds schema documents"| node_semantic
node_indexbuilder -.->|"persists collection"| node_chroma

click node_workspace "https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/app.ts"
click node_chat "https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/chat-window.ts"
click node_approval "https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/approval-modal.ts"
click node_sqlview "https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/sql-display.ts"
click node_results "https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/results-table.ts"
click node_schemaexplorer "https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/schema-explorer.ts"
click node_client "https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/api.ts"
click node_fastapi "https://github.com/devprajwalv/text-to-sql/blob/main/api/main.py"
click node_queryroute "https://github.com/devprajwalv/text-to-sql/blob/main/api/routes/query.py"
click node_health "https://github.com/devprajwalv/text-to-sql/blob/main/api/routes/health.py"
click node_schemaroute "https://github.com/devprajwalv/text-to-sql/blob/main/api/routes/schema.py"
click node_chain "https://github.com/devprajwalv/text-to-sql/blob/main/agent/sql_chain.py"
click node_retriever "https://github.com/devprajwalv/text-to-sql/blob/main/agent/retriever.py"
click node_semantic "https://github.com/devprajwalv/text-to-sql/blob/main/agent/semantic_layer.py"
click node_guard "https://github.com/devprajwalv/text-to-sql/blob/main/agent/hitl_guard.py"
click node_examples "https://github.com/devprajwalv/text-to-sql/blob/main/agent/few_shot_examples.yaml"
click node_seed "https://github.com/devprajwalv/text-to-sql/blob/main/data/seed.py"
click node_schema "https://github.com/devprajwalv/text-to-sql/blob/main/model/schema.py"
click node_dbengine "https://github.com/devprajwalv/text-to-sql/blob/main/model/database.py"
click node_analyticsdb "https://github.com/devprajwalv/text-to-sql/blob/main/model/database.py"
click node_logdb "https://github.com/devprajwalv/text-to-sql/blob/main/model/schema.py"
click node_indexbuilder "https://github.com/devprajwalv/text-to-sql/blob/main/agent/build_index.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_workspace,node_chat,node_approval,node_sqlview,node_results,node_schemaexplorer,node_client toneBlue
class node_fastapi,node_queryroute,node_health,node_schemaroute,node_chroma toneAmber
class node_chain,node_retriever,node_semantic,node_guard,node_examples,node_indexbuilder toneMint
class node_seed,node_schema,node_dbengine,node_analyticsdb,node_logdb toneRose
class node_analyst,node_openai toneIndigo
```

## Components

### Analyst workspace

- [Workspace](https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/app.ts): `frontend/src/app/app.ts`
- [Query workspace](https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/chat-window.ts): `frontend/src/app/chat-window.ts`
- [Approval dialog](https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/approval-modal.ts): `frontend/src/app/approval-modal.ts`
- [SQL display](https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/sql-display.ts): `frontend/src/app/sql-display.ts`
- [Results table](https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/results-table.ts): `frontend/src/app/results-table.ts`
- [Schema explorer](https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/schema-explorer.ts): `frontend/src/app/schema-explorer.ts`
- [API client](https://github.com/devprajwalv/text-to-sql/blob/main/frontend/src/app/api.ts): `frontend/src/app/api.ts`

### HTTP API

- [FastAPI app](https://github.com/devprajwalv/text-to-sql/blob/main/api/main.py): `api/main.py`
- [Query routes](https://github.com/devprajwalv/text-to-sql/blob/main/api/routes/query.py): `api/routes/query.py`
- [Health route](https://github.com/devprajwalv/text-to-sql/blob/main/api/routes/health.py): `api/routes/health.py`
- [Schema route](https://github.com/devprajwalv/text-to-sql/blob/main/api/routes/schema.py): `api/routes/schema.py`

### Query workflow

- [Query orchestration](https://github.com/devprajwalv/text-to-sql/blob/main/agent/sql_chain.py): `agent/sql_chain.py`
- [Table retrieval](https://github.com/devprajwalv/text-to-sql/blob/main/agent/retriever.py): `agent/retriever.py`
- [Semantic catalog](https://github.com/devprajwalv/text-to-sql/blob/main/agent/semantic_layer.py): `agent/semantic_layer.py`
- [SQL guard](https://github.com/devprajwalv/text-to-sql/blob/main/agent/hitl_guard.py): `agent/hitl_guard.py`
- [Worked examples](https://github.com/devprajwalv/text-to-sql/blob/main/agent/few_shot_examples.yaml): `agent/few_shot_examples.yaml`
- [Index builder](https://github.com/devprajwalv/text-to-sql/blob/main/agent/build_index.py): `agent/build_index.py`

### Data and metadata

- [Data importer](https://github.com/devprajwalv/text-to-sql/blob/main/data/seed.py): `data/seed.py`
- [Table metadata](https://github.com/devprajwalv/text-to-sql/blob/main/model/schema.py): `model/schema.py`
- [SQLite connections](https://github.com/devprajwalv/text-to-sql/blob/main/model/database.py): `model/database.py`
- [Analytics database](https://github.com/devprajwalv/text-to-sql/blob/main/model/database.py): `model/database.py`
- [Request log](https://github.com/devprajwalv/text-to-sql/blob/main/model/schema.py): `model/schema.py`

### Other components

- **Analyst**
- **OpenAI models**
- **Chroma index**

## Connections

- Analyst → Workspace: uses (evidence: `README.md`)
- Workspace → API client: loads health and schema (evidence: `frontend/src/app/app.ts`)
- Workspace → Query workspace: shows query workspace (evidence: `frontend/src/app/app.ts`)
- Workspace → Schema explorer: shows schema explorer (evidence: `frontend/src/app/app.ts`)
- Query workspace → API client: submits and decides (evidence: `frontend/src/app/chat-window.ts`)
- Query workspace → Approval dialog: opens review (evidence: `frontend/src/app/chat-window.ts`)
- Query workspace → SQL display: displays SQL (evidence: `frontend/src/app/chat-window.ts`)
- Query workspace → Results table: displays results (evidence: `frontend/src/app/chat-window.ts`)
- Schema explorer → API client: fetches schema (evidence: `frontend/src/app/schema-explorer.ts`)
- Results table → API client: uses API types (evidence: `frontend/src/app/results-table.ts`)
- Approval dialog → API client: submits decision (evidence: `frontend/src/app/approval-modal.ts`)
- API client → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Health route: registers route (evidence: `api/main.py`)
- FastAPI app → Schema route: registers route (evidence: `api/main.py`)
- FastAPI app → Query routes: registers route (evidence: `api/main.py`)
- Query routes → Query orchestration: calls ask and decide (evidence: `api/routes/query.py`)
- Schema route → Semantic catalog: serves catalog (evidence: `api/routes/schema.py`)
- Health route → Table retrieval: checks retrieval mode (evidence: `api/routes/health.py`)
- Health route → SQLite connections: checks database (evidence: `api/routes/health.py`)
- Query orchestration → Table retrieval: retrieves tables (evidence: `agent/sql_chain.py`)
- Query orchestration → Semantic catalog: formats schema context (evidence: `agent/sql_chain.py`)
- Query orchestration → OpenAI models: generates SQL (evidence: `README.md`)
- Query orchestration → Worked examples: loads examples (evidence: `agent/sql_chain.py`)
- Query orchestration → SQL guard: previews and executes SQL (evidence: `agent/sql_chain.py`)
- Query orchestration → SQLite connections: logs requests (evidence: `agent/sql_chain.py`)
- Query orchestration → Analytics database: queries data (evidence: `agent/sql_chain.py`)
- Table retrieval → Semantic catalog: builds table documents (evidence: `agent/retriever.py`)
- Table retrieval → Chroma index: queries index (evidence: `README.md`)
- Table retrieval → OpenAI models: embeds questions (evidence: `README.md`)
- Semantic catalog → Table metadata: reads metadata (evidence: `agent/semantic_layer.py`)
- SQL guard → Table metadata: restricts catalog (evidence: `agent/hitl_guard.py`)
- Data importer → Analytics database: seeds tables (evidence: `README.md`)
- Data importer → Table metadata: uses metadata (evidence: `data/seed.py`)
- SQLite connections → Analytics database: connects (evidence: `model/database.py`)
- FastAPI app → SQLite connections: initializes log schema (evidence: `api/main.py`)
- FastAPI app → Table metadata: creates application tables (evidence: `api/main.py`)
- Query orchestration → Request log: stores request records (evidence: `agent/sql_chain.py`)
- Index builder → Semantic catalog: builds schema documents (evidence: `agent/build_index.py`)
- Index builder → Chroma index: persists collection (evidence: `README.md`)
