# eeeee-star/text2sql architecture

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

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

## Overview

Text2SQL turns a user’s natural-language question into retrieved schema context, planned and generated SQL, validated execution, and a synthesized response. Its principal runtime spans the agent service, MCP tool server, and query-target DAL. Separate capabilities support schema/example retrieval, semantic caching, graph-aware context, tenant security, ingestion, replay, and operations. The README documents the main workflow and capabilities; source-index references support selected internal links, while unsampled implementation details are left unconnected.

Main entry points: [`src/agent_service/app.py`](https://github.com/eeeee-star/text2sql/blob/main/src/agent_service/app.py) (Agent API), [`src/mcp_server/main.py`](https://github.com/eeeee-star/text2sql/blob/main/src/mcp_server/main.py) (MCP server), [`src/dal/database.py`](https://github.com/eeeee-star/text2sql/blob/main/src/dal/database.py) (Database access), [`src/agent/graph.py`](https://github.com/eeeee-star/text2sql/blob/main/src/agent/graph.py) (Agent graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent workflow"]
  node_agent_api["Agent API<br/>[app.py]"]
  node_agent_graph["Agent graph<br/>[graph.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_agent_mcp["MCP client<br/>[manager.py]"]
  node_replay["Replay bundles<br/>[replay_bundle.py]"]
end

subgraph group_mcp["MCP tools and retrieval"]
  node_mcp_server["MCP server<br/>[main.py]"]
  node_sql_tool["SQL execution"]
  node_rag["Schema retrieval<br/>[engine.py]"]
  node_cache["Semantic cache<br/>[spacy_pipeline.py]"]
end

subgraph group_data["Data access and ingestion"]
  node_vector[("Vector indexes<br/>[factory.py]")]
  node_ingestion["Schema ingestion<br/>[sync_engine.py]"]
  node_dal["Database access<br/>[database.py]"]
  node_query_target[("Query targets<br/>[factory.py]")]
  node_security["SQL guardrails<br/>[read_only.py]"]
  node_control_db[("Control-plane stores<br/>[semantic_cache.py]")]
end

subgraph group_ops["Operations and observability"]
  node_otel_worker["OTEL worker<br/>[app.py]"]
  node_telemetry["Agent telemetry<br/>[telemetry.py]"]
  node_trace_store[("Trace storage<br/>[postgres.py]")]
end

subgraph group_ui["Operator interface"]
  node_ui_gateway["UI API<br/>[app.py]"]
  node_operator_ui["Operator UI<br/>[api.ts]"]
end

node_user(("User"))

node_user -->|"submits query"| node_agent_api
node_agent_api -->|"runs graph"| node_agent_graph
node_agent_graph -.->|"generates SQL"| node_llm
node_agent_graph -->|"calls tools"| node_agent_mcp
node_agent_api -->|"records or replays"| node_replay
node_agent_mcp -->|"requests tools"| node_mcp_server
node_mcp_server -->|"registers tools"| node_sql_tool
node_sql_tool -->|"executes query"| node_dal
node_sql_tool -.->|"enforces policy"| node_security
node_dal -->|"selects backend"| node_query_target
node_mcp_server -->|"configures retrieval"| node_rag
node_rag -->|"searches vectors"| node_vector
node_ingestion -.->|"builds indexes"| node_vector
node_mcp_server -->|"configures canonicalization"| node_cache
node_cache -->|"uses database"| node_dal
node_dal -.->|"persists metadata"| node_control_db
node_operator_ui -.->|"calls API"| node_ui_gateway
node_agent_api -->|"emits telemetry"| node_telemetry
node_telemetry -.->|"exports traces"| node_otel_worker
node_otel_worker -->|"persists traces"| node_trace_store

click node_agent_api "https://github.com/eeeee-star/text2sql/blob/main/src/agent_service/app.py"
click node_agent_graph "https://github.com/eeeee-star/text2sql/blob/main/src/agent/graph.py"
click node_llm "https://github.com/eeeee-star/text2sql/blob/main/src/agent/llm_client.py"
click node_agent_mcp "https://github.com/eeeee-star/text2sql/blob/main/src/agent/mcp_client/manager.py"
click node_replay "https://github.com/eeeee-star/text2sql/blob/main/src/agent/replay_bundle.py"
click node_mcp_server "https://github.com/eeeee-star/text2sql/blob/main/src/mcp_server/main.py"
click node_sql_tool "https://github.com/eeeee-star/text2sql/blob/main/src/mcp_server/tools/execute_sql_query.py"
click node_rag "https://github.com/eeeee-star/text2sql/blob/main/src/mcp_server/services/rag/engine.py"
click node_cache "https://github.com/eeeee-star/text2sql/blob/main/src/mcp_server/services/canonicalization/spacy_pipeline.py"
click node_vector "https://github.com/eeeee-star/text2sql/blob/main/src/ingestion/vector_indexes/factory.py"
click node_ingestion "https://github.com/eeeee-star/text2sql/blob/main/src/ingestion/sync_engine.py"
click node_dal "https://github.com/eeeee-star/text2sql/blob/main/src/dal/database.py"
click node_query_target "https://github.com/eeeee-star/text2sql/blob/main/src/dal/factory.py"
click node_security "https://github.com/eeeee-star/text2sql/blob/main/src/dal/util/read_only.py"
click node_control_db "https://github.com/eeeee-star/text2sql/blob/main/src/dal/postgres/semantic_cache.py"
click node_ui_gateway "https://github.com/eeeee-star/text2sql/blob/main/src/ui_api_gateway/app.py"
click node_operator_ui "https://github.com/eeeee-star/text2sql/blob/main/ui/src/api.ts"
click node_otel_worker "https://github.com/eeeee-star/text2sql/blob/main/src/otel_worker/app.py"
click node_telemetry "https://github.com/eeeee-star/text2sql/blob/main/src/agent/telemetry.py"
click node_trace_store "https://github.com/eeeee-star/text2sql/blob/main/src/otel_worker/storage/postgres.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_agent_api,node_agent_graph,node_llm,node_agent_mcp,node_replay,node_user toneBlue
class node_mcp_server,node_sql_tool,node_rag,node_cache toneAmber
class node_vector,node_ingestion,node_dal,node_query_target,node_security,node_control_db toneMint
class node_otel_worker,node_telemetry,node_trace_store toneRose
class node_ui_gateway,node_operator_ui toneIndigo
```

## Components

### Agent workflow

- [Agent API](https://github.com/eeeee-star/text2sql/blob/main/src/agent_service/app.py): `src/agent_service/app.py`
- [Agent graph](https://github.com/eeeee-star/text2sql/blob/main/src/agent/graph.py): `src/agent/graph.py`
- [LLM client](https://github.com/eeeee-star/text2sql/blob/main/src/agent/llm_client.py): `src/agent/llm_client.py`
- [MCP client](https://github.com/eeeee-star/text2sql/blob/main/src/agent/mcp_client/manager.py): `src/agent/mcp_client/manager.py`
- [Replay bundles](https://github.com/eeeee-star/text2sql/blob/main/src/agent/replay_bundle.py): `src/agent/replay_bundle.py`

### MCP tools and retrieval

- [MCP server](https://github.com/eeeee-star/text2sql/blob/main/src/mcp_server/main.py): `src/mcp_server/main.py`
- [SQL execution](https://github.com/eeeee-star/text2sql/blob/main/src/mcp_server/tools/execute_sql_query.py): `src/mcp_server/tools/execute_sql_query.py`
- [Schema retrieval](https://github.com/eeeee-star/text2sql/blob/main/src/mcp_server/services/rag/engine.py): `src/mcp_server/services/rag/engine.py`
- [Semantic cache](https://github.com/eeeee-star/text2sql/blob/main/src/mcp_server/services/canonicalization/spacy_pipeline.py): `src/mcp_server/services/canonicalization/spacy_pipeline.py`

### Data access and ingestion

- [Vector indexes](https://github.com/eeeee-star/text2sql/blob/main/src/ingestion/vector_indexes/factory.py): `src/ingestion/vector_indexes/factory.py`
- [Schema ingestion](https://github.com/eeeee-star/text2sql/blob/main/src/ingestion/sync_engine.py): `src/ingestion/sync_engine.py`
- [Database access](https://github.com/eeeee-star/text2sql/blob/main/src/dal/database.py): `src/dal/database.py`
- [Query targets](https://github.com/eeeee-star/text2sql/blob/main/src/dal/factory.py): `src/dal/factory.py`
- [SQL guardrails](https://github.com/eeeee-star/text2sql/blob/main/src/dal/util/read_only.py): `src/dal/util/read_only.py`
- [Control-plane stores](https://github.com/eeeee-star/text2sql/blob/main/src/dal/postgres/semantic_cache.py): `src/dal/postgres/semantic_cache.py`

### Operations and observability

- [OTEL worker](https://github.com/eeeee-star/text2sql/blob/main/src/otel_worker/app.py): `src/otel_worker/app.py`
- [Agent telemetry](https://github.com/eeeee-star/text2sql/blob/main/src/agent/telemetry.py): `src/agent/telemetry.py`
- [Trace storage](https://github.com/eeeee-star/text2sql/blob/main/src/otel_worker/storage/postgres.py): `src/otel_worker/storage/postgres.py`

### Operator interface

- [UI API](https://github.com/eeeee-star/text2sql/blob/main/src/ui_api_gateway/app.py): `src/ui_api_gateway/app.py`
- [Operator UI](https://github.com/eeeee-star/text2sql/blob/main/ui/src/api.ts): `ui/src/api.ts`

### Other components

- **User**

## Connections

- User → Agent API: submits query (evidence: `README.md`)
- Agent API → Agent graph: runs graph (evidence: `src/agent_service/app.py`)
- Agent graph → LLM client: generates SQL
- Agent graph → MCP client: calls tools (evidence: `README.md`)
- Agent API → Replay bundles: records or replays (evidence: `src/agent_service/app.py`)
- MCP client → MCP server: requests tools (evidence: `README.md`)
- MCP server → SQL execution: registers tools (evidence: `src/mcp_server/main.py`)
- SQL execution → Database access: executes query (evidence: `src/mcp_server/tools/execute_sql_query.py`)
- SQL execution → SQL guardrails: enforces policy (evidence: `src/mcp_server/tools/execute_sql_query.py`)
- Database access → Query targets: selects backend (evidence: `src/dal/database.py`)
- MCP server → Schema retrieval: configures retrieval (evidence: `src/mcp_server/main.py`)
- Schema retrieval → Vector indexes: searches vectors (evidence: `src/mcp_server/services/rag/engine.py`)
- Schema ingestion → Vector indexes: builds indexes
- MCP server → Semantic cache: configures canonicalization (evidence: `src/mcp_server/main.py`)
- Semantic cache → Database access: uses database (evidence: `src/mcp_server/services/canonicalization/spacy_pipeline.py`)
- Database access → Control-plane stores: persists metadata
- Operator UI → UI API: calls API
- Agent API → Agent telemetry: emits telemetry (evidence: `src/agent_service/app.py`)
- Agent telemetry → OTEL worker: exports traces
- OTEL worker → Trace storage: persists traces (evidence: `src/otel_worker/app.py`)