QueryCraft

QueryCraft is a Next.js learning studio for database practice. It combines SQL execution, relational algebra, tuple calculus, ER modeling, normalization, and synthetic dataset generation in one workspace.

The project is mostly client-side, with lightweight API routes for seed datasets and Test DB health/probe checks.

What Is Implemented

• SQL Sandbox with in-browser SQL execution, schema browser, query history, statement-level results, CSV export, and SQL import.
• Relational Algebra playground with parser, expression tree, step-by-step evaluation, and SQL translation.
• Tuple Relational Calculus workspace with TRC-to-SQL conversion and execution.
• ER Diagram Builder (React Flow) with preset diagrams, PNG export, and ER-to-relational conversion.
• Normalization wizard for FD input, candidate key detection, normal form detection, and decomposition steps.
• Table Generator with semantic hinting and SQL generation using Faker-based values.
• Learn page as a searchable SQL/DBMS reference (DDL, DML, joins, aggregates, set ops, TCL, DCL, routines, and theory sections).
• Device-local account system (local accounts, password check, account export/import).
• Per-account state isolation for all persisted workspaces.

Architecture Summary

• App framework: Next.js App Router + TypeScript.
• SQL runtime: sql.js (WASM SQLite) in the browser.
• State: Zustand stores, persisted to user-scoped localStorage keys.
• Styling: Tailwind CSS v4 + custom CSS variables and motion.
• Diagrams: @xyflow/react.
• Server routes:
  • GET /api/datasets reads JSON files from seed/datasets.
  • GET /api/tests/health reports Test DB bootstrap/config status.
  • GET /api/tests/health/probe runs a live SELECT 1 connectivity check against Test DB.

Routes

Public routes:

• /
• /login
• /register

Dashboard routes (client-side auth guard in layout):

• /dashboard
• /learn
• /sandbox
• /sandbox/history
• /algebra
• /algebra/history
• /tuple-calculus
• /tuple-calculus/history
• /er-builder
• /normalizer
• /generator
• /settings

API routes:

• /api/datasets (GET)
• /api/tests/health (GET)
• /api/tests/health/probe (GET)

Getting Started

Prerequisites:

• Node.js 22.13+ (22.x), 24.x, or 26+
• npm

Install and run:

npm install
npm run dev

Open http://localhost:3000.

Environment variables:

• None are required for currently shipped browser-first features.
• TEST_DB_URL is optional and used for the upcoming Test module backend foundation.
• GROQ_API_KEY enables the Normalizer Studio "Analyze with AI" workflow.
• GROQ_MODEL is optional (defaults to llama-3.1-8b-instant with server-side fallback models).

Use a Free Online Postgres (Recommended: Neon)

You can move Test DB from local Postgres to a free hosted Postgres in a few minutes.

1. Create a free Neon project and database (for example querycraft_test).
2. Copy the connection string from Neon dashboard.
3. Set TEST_DB_URL in .env.local:

TEST_DB_URL=postgresql://<user>:<password>@<host>/<database>?sslmode=require

4. Apply migrations to the online DB:

npm run test-db:migrate:status
npm run test-db:migrate

5. Verify connectivity:

• GET /api/tests/health should report status: "ready"
• GET /api/tests/health/probe should report status: "ok"

Scripts

• npm run dev: start local development server.
• npm run build: create production build.
• npm run start: run production server.
• npm run lint: run ESLint.
• npm run typecheck: check TypeScript without emitting files.
• npm run format: run Prettier over repository.
• npm run test: run Vitest test suite once.
• npm run test:watch: run Vitest in watch mode.
• npm run sync:sql-wasm: copy the installed sql.js WASM runtime to public/ (also runs after installation).
• npm run test-db:migrate:status: show Test DB migration status.
• npm run test-db:migrate: apply pending Test DB migrations.
• npm run test-db:migrate:down: roll back the latest Test DB migration.
• npm run test-db:migrate:down:all: roll back all applied Test DB migrations.

Seed Datasets

Seed files are stored in seed/datasets and loaded through /api/datasets.

Current bundled datasets:

• banking.json
• credentia.json
• university.json

Data and Auth Model

• Accounts are device-local. Passwords are SHA-256 hashed in-browser.
• Active session user is stored in sessionStorage.
• Workspace data is persisted in localStorage with user-scoped keys.
• Query execution happens in-browser via sql.js, not against an external database.

This design is intended for learning workflows, not production authentication.

Tests

TypeScript stays on 6.0.x because the ESLint TypeScript parser requires a version below 6.1. Node type definitions track the minimum supported Node major (22). ESLint stays on the latest 9.x release because Next's React, accessibility, and import plugins do not yet support ESLint 10. npm reports an upstream support deprecation for ESLint 9; upgrading it currently creates invalid peer dependencies.

The unit suite validates:

• SQL executor behavior (DDL/DML, DCL, TCL, procedures, triggers, cursors, MySQL compatibility, and multi-database behavior).
• Statement splitting and PL/SQL runtime helpers.
• Data generator hint detection/output.
• Session persistence utility behavior.

Run all tests:

npm run test

Documentation

• docs/API.md
• docs/SECURITY.md
• docs/CONTRIBUTING.md
• ROADMAP.md