QueryFlow

See what your SQL actually does.

QueryFlow is a browser-based SQL visualization tool that turns a SQL query into a visual execution flow. Instead of only showing the final rows, it helps you follow the tables, operations, row changes, and final projection that lead to the result.

Why QueryFlow?

SQL tells you what to ask for. QueryFlow focuses on how the result is produced.

A query such as:

SELECT users.name, orders.total
FROM users
JOIN orders ON users.id = orders.user_id
WHERE orders.total > 100;

becomes a visual sequence:

┌────────┐      ┌───────┐      ┌───────┐      ┌────────┐      ┌────────┐
│  FROM  │ ───▶ │ JOIN  │ ───▶ │ WHERE │ ───▶ │ SELECT │ ───▶ │ RESULT │
└────────┘      └───────┘      └───────┘      └────────┘      └────────┘
     │               │              │               │               │
     ▼               ▼              ▼               ▼               ▼
 source rows     matched rows   removed rows    new shape      final rows

The goal is to make the execution of a query easier to see, inspect, and understand.

✨ Current experience

SQL editor

• Syntax-aware SQL presentation
• Preloaded example queries
• Run and Step controls
• Ctrl/Cmd + Enter execution shortcut
• Query preset selector
• Reset support

🧩 Database schema

• Built-in USERS and ORDERS tables
• Visible column structure
• users.id → orders.user_id relationship
• Active-table highlighting during execution
• JOIN relationship emphasis

⚙️ Query execution rail

The central QueryFlow experience is a horizontal execution rail:

FROM → JOIN → WHERE → SELECT → RESULT

Each stage represents a meaningful operation and updates the surrounding evidence shown in the interface.

🔎 Row-level evidence

At filtering stages, QueryFlow makes the effect of the condition visible.

For example:

id   name      age
────────────────────
1    Ahmed     17    excluded
2    Sara      22    included
3    Omar      25    included
4    Ali       16    excluded
5    Mona      31    included

The interface can show exactly which records continue through the pipeline and which records are removed.

📝 Explanations

The explanation panel follows the selected pipeline stage and translates the operation into plain language.

📊 Final results

The final result is presented as the conclusion of the execution flow, with the relationship between the intermediate states and final projection kept visible.

🛠️ Tech stack

Area	Technology
UI	React
Language	TypeScript
Build tool	Vite
Styling	Tailwind CSS
Testing	Vitest + Testing Library
Icons	lucide-react
SQL runtime	Browser-side architecture, prepared for SQLite/WASM
Rendering	React + CSS/SVG
Backend	None

QueryFlow is designed as a browser-only application for the MVP. The execution layer is isolated behind an adapter so a real SQLite/WASM implementation can be introduced without coupling SQL APIs to the UI.

🏗️ Architecture

The project keeps SQL execution, visualization, and presentation separate:

┌──────────────────────────────┐
│         SQL Editor           │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│        SQL Parser            │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│   Execution / Adapter Layer  │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│ Visualization Step Generator │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│       QueryFlow UI           │
└──────────────────────────────┘

Core data contract

Visualization is represented with structured step data rather than being hard-coded into individual components.

A step can contain:

type VisualizationStep = {
  id: string;
  operation: string;
  label: string;
  description: string;
  detail: string;
  condition?: string;
  inputRows: unknown[];
  outputRows: unknown[];
  removedRows: unknown[];
  columns: string[];
  relatedTables?: string[];
};

This keeps the UI focused on displaying execution evidence while the SQL layer remains replaceable.

📁 Project structure

queryflow/
├── src/
│   ├── components/
│   │   ├── AppHeader.tsx
│   │   ├── ExplanationPanel.tsx
│   │   ├── PipelineRail.tsx
│   │   ├── PipelineStage.tsx
│   │   ├── ResultsTable.tsx
│   │   ├── RowMatrix.tsx
│   │   ├── SchemaGraph.tsx
│   │   └── SqlEditor.tsx
│   │
│   ├── data/
│   │   └── demoQuery.ts
│   │
│   ├── hooks/
│   │   └── usePipeline.ts
│   │
│   ├── lib/
│   │   └── demoExecutionAdapter.ts
│   │
│   ├── types/
│   │   └── query.ts
│   │
│   ├── App.tsx
│   └── index.css
│
├── package.json
├── vite.config.ts
└── README.md

🚀 Getting started

Prerequisites

• Node.js 18+
• npm

Install

npm install

Start the development server

npm run dev

Vite will start the local development server and print the local URL in your terminal.

Run tests

npm test -- --run

Type-check

npx tsc -b

Lint

npm run lint

Production build

npm run build

🧪 Validation

The current foundation has been validated with:

• 20 automated tests
• TypeScript compilation
• ESLint
• Production build
• Browser-based viewport checks
• Desktop, tablet, and mobile render verification
• Pipeline interaction checks
• WHERE row exclusion checks
• Run-to-result behavior
• Step navigation and restart behavior

The UI has also been exercised at:

• 1440px desktop
• 900px tablet
• 390px mobile

🗃️ Built-in demo database

QueryFlow ships with a small relational dataset so the experience works immediately.

users

id	name	email	age
1	Ahmed	ahmed@example.com	17
2	Sara	sara@example.com	22
3	Omar	omar@example.com	25
4	Ali	ali@example.com	16
5	Mona	mona@example.com	31

orders

id	user_id	product	total
1	2	Keyboard	150
2	3	Mouse	80
3	2	Monitor	500
4	5	Laptop	1200

The relationship is:

users.id ─────────────▶ orders.user_id

📌 MVP SQL support

The initial product is intentionally focused on a small, highly visual SQL surface.

Supported

• SELECT
• FROM
• WHERE
• JOIN
• ON

Planned

• ORDER BY
• LIMIT
• Multiple JOINs
• GROUP BY
• HAVING
• Aggregate functions such as COUNT, SUM, and AVG
• Subqueries
• CTEs
• UNION
• Additional JOIN types

The project prioritizes clear visualization of supported operations over broad SQL coverage.

🎨 Design principles

QueryFlow follows a few simple UI rules:

Show evidence. Every important execution stage should have visible data behind it.

Keep the SQL central. The UI exists to explain the query, not compete with it.

Use motion for meaning. Animation should communicate state changes, not decorate the screen.

Stay dense but readable. Query tools benefit from information density when hierarchy is clear.

Prefer restraint. Borders, color, radius, and shadows should support the data flow rather than become the visual focus.

🤝 Contributing

Contributions are welcome as the project evolves.

Before opening a pull request:

npm test -- --run
npm run lint
npx tsc -b
npm run build

For UI changes, also verify the affected states at desktop and mobile widths.

📄 License

This project is licensed under the MIT License.

---

Built with React, TypeScript, and a lot of SQL.