How dhruvak99/semanticsql works
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: endpoints Feature endpoints · query_pipeline.py Query pipeline · QueryInterfacePage.tsx Query workspace · query.py Query endpoint
Components 28
User interface
- Query workspace
frontend/src/pages/QueryInterfacePage.tsx - Query API client
frontend/src/api/query.ts - Query history
frontend/src/pages/QueryHistoryPage.tsx - History API client
frontend/src/api/history.ts - Database explorer
frontend/src/pages/DatabaseExplorerPage.tsx - Schema manager
frontend/src/pages/SchemaManagerPage.tsx
API layer
- API router
backend/app/api/v1/api.py - Query endpoint
backend/app/api/v1/endpoints/query.py - Feature endpoints
backend/app/api/v1/endpoints
Query processing
- Query pipeline
backend/app/services/query_pipeline.py - Rule SQL generation
backend/app/services/sql_generation_service.py - LLM SQL generation
backend/app/services/llm_sql_generation_service.py - SQL validation
backend/app/services/sql_validation_service.py - Semantic cache
backend/app/services/semantic_cache_service.py
Operations and data
- Database execution
backend/app/services/database_service.py - Relational database
backend/app/db/session.py - History service
backend/app/services/query_history_service.py - History records
backend/app/models/query_history.py - Redis / memory cache
backend/app/db/redis.py - Runtime configuration
backend/app/core/config.py - Model management
backend/app/services/model_management_service.py - Query analytics
backend/app/services/query_analytics_service.py - Research analytics
backend/app/services/research_analytics_service.py - System monitoring
backend/app/services/system_monitor_service.py - Settings
backend/app/services/settings_service.py - Schema management
backend/app/services/schema_manager_service.py
Other components
- User
- Ollama
Connections 26
- User → Query workspace: enters question
- Query workspace → Query API client: submits query
frontend/src/pages/QueryInterfacePage.tsx - Query API client → Query endpoint: posts request
frontend/src/api/query.ts - API router → Query endpoint: registers route
backend/app/api/v1/api.py - Query endpoint → Query pipeline: processes query
backend/app/api/v1/endpoints/query.py - Query pipeline → Semantic cache: checks cache
backend/app/services/query_pipeline.py - Query pipeline → Rule SQL generation: generates rules
backend/app/services/query_pipeline.py - Query pipeline → LLM SQL generation: generates SQL
backend/app/services/query_pipeline.py - Query pipeline → SQL validation: validates SQL
backend/app/services/query_pipeline.py - Query pipeline → Database execution: executes SQL
backend/app/services/query_pipeline.py - Database execution → Relational database: uses sessions
backend/app/services/database_service.py - LLM SQL generation → Ollama: requests generation
backend/app/services/llm_sql_generation_service.py - Query pipeline → History service: records outcome
backend/app/services/query_pipeline.py - History service → History records: persists records
backend/app/services/query_history_service.py - Semantic cache → Redis / memory cache: uses Redis
README.md - Query workspace → User: displays results
frontend/src/pages/QueryInterfacePage.tsx - Query history → History API client: loads history
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