NoQL - No Query Language

---

🚀 Project Overview

NoQL (No Query Language) is an AI-powered, full-stack data analysis platform that enables users to query databases using natural language and visualize results instantly.

Key Highlights:

• Natural Language Queries: Ask questions in plain English and get answers from your database
• Interactive Visualizations: Generate tables and charts via a dedicated plot service
• Secure LLM Integration: Backend integrates with OpenAI GPT and Anthropic Claude for intelligent query handling
• Modern Full-Stack Architecture:
  • Backend: Java + Spring Boot, PostgreSQL
  • Frontend: React + TypeScript SPA
  • Plot Service: Dockerized Python service for visualization
• Production-Ready DevOps: Dockerized services, CI/CD pipelines, AWS deployment

---

🗂️ Table of Contents

• Description
• Tech Stack
• Software Requirements
• Architecture
• Project Structure
• How to Run
• Pipelines (CI/CD)
  • Environment Variables and Secrets
  • CI Pipelines
  • Deployment Pipeline
  • Tear-down Pipeline

---

📝 Description

More details about backend and fronend components are describe in:

• Backend README
• Frontend README
• 📺 Demo

---

🔨 Tech Stack

Backend

• Java 17
• Spring
• Gradle
• PostgreSQL
• MySQL
• Docker
• Docker Compose
• Swagger
• Python
• Matplotlib
• GPT API
• Anthropic API

Frontend

• React
• TypeScript
• Vite
• Material UI
• Nginx

Infrastructure & Others

• AWS
• CloudFormation
• Make
• Git
• GitHub Actions
• Bash

---

✅ Software Requirements

Backend

• Java 17
• Gradle (or use the included Gradle Wrapper)
• Docker
• Docker Compose

Frontend

• Node.js 18+
• Docker
• Docker Compose

Deployment

• AWS CLI
• Make
• Bash

---

🏛 Architecture

The system is composed of five main components:

• Backend – business logic and REST API
• Frontend – user interaction SPA
• Plot Service – isolated Python service for plots
• PostgreSQL – data persistence
• LLM(s) – external AI agents for natural language processing

Components:

Request flow diagrams:

---

🌲 Project Structure

.github/
├─ workflows/                             # GitHub workflows (pipelines)
backend/                                  # backend root
ci/
├─ scripts                                # scripts used in pipelines
customModel/                              # [Deprecated ]custom LLM api (separate project - gpt proxy)
frontend/                                 # frontend app root
infra/                                    # infrastructure
├─ local-stack/                           # docker compose stacks, files, ...
|  ├─ scripts                             # scripts
|  ├─ stack-date                          # persists data from docker containers
├─ prod-stack/                            # AWS stack
├─ scripts/                               # infra related scripts
README.md                                 # Documentation

---

🏃 How to Run

The application can be run in several ways, depending on your needs:

• Deploy to AWS (production-like)

  • Using GitHub Actions: see the Deployment Pipeline section
  • Manual deployment: infra/prod-stack/README.md

• Run locally with Docker Compose

  • Instructions: infra/local-stack/README.md

• Run components natively (development)

  • Backend: backend/README.md
  • Frontend: frontend/NoQL/README.md

---

🔁 Pipelines (CI/CD)

The project uses a multi-pipeline CI/CD setup consisting of:

• Component-specific CI pipelines for the backend, frontend, and plot service
• A deployment pipeline that provisions infrastructure and deploys all components
• A tear-down pipeline that removes the AWS infrastructure

🔐 Environment Variables and Secrets

The following secrets and variables must be configured in GitHub for the CI/CD pipelines.

Secrets

Name	Description
AWS_ACCESS_KEY_ID	AWS access key ID used by deployment and tear-down pipelines
AWS_SECRET_ACCESS_KEY	AWS secret access key used by deployment and tear-down pipelines
AWS_SSH_KEY_VALUE	Private SSH key used to access the AWS EC2 instance
BACKEND_DOT_ENV	Backend .env file content for the production stack, variables description: backend/README.md
FRONTEND_DOT_ENV	Frontend .env file content for the production stack, variables description: frontend/NoQL/README.md
DOCKERHUB_USERNAME	Docker Hub username
DOCKERHUB_TOKEN	Docker Hub access token
GH_ACCESS_TOKEN	GitHub access token with read & write repository access

Variables

Name	Description
AWS_SSH_KEY_NAME	Name of the EC2 SSH key pair how to get it: infra/prod-stack/README.md
NOQL_AWS_REGION	AWS region where the infrastructure is deployed

---

📦 CI Pipelines

CI pipelines are triggered automatically on pull requests targeting the main branch and can also be run manually.

Each component (backend, frontend, and plot service) has its own dedicated CI pipeline, allowing independent validation, testing, and builds.

Backend CI Pipeline

Backend CI Pipeline

▶️ GitHub trigger

Jobs

• Validate

  • Detects changes in the backend directory.
  • If changes are detected:
    • Verifies that the backend version has been incremented.
    • Runs backend linting checks.

• Test

  • Runs when:
    • Backend changes were detected in the Validate job, or
    • A pull request has been merged, or
    • The workflow is manually triggered.
  • Executes unit and integration tests with coverage reporting.
  • Coverage results are published in the job summary.
  • When triggered by a PR merge, updates backend_coverage.json in the coverage-badge branch.
    This file is used to generate the coverage badge displayed at the top of this file.

• Build

  • Builds the backend JAR artifact.
  • If the workflow is manually triggered with push_docker=true:
    • Builds and pushes the Docker image janbabak/noql-backend to Docker Hub.
    • The Docker image tag matches the backend version.

Plot Service CI Pipeline

Plot Service CI Pipeline

▶️ GitHub trigger

Jobs

• Validate

  • Detects changes in plotService.Dockerfile.
  • If changes are detected:
    • Verifies that the plot service version has been incremented.

• Build

  • Runs only when the workflow is manually triggered with push_docker=true.
  • Builds and pushes the Docker image janbabak/noql-plot-service to Docker Hub.
  • The Docker image tag matches the plot service version.

Frontend CI Pipeline

Frontend CI Pipeline

▶️ GitHub trigger

Jobs

• Validate

  • Detects changes in the frontend directory.
  • If changes are detected:
    • Verifies that the frontend version has been incremented.

• Build

  • Builds and packages the frontend application.
  • If the workflow is manually triggered with push_docker=true:
    • Builds and pushes the Docker image janbabak/noql-frontend to Docker Hub.
    • The Docker image tag matches the frontend version.

---

,🚀 Deployment Pipeline

Deployment Pipeline

▶️ GitHub trigger

The deployment pipeline deploys all system components (backend, frontend, and plot service) to AWS.

• The pipeline can be triggered only manually.
• It accepts a single input parameter: stack ID.

Jobs

• Deploy Infrastructure

  • Authenticates with AWS.
  • Deploys infrastructure defined in the CloudFormation template:
    • infra.yaml

• Deploy Application (Docker Compose)

  • Loads environment variables from:
    • .env.backend-prod (Needs to be created)
    • .env.frontend-prod (Needs to be created)
  • Starts Docker Compose, pulling Docker images from Docker Hub.
  • The frontend URL is printed in the output of the Print stack URL step.

---

🧹 Tear-down Pipeline

Tear-down Pipeline

▶️ GitHub trigger

The tear-down pipeline removes the AWS infrastructure.

• The pipeline can be triggered only manually.
• It accepts a single input parameter: stack ID.

Jobs

• Tear Down Infrastructure
  • Authenticates with AWS.
  • Deletes infrastructure defined in the CloudFormation template:
    • infra.yaml