How jitashi-arora/graphsql-genie works
1. Overall shape
- This is a Spring Boot 3 / Java 17 application that sits between a user and a live MySQL database.
- Its core purpose is text-to-SQL: accept a natural-language question, infer the relevant schema context, build SQL, execute it, and render results.
2. Entry points
- GraphSQLApp is the Spring Boot bootstrap class.
- QueryController is the HTTP boundary for the app, likely serving the main page and handling query submissions from the UI.
- src/main/resources/templates/index.html is the Thymeleaf front-end entry point for the browser-facing workflow.
3. Request flow
- The typical path is: browser/UI → controller → SQL orchestration → schema inspection + AI call → SQL generation → database execution → HTML response.
- The controller should be treated as a thin presentation layer; the main business logic lives in the helper/service classes.
4. Orchestration layer
- SQLGenie is the central coordinator.
- Based on the README and file naming, it likely combines:
- the user’s question,
- the current database schema,
- AI-generated intent/filters,
- graph-based join path resolution,
- final SQL assembly and execution.
- This class is the main “application logic” boundary.
5. Schema discovery
- SchemaIndexer is responsible for inspecting the live database through JDBC metadata.
- It likely reads tables, columns, primary keys, and foreign keys from MySQL at runtime instead of relying on hardcoded schema definitions.
- This makes the system schema-driven and keeps the app coupled to the current database state.
6. Schema graph model
- SchemaGraph represents the database as a graph where tables are nodes and foreign keys are edges.
- This is the deterministic subsystem used to reason about joins.
- It is the structural bridge between metadata discovery and SQL join construction.
7. Join-path computation
- The README says BFS is used for joins, so the graph subsystem likely supports shortest-path traversal between tables.
- This means multi-table queries are not left entirely to the LLM; the app uses graph search to find valid join chains across tables.
- Architecturally, this is the key deterministic boundary that reduces reliance on AI for correctness.
8. AI integration
- AIClient is the external-service adapter for the LLM provider.
- Based on the README, it likely calls Groq Cloud API with a Llama 3.1 model.
- Its role is to infer user intent and help identify the tables, conditions, or query semantics needed, while not owning final SQL execution.
9. Data access and execution
- The app connects to a live MySQL database through JDBC/Spring configuration in application.properties.
- The database is both the source of schema metadata and the execution target for the generated SQL.
- This creates two distinct DB interactions: metadata read and query execution.
10. Presentation layer
- index.html is the only visible UI artifact in the tree, so the front end is likely a server-rendered Thymeleaf page rather than a separate SPA.
- Results are probably returned as an HTML table or message view, keeping the app monolithic and simple to deploy.
11. Testing boundaries
- DBTest, GraphTest, and IntegrationTest indicate separation of concerns in validation:
- database connectivity / live metadata,
- graph and traversal logic,
- end-to-end pipeline behavior.
- That suggests the architecture is built around independently testable subsystems rather than one large service method.
12. Packaging and deployment
- pom.xml makes this a Maven-managed Java service.
- Dockerfile indicates the app is intended to be containerized as a single deployable unit.
- Runtime configuration is externalized via application.properties, which likely holds DB and API credentials.
13. Key architectural boundary
- The most important design split is between:
- probabilistic interpretation via the LLM,
- and deterministic schema/join resolution via graph traversal.
- That hybrid approach is the defining architecture of the repository and should be central in any diagram.
14. External dependencies
- The app depends materially on two outside systems:
- MySQL for schema and data,
- Groq Cloud for natural-language understanding.
- The application itself is the orchestration layer that mediates between them.
Main entry points: SQLGenie.java SQLGenie · QueryController.java QueryController · IntegrationTest.java IntegrationTest · GraphSQLApp.java GraphSQLApp
Components 16
Application
Spring Boot text-to-SQL service and its core runtime components
- GraphSQLApp · Spring Boot entry point
src/main/java/com/graphsql/GraphSQLApp.java - QueryController · HTTP boundary for query submission and page rendering
src/main/java/com/graphsql/QueryController.java - SQLGenie · Central coordinator for text-to-SQL flow
src/main/java/com/graphsql/SQLGenie.java - SchemaIndexer · Reads live JDBC metadata for tables, columns, and keys
src/main/java/com/graphsql/SchemaIndexer.java - SchemaGraph · Represents tables and foreign-key links for join reasoning
src/main/java/com/graphsql/SchemaGraph.java - AIClient · Calls the external LLM service for intent and query help
src/main/java/com/graphsql/AIClient.java - index.html · Server-rendered browser entry point
src/main/resources/templates/index.html - application.properties · Externalized configuration for database and AI settings
src/main/resources/application.properties
External Systems
Runtime dependencies used for AI inference and database access
- MySQL · Live relational database used for metadata and query execution
- Groq Cloud · External AI provider for natural-language understanding
Tests
Test coverage for database, graph, and end-to-end behavior
- DBTest · Validates database connectivity and metadata access
src/main/java/com/graphsql/DBTest.java - GraphTest · Validates schema graph and traversal logic
src/main/java/com/graphsql/GraphTest.java - IntegrationTest · Exercises the full request-to-SQL pipeline
src/main/java/com/graphsql/IntegrationTest.java
Other components
- pom.xml · Maven build and dependency definition
pom.xml - Dockerfile · Container packaging for the application
Dockerfile - README.md · Project overview and usage guidance
README.md
Connections 22
- GraphSQLApp → QueryController: wires · Bootstraps the web layer
- QueryController → index.html: renders · Serves the browser UI
- QueryController → SQLGenie: delegates · Hands query requests to orchestration
- SQLGenie → SchemaIndexer: loads schema · Fetches live database metadata
- SQLGenie → SchemaGraph: builds joins · Uses graph structure for table linkage
- SQLGenie → AIClient: asks AI · Sends prompt and context for interpretation
- SQLGenie → MySQL: executes SQL · Runs generated queries against the live database
- SchemaIndexer → MySQL: reads metadata · Inspects JDBC metadata from the database
- SchemaGraph → MySQL: models schema · Reflects the live relational structure
- AIClient → Groq Cloud: calls · Invokes the external LLM API
- QueryController → SQLGenie: returns results · Passes result data back to the presentation layer
- SQLGenie → index.html: formats view · Supplies data for HTML response rendering
- application.properties → MySQL: configures · Provides connection settings
- application.properties → Groq Cloud: configures · Provides API and model settings
- DBTest → MySQL: verifies · Checks database access and metadata behavior
- GraphTest → SchemaGraph: verifies · Checks graph traversal and join-path logic
- IntegrationTest → QueryController: drives · Exercises the HTTP and orchestration pipeline
- IntegrationTest → SQLGenie: covers · Validates the core text-to-SQL flow
- IntegrationTest → MySQL: uses · Depends on a live database for end-to-end validation
- pom.xml → GraphSQLApp: builds · Defines the Maven project for the app
- Dockerfile → GraphSQLApp: packages · Containerizes the Spring Boot service
- README.md → SQLGenie: describes · Documents the central orchestration flow