QueryFlux architecture documentation

This section describes how QueryFlux is put together: why it exists, how SQL is translated, and how traffic is routed to cluster groups and individual clusters.

Document	What it covers
Motivation and goals	Problem statement, goals, and how QueryFlux fits multi-engine estates.
System map	End-to-end query lifecycle, major crates, and component status (high level).
Query translation	Dialect detection, sqlglot integration, when translation runs, and schema-aware mode.
Routing and clusters	Router chain, routingFallback, cluster groups, load-balancing strategies, and queueing.
Cluster variants, health & reconcile	Multi-warehouse expansion, ADBC introspection, custom health/reconcile SQL, distributed capacity.
Query tags	Attaching metadata to queries for routing, observability, and backend forwarding.
Query parameters	Typed positional bindings — how ? params flow from frontend to native engine APIs.
Observability	Prometheus metrics, Grafana dashboard, QueryFlux Studio, and the Admin REST API.
Guardrails	SQL-shape safety checks (read-only, LIMIT, Python guards).
Access control	Table/column allow-deny, row filters, masks, and customer API use case via OPA.
Frontends	Protocol listeners — Trino HTTP, PostgreSQL wire, MySQL wire, Flight SQL, and more. Shared dispatch, session model, and per-protocol details.
Extending QueryFlux	Backend (Rust + Studio) and Frontend (new protocols).
Auth / authz design	Authentication and authorization design notes.

Start with Motivation and goals if you are new to the project; use System map as the single-page map of the system.

The canonical Markdown sources live under docs/ in the repository.