Architecture

Kaveon is one product with three pillars: Studio, the deterministic Data Language Model, and the Rust analytical Engine. Studio and the API provide the product surface; the Engine provides the distributed analytical path for lake-backed statements.

Status vocabulary: Current means it is in the request path people use. Alpha means the path is implemented and qualified, but its SQL and cloud-format coverage is still expanding. Target means approved architecture that is not yet implemented.

Kaveon platform architecture showing Studio, DLM, and Engine with current and target boundaries — The product boundary includes all three pillars. Solid connections are current; explicitly labeled target connections are roadmap architecture. Open the diagram for a full-size view.

Runtime boundaries

Component	Runtime	Maturity	Responsibility
Kaveon Studio	Next.js 15 · React 19	Current	Ask, SQL Lab, semantic datasets, charts, dashboards, and administration.
Platform API + DLM	FastAPI · Python	Current	Authenticated application services, deterministic question resolution, and the statements it hands the Engine.
Kaveon Engine	Rust · Arrow · Delta on ADLS Gen2	Alpha · qualified path	Durable catalog, optimized plans, distributed vectorized stages, Arrow IPC exchange, cube and sketch answers, and KaveonDB transactional records.

The request path

text

Browser
  │ same-origin Auth.js session
  ▼
Kaveon Studio (Vercel, AKS, or VM)
  │ /api/kaveon/* proxy · authenticated identity headers
  ▼
Platform API + DLM (FastAPI)
  │
  ├─ Kaveon Engine ──► Delta tables in ADLS Gen2
  │                    cube cells and sketches, or a distributed scan
  └─ KaveonDB (kaveon.product.*) ──► the platform's own records

The browser does not send trusted identity headers directly. Studio derives identity from the server-side session and signs the proxy request with KAVEON_PROXY_SECRET. FastAPI can also validate configured provider-issued bearer tokens for direct API clients. Each query runs against one selected source; cross-source federation is not implemented.

How a statement executes

text

Remote CLI or Engine HTTP client
  ▼
Coordinator: durable catalog → SQL → optimizer → stage graph
  ▼
Versioned fragments → worker tasks → Arrow IPC exchanges
  ▼
local Parquet / Delta splits → root Arrow result

The Engine executes distributed scans, partial and final aggregates, Sort/TopN, and repartitioned or broadcast joins, with retry, cancellation, exchange cleanup and bounded Sort/TopN spill. A cube-shaped aggregate skips execution entirely and is answered from precomputed cells and HyperLogLog sketches; the record says which lane a statement took. Delta on ADLS Gen2 is in production use. S3, Iceberg, aggregate and join spill, and engine HTTP authentication with TLS remain target work.

Internal exchange and catalog-mutation routes carry bearer tokens, but statement clients still have no end-user authentication, authorization or TLS of their own. In the reference deployment the Engine’s ports are bound to localhost and only the API reaches them. Keep it behind a trusted boundary.

Data and control planes

Control plane: datasets, charts, dashboards, roles, history, DLM artifacts and configuration, held as transactional rows in kaveon.product.* and written only through KaveonDB’s transaction boundary.
Lake data plane: Delta tables in ADLS Gen2, read by the Engine. This is where a query’s rows come from.
Registered SQL data plane: a Fabric SQL, Azure SQL, PostgreSQL, MySQL or StarRocks source a tenant registers. One source per query; cross-source federation is not implemented.

Architectural invariants

Identity is established at a verified trust boundary; raw client identity headers are never authoritative.
Optimization may read extra data but must never omit qualifying rows.
DLM acceleration complements Engine performance; it is not a substitute for a fast compute path.
Performance claims must name the data, hardware, version, cache state, concurrency, and date.
Current and target behaviour remain visibly distinct in product documentation.

Runtime boundaries

Component

Runtime

Maturity

Responsibility

Kaveon Studio

Next.js 15 · React 19

Current

Ask, SQL Lab, semantic datasets, charts, dashboards, and administration.

Platform API + DLM

FastAPI · Python

Current

Authenticated application services, deterministic question resolution, and the statements it hands the Engine.

Kaveon Engine

Rust · Arrow · Delta on ADLS Gen2

Alpha · qualified path

Durable catalog, optimized plans, distributed vectorized stages, Arrow IPC exchange, cube and sketch answers, and KaveonDB transactional records.

The request path

text

Browser
  │ same-origin Auth.js session
  ▼
Kaveon Studio (Vercel, AKS, or VM)
  │ /api/kaveon/* proxy · authenticated identity headers
  ▼
Platform API + DLM (FastAPI)
  │
  ├─ Kaveon Engine ──► Delta tables in ADLS Gen2
  │                    cube cells and sketches, or a distributed scan
  └─ KaveonDB (kaveon.product.*) ──► the platform's own records

How a statement executes

text

Remote CLI or Engine HTTP client
  ▼
Coordinator: durable catalog → SQL → optimizer → stage graph
  ▼
Versioned fragments → worker tasks → Arrow IPC exchanges
  ▼
local Parquet / Delta splits → root Arrow result

Data and control planes

Control plane: datasets, charts, dashboards, roles, history, DLM artifacts and configuration, held as transactional rows in kaveon.product.* and written only through KaveonDB’s transaction boundary.

Lake data plane: Delta tables in ADLS Gen2, read by the Engine. This is where a query’s rows come from.

Registered SQL data plane: a Fabric SQL, Azure SQL, PostgreSQL, MySQL or StarRocks source a tenant registers. One source per query; cross-source federation is not implemented.

Architectural invariants

Identity is established at a verified trust boundary; raw client identity headers are never authoritative.

Optimization may read extra data but must never omit qualifying rows.

DLM acceleration complements Engine performance; it is not a substitute for a fast compute path.

Performance claims must name the data, hardware, version, cache state, concurrency, and date.

Current and target behaviour remain visibly distinct in product documentation.