# jonkmatsumo/text2sql architecture

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

- Interactive diagram: https://gitdiagram.com/jonkmatsumo/text2sql
- Repository: https://github.com/jonkmatsumo/text2sql

## Overview

Text2SQL turns a natural-language question into guarded SQL, executes it against a configured query-target database, and returns results through the agent service. Its documented agent workflow clarifies or retrieves context, plans and generates SQL, validates it, executes it, and synthesizes a response; the MCP server supplies retrieval and execution tools. Separate operator interfaces, ingestion, semantic caching, and trace observability support the product. The index and excerpts establish some wiring, while several documented capabilities have unsampled implementations; those relationships are shown only when documented or marked unverified.

Main entry points: [`src/agent_service/app.py`](https://github.com/jonkmatsumo/text2sql/blob/main/src/agent_service/app.py) (Agent API), [`src/dal/database.py`](https://github.com/jonkmatsumo/text2sql/blob/main/src/dal/database.py) (DAL Factory), [`src/agent/graph.py`](https://github.com/jonkmatsumo/text2sql/blob/main/src/agent/graph.py) (Agent Graph), [`src/mcp_server/tools`](https://github.com/jonkmatsumo/text2sql/tree/main/src/mcp_server/tools) (MCP Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_ui["Operator UI<br/>[App.tsx]"]
  node_gateway["UI API<br/>[app.py]"]
end

subgraph group_agent["Agent Workflow"]
  node_agent_service["Agent API<br/>[app.py]"]
  node_graph["Agent Graph<br/>[graph.py]"]
  node_agent_nodes["Query Stages"]
  node_llm["LLM Client<br/>[llm_client.py]"]
  node_replay["Replay Bundles<br/>[replay_bundle.py]"]
end

subgraph group_mcp["MCP and Retrieval"]
  node_mcp_server["MCP Server<br/>[main.py]"]
  node_tools["MCP Tools"]
  node_rag["Schema RAG<br/>[engine.py]"]
  node_vector[("ANN Index")]
  node_canonical["Query Canonicalizer<br/>[spacy_pipeline.py]"]
  node_cache[("Semantic Cache<br/>[service.py]")]
  node_ingestion["Schema Ingestion<br/>[sync_engine.py]"]
end

subgraph group_data["Data Access"]
  node_policy["SQL Guardrails<br/>[sql_policy.py]"]
  node_dal["DAL Factory<br/>[database.py]"]
  node_adapters["Database Adapters"]
  node_control_db[("Control Plane")]
  node_target_db[("Query Target")]
end

subgraph group_operations["Operations"]
  node_otel["OTEL Worker<br/>[app.py]"]
  node_otel_storage[("Trace Storage")]
  node_telemetry["Agent Telemetry<br/>[telemetry.py]"]
end

node_user(("Questioner"))
node_operator(("Operator"))

node_user -->|"submits question"| node_agent_service
node_agent_service -->|"runs graph"| node_graph
node_graph -->|"dispatches stages"| node_agent_nodes
node_graph -.->|"uses model"| node_llm
node_agent_service -->|"records replays"| node_replay
node_agent_nodes -->|"calls tools"| node_mcp_server
node_mcp_server -->|"registers tools"| node_tools
node_tools -->|"executes queries"| node_dal
node_tools -->|"enforces policy"| node_policy
node_rag -->|"searches index"| node_vector
node_rag -->|"loads schema"| node_ingestion
node_ingestion -.->|"builds index"| node_vector
node_canonical -.->|"canonicalizes cache keys"| node_cache
node_dal -->|"initializes provider"| node_adapters
node_adapters -->|"queries data"| node_target_db
node_dal -->|"stores metadata"| node_control_db
node_operator -->|"operates system"| node_ui
node_ui -.->|"requests APIs"| node_gateway
node_gateway -->|"configures data access"| node_dal
node_agent_service -->|"emits telemetry"| node_telemetry
node_otel -->|"persists traces"| node_otel_storage

click node_ui "https://github.com/jonkmatsumo/text2sql/blob/main/ui/src/App.tsx"
click node_gateway "https://github.com/jonkmatsumo/text2sql/blob/main/src/ui_api_gateway/app.py"
click node_agent_service "https://github.com/jonkmatsumo/text2sql/blob/main/src/agent_service/app.py"
click node_graph "https://github.com/jonkmatsumo/text2sql/blob/main/src/agent/graph.py"
click node_agent_nodes "https://github.com/jonkmatsumo/text2sql/tree/main/src/agent/nodes"
click node_llm "https://github.com/jonkmatsumo/text2sql/blob/main/src/agent/llm_client.py"
click node_replay "https://github.com/jonkmatsumo/text2sql/blob/main/src/agent/replay_bundle.py"
click node_mcp_server "https://github.com/jonkmatsumo/text2sql/blob/main/src/mcp_server/main.py"
click node_tools "https://github.com/jonkmatsumo/text2sql/tree/main/src/mcp_server/tools"
click node_rag "https://github.com/jonkmatsumo/text2sql/blob/main/src/mcp_server/services/rag/engine.py"
click node_vector "https://github.com/jonkmatsumo/text2sql/tree/main/src/ingestion/vector_indexes"
click node_canonical "https://github.com/jonkmatsumo/text2sql/blob/main/src/mcp_server/services/canonicalization/spacy_pipeline.py"
click node_cache "https://github.com/jonkmatsumo/text2sql/blob/main/src/mcp_server/services/cache/service.py"
click node_ingestion "https://github.com/jonkmatsumo/text2sql/blob/main/src/ingestion/sync_engine.py"
click node_policy "https://github.com/jonkmatsumo/text2sql/blob/main/src/common/policy/sql_policy.py"
click node_dal "https://github.com/jonkmatsumo/text2sql/blob/main/src/dal/database.py"
click node_adapters "https://github.com/jonkmatsumo/text2sql/tree/main/src/dal"
click node_control_db "https://github.com/jonkmatsumo/text2sql/tree/main/src/dal/postgres"
click node_otel "https://github.com/jonkmatsumo/text2sql/blob/main/src/otel_worker/app.py"
click node_otel_storage "https://github.com/jonkmatsumo/text2sql/tree/main/src/otel_worker/storage"
click node_telemetry "https://github.com/jonkmatsumo/text2sql/blob/main/src/agent/telemetry.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_ui,node_gateway toneBlue
class node_agent_service,node_graph,node_agent_nodes,node_llm,node_replay toneAmber
class node_mcp_server,node_tools,node_rag,node_vector,node_canonical,node_cache,node_ingestion toneMint
class node_policy,node_dal,node_adapters,node_control_db,node_target_db toneRose
class node_otel,node_otel_storage,node_telemetry,node_user,node_operator toneIndigo
```

## Components

### User Experience

- [Operator UI](https://github.com/jonkmatsumo/text2sql/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [UI API](https://github.com/jonkmatsumo/text2sql/blob/main/src/ui_api_gateway/app.py): `src/ui_api_gateway/app.py`

### Agent Workflow

- [Agent API](https://github.com/jonkmatsumo/text2sql/blob/main/src/agent_service/app.py): `src/agent_service/app.py`
- [Agent Graph](https://github.com/jonkmatsumo/text2sql/blob/main/src/agent/graph.py): `src/agent/graph.py`
- [Query Stages](https://github.com/jonkmatsumo/text2sql/tree/main/src/agent/nodes): `src/agent/nodes`
- [LLM Client](https://github.com/jonkmatsumo/text2sql/blob/main/src/agent/llm_client.py): `src/agent/llm_client.py`
- [Replay Bundles](https://github.com/jonkmatsumo/text2sql/blob/main/src/agent/replay_bundle.py): `src/agent/replay_bundle.py`

### MCP and Retrieval

- [MCP Server](https://github.com/jonkmatsumo/text2sql/blob/main/src/mcp_server/main.py): `src/mcp_server/main.py`
- [MCP Tools](https://github.com/jonkmatsumo/text2sql/tree/main/src/mcp_server/tools): `src/mcp_server/tools`
- [Schema RAG](https://github.com/jonkmatsumo/text2sql/blob/main/src/mcp_server/services/rag/engine.py): `src/mcp_server/services/rag/engine.py`
- [ANN Index](https://github.com/jonkmatsumo/text2sql/tree/main/src/ingestion/vector_indexes): `src/ingestion/vector_indexes`
- [Query Canonicalizer](https://github.com/jonkmatsumo/text2sql/blob/main/src/mcp_server/services/canonicalization/spacy_pipeline.py): `src/mcp_server/services/canonicalization/spacy_pipeline.py`
- [Semantic Cache](https://github.com/jonkmatsumo/text2sql/blob/main/src/mcp_server/services/cache/service.py): `src/mcp_server/services/cache/service.py`
- [Schema Ingestion](https://github.com/jonkmatsumo/text2sql/blob/main/src/ingestion/sync_engine.py): `src/ingestion/sync_engine.py`

### Data Access

- [SQL Guardrails](https://github.com/jonkmatsumo/text2sql/blob/main/src/common/policy/sql_policy.py): `src/common/policy/sql_policy.py`
- [DAL Factory](https://github.com/jonkmatsumo/text2sql/blob/main/src/dal/database.py): `src/dal/database.py`
- [Database Adapters](https://github.com/jonkmatsumo/text2sql/tree/main/src/dal): `src/dal`
- [Control Plane](https://github.com/jonkmatsumo/text2sql/tree/main/src/dal/postgres): `src/dal/postgres`
- **Query Target**

### Operations

- [OTEL Worker](https://github.com/jonkmatsumo/text2sql/blob/main/src/otel_worker/app.py): `src/otel_worker/app.py`
- [Trace Storage](https://github.com/jonkmatsumo/text2sql/tree/main/src/otel_worker/storage): `src/otel_worker/storage`
- [Agent Telemetry](https://github.com/jonkmatsumo/text2sql/blob/main/src/agent/telemetry.py): `src/agent/telemetry.py`

### Other components

- **Questioner**
- **Operator**

## Connections

- Questioner → Agent API: submits question (evidence: `README.md`)
- Agent API → Agent Graph: runs graph (evidence: `src/agent_service/app.py`)
- Agent Graph → Query Stages: dispatches stages (evidence: `README.md`)
- Agent Graph → LLM Client: uses model
- Agent API → Replay Bundles: records replays (evidence: `src/agent_service/app.py`)
- Query Stages → MCP Server: calls tools (evidence: `README.md`)
- MCP Server → MCP Tools: registers tools (evidence: `src/mcp_server/main.py`)
- MCP Tools → DAL Factory: executes queries (evidence: `README.md`)
- MCP Tools → SQL Guardrails: enforces policy (evidence: `README.md`)
- Schema RAG → ANN Index: searches index (evidence: `src/mcp_server/services/rag/engine.py`)
- Schema RAG → Schema Ingestion: loads schema (evidence: `src/mcp_server/services/rag/engine.py`)
- Schema Ingestion → ANN Index: builds index
- Query Canonicalizer → Semantic Cache: canonicalizes cache keys
- DAL Factory → Database Adapters: initializes provider (evidence: `src/dal/database.py`)
- Database Adapters → Query Target: queries data (evidence: `README.md`)
- DAL Factory → Control Plane: stores metadata (evidence: `README.md`)
- Operator → Operator UI: operates system (evidence: `README.md`)
- Operator UI → UI API: requests APIs
- UI API → DAL Factory: configures data access (evidence: `src/ui_api_gateway/app.py`)
- Agent API → Agent Telemetry: emits telemetry (evidence: `src/agent_service/app.py`)
- OTEL Worker → Trace Storage: persists traces (evidence: `src/otel_worker/app.py`)