# dhruvak99/semanticsql architecture

> Architecture diagram of the GitHub repository dhruvak99/semanticsql, 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/dhruvak99/semanticsql
- Repository: https://github.com/dhruvak99/semanticsql

## Overview

SemanticSQL is a browser-based natural-language-to-SQL product. Users submit a question through the query interface; the backend checks semantic cache, generates SQL on a miss, validates and executes it, and returns results while recording history. The README documents the broader analytics, schema, model, settings, monitoring, and research capabilities, though most of those implementations were not sampled. Edges for the core path use source excerpts or README statements; unsampled feature internals are represented without inferred service calls.

Main entry points: [`backend/app/api/v1/endpoints`](https://github.com/dhruvak99/semanticsql/tree/master/backend/app/api/v1/endpoints) (Feature endpoints), [`backend/app/services/query_pipeline.py`](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/query_pipeline.py) (Query pipeline), [`frontend/src/pages/QueryInterfacePage.tsx`](https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/pages/QueryInterfacePage.tsx) (Query workspace), [`backend/app/api/v1/endpoints/query.py`](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/api/v1/endpoints/query.py) (Query endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_query_page["Query workspace"]
  node_query_client["Query API client<br/>[query.ts]"]
  node_history_page["Query history"]
  node_history_client["History API client<br/>[history.ts]"]
  node_database_page["Database explorer"]
  node_schema_page["Schema manager"]
end

subgraph group_api["API layer"]
  node_api_router["API router<br/>[api.py]"]
  node_query_endpoint["Query endpoint<br/>[query.py]"]
  node_other_endpoints["Feature endpoints"]
end

subgraph group_query["Query processing"]
  node_pipeline["Query pipeline<br/>[query_pipeline.py]"]
  node_rule_generation["Rule SQL generation"]
  node_llm_generation["LLM SQL generation"]
  node_validation["SQL validation"]
  node_cache["Semantic cache"]
end

subgraph group_operations["Operations and data"]
  node_database_service["Database execution"]
  node_relational_db[("Relational database<br/>[session.py]")]
  node_history_service["History service"]
  node_history_store[("History records<br/>[query_history.py]")]
  node_cache_store[("Redis / memory cache<br/>[redis.py]")]
  node_runtime_config["Runtime configuration<br/>[config.py]"]
  node_model_management["Model management"]
  node_analytics["Query analytics"]
  node_research["Research analytics"]
  node_system_monitor["System monitoring"]
  node_settings["Settings"]
  node_schema_manager["Schema management"]
end

node_user(("User"))
node_ollama{{"Ollama"}}

node_user -->|"enters question"| node_query_page
node_query_page -->|"submits query"| node_query_client
node_query_client -->|"posts request"| node_query_endpoint
node_api_router -->|"registers route"| node_query_endpoint
node_query_endpoint -->|"processes query"| node_pipeline
node_pipeline -->|"checks cache"| node_cache
node_pipeline -->|"generates rules"| node_rule_generation
node_pipeline -->|"generates SQL"| node_llm_generation
node_pipeline -->|"validates SQL"| node_validation
node_pipeline -->|"executes SQL"| node_database_service
node_database_service -->|"uses sessions"| node_relational_db
node_llm_generation -->|"requests generation"| node_ollama
node_pipeline -->|"records outcome"| node_history_service
node_history_service -->|"persists records"| node_history_store
node_cache -->|"uses Redis"| node_cache_store
node_query_page -->|"displays results"| node_user
node_history_page -->|"loads history"| node_history_client
node_history_client -.->|"requests history"| node_history_service
node_database_page -.->|"explores databases"| node_other_endpoints
node_schema_page -.->|"manages schema"| node_other_endpoints
node_other_endpoints -.->|"supports model controls"| node_model_management
node_other_endpoints -.->|"supports analytics"| node_analytics
node_other_endpoints -.->|"supports research views"| node_research
node_other_endpoints -.->|"supports monitoring"| node_system_monitor
node_other_endpoints -.->|"supports settings"| node_settings
node_other_endpoints -.->|"supports schema"| node_schema_manager

click node_query_page "https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/pages/QueryInterfacePage.tsx"
click node_query_client "https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/api/query.ts"
click node_history_page "https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/pages/QueryHistoryPage.tsx"
click node_history_client "https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/api/history.ts"
click node_database_page "https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/pages/DatabaseExplorerPage.tsx"
click node_schema_page "https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/pages/SchemaManagerPage.tsx"
click node_api_router "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/api/v1/api.py"
click node_query_endpoint "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/api/v1/endpoints/query.py"
click node_other_endpoints "https://github.com/dhruvak99/semanticsql/tree/master/backend/app/api/v1/endpoints"
click node_pipeline "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/query_pipeline.py"
click node_rule_generation "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/sql_generation_service.py"
click node_llm_generation "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/llm_sql_generation_service.py"
click node_validation "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/sql_validation_service.py"
click node_cache "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/semantic_cache_service.py"
click node_database_service "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/database_service.py"
click node_relational_db "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/db/session.py"
click node_history_service "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/query_history_service.py"
click node_history_store "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/models/query_history.py"
click node_cache_store "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/db/redis.py"
click node_runtime_config "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/core/config.py"
click node_model_management "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/model_management_service.py"
click node_analytics "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/query_analytics_service.py"
click node_research "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/research_analytics_service.py"
click node_system_monitor "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/system_monitor_service.py"
click node_settings "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/settings_service.py"
click node_schema_manager "https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/schema_manager_service.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_query_page,node_query_client,node_history_page,node_history_client,node_database_page,node_schema_page,node_user toneBlue
class node_api_router,node_query_endpoint,node_other_endpoints toneAmber
class node_pipeline,node_rule_generation,node_llm_generation,node_validation,node_cache toneMint
class node_database_service,node_relational_db,node_history_service,node_history_store,node_cache_store,node_runtime_config,node_model_management,node_analytics,node_research,node_system_monitor,node_settings,node_schema_manager toneRose
class node_ollama toneIndigo
```

## Components

### User interface

- [Query workspace](https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/pages/QueryInterfacePage.tsx): `frontend/src/pages/QueryInterfacePage.tsx`
- [Query API client](https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/api/query.ts): `frontend/src/api/query.ts`
- [Query history](https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/pages/QueryHistoryPage.tsx): `frontend/src/pages/QueryHistoryPage.tsx`
- [History API client](https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/api/history.ts): `frontend/src/api/history.ts`
- [Database explorer](https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/pages/DatabaseExplorerPage.tsx): `frontend/src/pages/DatabaseExplorerPage.tsx`
- [Schema manager](https://github.com/dhruvak99/semanticsql/blob/master/frontend/src/pages/SchemaManagerPage.tsx): `frontend/src/pages/SchemaManagerPage.tsx`

### API layer

- [API router](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/api/v1/api.py): `backend/app/api/v1/api.py`
- [Query endpoint](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/api/v1/endpoints/query.py): `backend/app/api/v1/endpoints/query.py`
- [Feature endpoints](https://github.com/dhruvak99/semanticsql/tree/master/backend/app/api/v1/endpoints): `backend/app/api/v1/endpoints`

### Query processing

- [Query pipeline](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/query_pipeline.py): `backend/app/services/query_pipeline.py`
- [Rule SQL generation](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/sql_generation_service.py): `backend/app/services/sql_generation_service.py`
- [LLM SQL generation](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/llm_sql_generation_service.py): `backend/app/services/llm_sql_generation_service.py`
- [SQL validation](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/sql_validation_service.py): `backend/app/services/sql_validation_service.py`
- [Semantic cache](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/semantic_cache_service.py): `backend/app/services/semantic_cache_service.py`

### Operations and data

- [Database execution](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/database_service.py): `backend/app/services/database_service.py`
- [Relational database](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/db/session.py): `backend/app/db/session.py`
- [History service](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/query_history_service.py): `backend/app/services/query_history_service.py`
- [History records](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/models/query_history.py): `backend/app/models/query_history.py`
- [Redis / memory cache](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/db/redis.py): `backend/app/db/redis.py`
- [Runtime configuration](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/core/config.py): `backend/app/core/config.py`
- [Model management](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/model_management_service.py): `backend/app/services/model_management_service.py`
- [Query analytics](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/query_analytics_service.py): `backend/app/services/query_analytics_service.py`
- [Research analytics](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/research_analytics_service.py): `backend/app/services/research_analytics_service.py`
- [System monitoring](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/system_monitor_service.py): `backend/app/services/system_monitor_service.py`
- [Settings](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/settings_service.py): `backend/app/services/settings_service.py`
- [Schema management](https://github.com/dhruvak99/semanticsql/blob/master/backend/app/services/schema_manager_service.py): `backend/app/services/schema_manager_service.py`

### Other components

- **User**
- **Ollama**

## Connections

- User → Query workspace: enters question
- Query workspace → Query API client: submits query (evidence: `frontend/src/pages/QueryInterfacePage.tsx`)
- Query API client → Query endpoint: posts request (evidence: `frontend/src/api/query.ts`)
- API router → Query endpoint: registers route (evidence: `backend/app/api/v1/api.py`)
- Query endpoint → Query pipeline: processes query (evidence: `backend/app/api/v1/endpoints/query.py`)
- Query pipeline → Semantic cache: checks cache (evidence: `backend/app/services/query_pipeline.py`)
- Query pipeline → Rule SQL generation: generates rules (evidence: `backend/app/services/query_pipeline.py`)
- Query pipeline → LLM SQL generation: generates SQL (evidence: `backend/app/services/query_pipeline.py`)
- Query pipeline → SQL validation: validates SQL (evidence: `backend/app/services/query_pipeline.py`)
- Query pipeline → Database execution: executes SQL (evidence: `backend/app/services/query_pipeline.py`)
- Database execution → Relational database: uses sessions (evidence: `backend/app/services/database_service.py`)
- LLM SQL generation → Ollama: requests generation (evidence: `backend/app/services/llm_sql_generation_service.py`)
- Query pipeline → History service: records outcome (evidence: `backend/app/services/query_pipeline.py`)
- History service → History records: persists records (evidence: `backend/app/services/query_history_service.py`)
- Semantic cache → Redis / memory cache: uses Redis (evidence: `README.md`)
- Query workspace → User: displays results (evidence: `frontend/src/pages/QueryInterfacePage.tsx`)
- Query history → History API client: loads history (evidence: `frontend/src/pages/QueryHistoryPage.tsx`)
- History API client → History service: requests history
- Database explorer → Feature endpoints: explores databases
- Schema manager → Feature endpoints: manages schema
- Feature endpoints → Model management: supports model controls
- Feature endpoints → Query analytics: supports analytics
- Feature endpoints → Research analytics: supports research views
- Feature endpoints → System monitoring: supports monitoring
- Feature endpoints → Settings: supports settings
- Feature endpoints → Schema management: supports schema
