# jitashi-arora/graphsql-genie architecture

> Architecture diagram of the GitHub repository jitashi-arora/graphsql-genie, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jitashi-arora/graphsql-genie
- Repository: https://github.com/jitashi-arora/graphsql-genie

## Overview

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: [`src/main/java/com/graphsql/SQLGenie.java`](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/SQLGenie.java) (SQLGenie), [`src/main/java/com/graphsql/QueryController.java`](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/QueryController.java) (QueryController), [`src/main/java/com/graphsql/IntegrationTest.java`](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/IntegrationTest.java) (IntegrationTest), [`src/main/java/com/graphsql/GraphSQLApp.java`](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/GraphSQLApp.java) (GraphSQLApp)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_graphsqlapp(("GraphSQLApp<br/>boot app<br/>[GraphSQLApp.java]"))
  node_querycontroller["QueryController<br/>web controller"]
  node_sqlgenie{{"SQLGenie<br/>orchestrator<br/>[SQLGenie.java]"}}
  node_schemaindexer["SchemaIndexer<br/>metadata service<br/>[SchemaIndexer.java]"]
  node_schemagraph{{"SchemaGraph<br/>graph model<br/>[SchemaGraph.java]"}}
  node_aiclient["AIClient<br/>llm adapter<br/>[AIClient.java]"]
  node_indexhtml["index.html<br/>thymeleaf view<br/>[index.html]"]
  node_appprops["application.properties<br/>runtime config"]
end

subgraph group_external["External Systems"]
  node_mysql[("MySQL<br/>database")]
  node_groq(("Groq Cloud<br/>llm service"))
end

subgraph group_tests["Tests"]
  node_dbtest["DBTest<br/>db test<br/>[DBTest.java]"]
  node_graphtest["GraphTest<br/>graph test<br/>[GraphTest.java]"]
  node_integrationtest["IntegrationTest<br/>e2e test"]
end

node_pomxml["pom.xml<br/>build config<br/>[pom.xml]"]
node_dockerfile["Dockerfile<br/>deploy config"]
node_readme["README.md<br/>docs<br/>[README.md]"]

node_graphsqlapp -->|"wires"| node_querycontroller
node_querycontroller -->|"renders"| node_indexhtml
node_querycontroller -->|"delegates"| node_sqlgenie
node_sqlgenie -->|"loads schema"| node_schemaindexer
node_sqlgenie -->|"builds joins"| node_schemagraph
node_sqlgenie -->|"asks AI"| node_aiclient
node_sqlgenie -->|"executes SQL"| node_mysql
node_schemaindexer -->|"reads metadata"| node_mysql
node_schemagraph -.->|"models schema"| node_mysql
node_aiclient -->|"calls"| node_groq
node_querycontroller -->|"returns results"| node_sqlgenie
node_sqlgenie -.->|"formats view"| node_indexhtml
node_appprops -.->|"configures"| node_mysql
node_appprops -.->|"configures"| node_groq
node_dbtest -.->|"verifies"| node_mysql
node_graphtest -.->|"verifies"| node_schemagraph
node_integrationtest -.->|"drives"| node_querycontroller
node_integrationtest -.->|"covers"| node_sqlgenie
node_integrationtest -.->|"uses"| node_mysql
node_pomxml -.->|"builds"| node_graphsqlapp
node_dockerfile -.->|"packages"| node_graphsqlapp
node_readme -.->|"describes"| node_sqlgenie

click node_graphsqlapp "https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/GraphSQLApp.java"
click node_querycontroller "https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/QueryController.java"
click node_sqlgenie "https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/SQLGenie.java"
click node_schemaindexer "https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/SchemaIndexer.java"
click node_schemagraph "https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/SchemaGraph.java"
click node_aiclient "https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/AIClient.java"
click node_indexhtml "https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/resources/templates/index.html"
click node_appprops "https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/resources/application.properties"
click node_dbtest "https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/DBTest.java"
click node_graphtest "https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/GraphTest.java"
click node_integrationtest "https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/IntegrationTest.java"
click node_pomxml "https://github.com/jitashi-arora/graphsql-genie/blob/main/pom.xml"
click node_dockerfile "https://github.com/jitashi-arora/graphsql-genie/tree/main/Dockerfile"
click node_readme "https://github.com/jitashi-arora/graphsql-genie/blob/main/README.md"

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_graphsqlapp,node_querycontroller,node_sqlgenie,node_schemaindexer,node_schemagraph,node_aiclient,node_indexhtml,node_appprops toneBlue
class node_mysql,node_groq toneAmber
class node_dbtest,node_graphtest,node_integrationtest toneMint
class node_pomxml,node_dockerfile,node_readme toneNeutral
```

## Components

### Application

Spring Boot text-to-SQL service and its core runtime components

- [GraphSQLApp](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/GraphSQLApp.java): boot app · Spring Boot entry point · `src/main/java/com/graphsql/GraphSQLApp.java`
- [QueryController](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/QueryController.java): web controller · HTTP boundary for query submission and page rendering · `src/main/java/com/graphsql/QueryController.java`
- [SQLGenie](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/SQLGenie.java): orchestrator · Central coordinator for text-to-SQL flow · `src/main/java/com/graphsql/SQLGenie.java`
- [SchemaIndexer](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/SchemaIndexer.java): metadata service · Reads live JDBC metadata for tables, columns, and keys · `src/main/java/com/graphsql/SchemaIndexer.java`
- [SchemaGraph](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/SchemaGraph.java): graph model · Represents tables and foreign-key links for join reasoning · `src/main/java/com/graphsql/SchemaGraph.java`
- [AIClient](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/AIClient.java): llm adapter · Calls the external LLM service for intent and query help · `src/main/java/com/graphsql/AIClient.java`
- [index.html](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/resources/templates/index.html): thymeleaf view · Server-rendered browser entry point · `src/main/resources/templates/index.html`
- [application.properties](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/resources/application.properties): runtime config · Externalized configuration for database and AI settings · `src/main/resources/application.properties`

### External Systems

Runtime dependencies used for AI inference and database access

- **MySQL**: database · Live relational database used for metadata and query execution
- **Groq Cloud**: llm service · External AI provider for natural-language understanding

### Tests

Test coverage for database, graph, and end-to-end behavior

- [DBTest](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/DBTest.java): db test · Validates database connectivity and metadata access · `src/main/java/com/graphsql/DBTest.java`
- [GraphTest](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/GraphTest.java): graph test · Validates schema graph and traversal logic · `src/main/java/com/graphsql/GraphTest.java`
- [IntegrationTest](https://github.com/jitashi-arora/graphsql-genie/blob/main/src/main/java/com/graphsql/IntegrationTest.java): e2e test · Exercises the full request-to-SQL pipeline · `src/main/java/com/graphsql/IntegrationTest.java`

### Other components

- [pom.xml](https://github.com/jitashi-arora/graphsql-genie/blob/main/pom.xml): build config · Maven build and dependency definition · `pom.xml`
- [Dockerfile](https://github.com/jitashi-arora/graphsql-genie/tree/main/Dockerfile): deploy config · Container packaging for the application · `Dockerfile`
- [README.md](https://github.com/jitashi-arora/graphsql-genie/blob/main/README.md): docs · Project overview and usage guidance · `README.md`

## Connections

- 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
