# guocjsh/supersql architecture

> Architecture diagram of the GitHub repository guocjsh/supersql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guocjsh/supersql
- Repository: https://github.com/guocjsh/supersql

## Overview

##### Project Overview and Major Components
- Project Type: A modular, multi-module Java framework that transforms natural language queries into SQL using Retrieval-Augmented Generation (RAG) techniques. It combines a backend processing engine, training modules, integration with external AI chat/embedding providers (like Azure OpenAI and Ollama), vector database connectivity (e.g., Chroma), and a modern web UI.
- Super-Sql Core Module: Contains the SQL generation logic, builders, engine interfaces/implementations (e.g., SpringSqlEngine, RagEngine), chat prompt utilities, vector store abstractions, and supporting utilities.
- Integration Modules: Super-sql-mybatis-plus (for MyBatis integration) and super-sql-spring-boot-starter (Spring Boot auto-configuration) that enable smooth integration into Spring applications.
- Console Module: The “super-sql-console” application includes REST controllers (e.g., DocumentController, SuperChatController, SuperSqlController) and configuration classes (like WebCorsFilter) that expose endpoints for SQL generation, execution, and training.
- UI Module: The “super-sql-ui” directory represents the frontend (built likely with Vue/Vite) which provides the Chat interface. It interacts (via REST calls) with the Super-Sql console.
- External AI & Vector Support: Integration with Azure Open AI, Ollama, and support for vector database components (e.g., Chroma) are key external pieces that support text-to-SQL functionality.

##### Analyzing the File Structure for Architectural Clues
- Notice the clear multi-module Maven structure with separate projects for core functionality, integration (MyBatis Plus and Spring Boot Starter), the console application, and the independent UI.
- The core package (under super-sql-core) contains sub-packages such as builder, engine, model, prompt, service, and vector – indicating a layered architecture where the core SQL generation and training logic is encapsulated.
- The console module (super-sql-console) holds the Spring Boot application entry point and controllers, which likely serve as the API backend.
- The UI module (super-sql-ui) appears to be a single-page application (SPA) interfacing with users, with dedicated API directories and component layouts.
- Configuration files (e.g., application.yml, pom.xml files, auto-configuration classes in the starter module) emphasize the framework’s extensibility and spring ecosystem integration.

a. Components to include:
- Frontend/UI (super-sql-ui): Displaying a chat interface for user input.
- REST API/Console Application (super-sql-console): Handling HTTP requests, coordinating calls between the UI and backend services.
- Core Engine (super-sql-core): The central logic for converting natural language questions to SQL. It incorporates:
- Chat Model Integration: Components for Azure OpenAI Chat Model and Ollama’s ChatModel.
- SQL Engine: Classes like SpringSqlEngine and underlying engine implementations (e.g., RagEngine, SpringRagEngine).
- Builders: Components such as FollowupQuestionsBuilder, SqlEngineBuilder, TrainBuilder that prepare training and query logic.
- Persistence/Database Integration:
- MyBatis Plus Integration (super-sql-mybatis-plus) for mapping and executing SQL statements.
- External vector database connectivity (e.g., through Chroma or other supported vector databases) for similarity search or augmented training.
- Configuration / Auto-Configuration Module (super-sql-spring-boot-starter): Handling Spring Boot integration and auto-configuration.

b. Relationships and Data Flow:
- User Interaction: The UI sends natural language queries to the REST API.
- REST API: Controllers delegate received queries to the SQL Engine.
- SQL Engine: Uses the assigned Chat Model to generate SQL queries by invoking builder classes and applying RAG-based techniques.
- Database Execution: The generated SQL is executed via MyBatis Plus or similar DB integration.
- Training Flow: Separate endpoints (controllers) trigger training operations using provided DDL or SQL examples, updating the backend learning modules.
- External Service Interaction: The engine communicates with external AI services (Azure OpenAI/Ollama) and vector databases as needed (with configuration provided in YAML files).

##### Specific Elements
- Each component label (for instance, “Super-Sql Core Engine”, “Azure OpenAI Chat Model”, “Ollama Chat Model”, “MyBatis Plus Mapper”, “Super-Sql UI”).
- From User (UI) to REST Controller.
- From Controller to SQL Engine, showing method invocations such as “generateSql(query)” and “executeSql(sql)”.
- Flow from SQL Engine to the Vector Store component for retrieval tasks.
- Data movement from SQL Engine through MyBatis to the database.
- Supplement with annotations for key configuration points (like YAML configuration for AI models) and training methods (for DDL or SQL training endpoints).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Super-Sql UI"]:::frontend
    end

    %% API/Application Layer
    subgraph "API/Application Layer"
        REST["Super-Sql Console (REST API)"]:::backend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        CORE["Super-Sql Core Engine"]:::backend
        ENGINE["SQL Engine"]:::backend
        BUILDERS["Builders (FollowupQuestionsBuilder,SqlEngineBuilder,TrainBuilder)"]:::backend
        VECTOR["Vector Store"]:::backend
        AZURE_MODEL["Azure OpenAI Chat Model"]:::external
        OLLAMA_MODEL["Ollama Chat Model"]:::external
    end

    %% Integration Layer
    subgraph "Integration Layer"
        MYBATIS["MyBatis Plus Integration"]:::integration
        AUTO["Spring Boot Starter Auto-Configuration"]:::integration
    end

    %% Database Layer
    subgraph "Database Layer"
        DB["Database (SQL Execution)"]:::integration
    end

    %% Connections
    UI -->|"sendQuery"| REST
    REST -->|"generateSql(query)"| CORE
    REST -->|"train(sql)"| CORE
    CORE -->|"processSQL"| ENGINE
    CORE -->|"invokeBuilders"| BUILDERS
    CORE -->|"retrieveData"| VECTOR
    CORE -->|"callAzure"| AZURE_MODEL
    CORE -->|"callOllama"| OLLAMA_MODEL
    CORE -->|"executeSql(sql)"| MYBATIS
    MYBATIS -->|"performSQL"| DB
    AUTO -.->|"autoWire"| REST
    AUTO -.->|"autoWire"| MYBATIS

    %% Click events
    click UI "https://github.com/guocjsh/supersql/tree/master/super-sql-ui/"
    click CORE "https://github.com/guocjsh/supersql/tree/master/super-sql-core/"
    click REST "https://github.com/guocjsh/supersql/tree/master/super-sql-console/"
    click MYBATIS "https://github.com/guocjsh/supersql/tree/master/super-sql-mybatis-plus/"
    click AUTO "https://github.com/guocjsh/supersql/tree/master/super-sql-spring-boot-starter/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef integration fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef external fill:#F9D5BB,stroke:#000,stroke-width:2px;
```
