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. |
| Observability | Prometheus metrics, Grafana dashboard, QueryFlux Studio, and the Admin REST API. |
| Adding engine support | Checklist for new backend engines (Rust adapters), Studio (lib/studio-engines/ manifest + catalog slots), and frontend wire protocols (e.g. Postgres wire). |
| 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.