server architecture

Signed-off-by: Connor Tsui <connor.tsui20@gmail.com>

Author: connortsui20

benchmarks-website/README.md

@@ -36,12 +36,13 @@ local DB file. Five fact tables (`query_measurements`, `compression_times`,
 `compression_sizes`, `random_access_times`, `vector_search_runs`) plus a
 `commits` dim table — see [`server/src/schema.rs`](server/src/schema.rs) for
 the column contracts. Three HTML routes (`/`, `/chart/{slug}`,
-`/group/{slug}`) and four JSON routes (`GET /api/groups`,
-`GET /api/chart/{slug}`, `GET /api/group/{slug}`, `GET /health`), plus a
-bearer-gated `POST /api/ingest`. Charts render inline on the landing page via
-SSR + lazy hydration; visual downsampling (LTTB at most
-`MAX_VISIBLE_POINTS = 500`) is client-side in
-[`server/static/chart-init.js`](server/static/chart-init.js).
+`/group/{slug}`) and four stable JSON routes (`GET /api/groups`,
+`GET /api/chart/{slug}`, `GET /api/group/{slug}`, `GET /health`), plus
+versioned group shard artifacts and bearer-gated `POST /api/ingest`. The hot
+website path serves precomputed, precompressed latest-100 artifacts from an
+in-memory read model; pages render chart shells and hydrate groups via shard
+artifacts, while full history warms in the background. See
+[`server/ARCHITECTURE.md`](server/ARCHITECTURE.md).
 
 For the per-module crate map and the request-flow walkthrough, see the
 `//!` doc on [`server/src/lib.rs`](server/src/lib.rs). The producer side of

benchmarks-website/server/ARCHITECTURE.md

@@ -0,0 +1,82 @@
+<!--
+SPDX-License-Identifier: Apache-2.0
+SPDX-FileCopyrightText: Copyright the Vortex contributors
+-->
+
+# Benchmark Server Architecture
+
+The benchmark website is optimized around a materialized latest-100 read path.
+DuckDB is the source of truth, but normal landing-page and group-open
+hydration does not run SQL, serialize JSON, or compress responses per request.
+
+## Hot Read Path
+
+On startup the server builds a `ReadGeneration` from one DuckDB snapshot. That
+generation contains precomputed JSON artifacts for:
+
+- `/api/groups`
+- default `/api/chart/{slug}` latest-100 payloads
+- default `/api/group/{slug}` latest-100 compatibility payloads
+- versioned group shard payloads under
+  `/api/artifacts/{generation}/groups/{group_slug}/shards/{index}`
+
+Each artifact is stored in memory as identity, gzip, and brotli bytes. Request
+handlers negotiate `Accept-Encoding` and serve those bytes directly with
+`ETag`, `Vary: Accept-Encoding`, `Content-Length`, and cache headers.
+
+## Page Hydration
+
+The landing page and `/group/{slug}` render group metadata plus chart shells,
+not inline chart payloads. Each group carries the active read generation, shard
+count, and shard URL prefix. `chart-init.js` fetches shard 0 on intent or group
+open so charts paint quickly, then queues the remaining latest-100 shards with
+bounded per-tab concurrency.
+
+Latest-100 chart payloads include additive `history` metadata:
+
+- `total_commits`: full x-axis length for the chart
+- `start_index`: where this payload starts in the full x-axis
+- `loaded_commits`: number of loaded commits
+- `complete`: whether the payload covers the full x-axis
+
+The client normalizes incomplete latest-100 payloads onto the full virtual
+x-axis. Older unloaded commits are represented by blank labels and null series
+values, so the range strip, zoom limits, and slider bounds behave as if the
+whole history is present without fabricating data.
+
+## Full-History Warmup
+
+Opening a group queues `/api/chart/{slug}?n=all` for that group's charts in a
+separate low-concurrency priority queue. A later-opened group gets higher
+priority than queued work for older groups. If the user pans or zooms into an
+unloaded virtual range before warmup finishes, that chart's queued full-history
+request is promoted. In-flight requests are not cancelled.
+
+When the full payload arrives, the client replaces the virtual latest-100
+payload in place and preserves the current x-range when possible.
+
+## Fallback Paths
+
+`?n=all` and non-default `?n=` windows still use the DB-backed fallback path.
+Those reads go through `QueryCache` single-flight entries and the DB read
+semaphore so cold or unusual requests do not stampede DuckDB. Ingest writes do
+not consume read permits.
+
+## Ingest And Rebuild
+
+Successful ingest invalidates `QueryCache` and schedules a read-model rebuild.
+The active generation remains live while rebuilding. Repeated rebuild requests
+coalesce, and a failed rebuild keeps serving the old generation. The server
+keeps the active generation plus the most recent previous generation so already
+loaded pages can continue resolving immutable shard URLs across a swap.
+
+## Main Files
+
+- `src/read_model.rs`: materialized generation and encoded artifact serving
+- `src/api/mod.rs`: API routing between materialized artifacts and fallbacks
+- `src/api/charts.rs`: chart DTO construction and `history` metadata
+- `src/html/mod.rs`, `src/html/landing.rs`: shell/shard HTML rendering
+- `static/chart-init.js`: virtual-axis normalization, shard hydration, and
+  full-history priority warmup
+- `src/query_cache.rs`: single-flight fallback cache
+- `src/db.rs`: DuckDB connection cloning and read backpressure

benchmarks-website/server/src/lib.rs

@@ -9,22 +9,31 @@
 //! plus every HTML page. All static assets (Chart.js + the zoom plugin +
 //! `chart-init.js` + `style.css` + the two logos) are baked into the
 //! binary via `include_bytes!` so a deploy is one binary plus a database
-//! file. A `tower-http::CompressionLayer` wraps every response — the
-//! landing page HTML alone is several hundred KB uncompressed, so this is
-//! the single biggest cold-load win.
+//! file.
+//!
+//! The hot website path is a materialized latest-100 read model. DuckDB
+//! remains the source of truth, but default group/chart hydration is served
+//! from precomputed, precompressed in-memory artifacts. See
+//! `benchmarks-website/server/ARCHITECTURE.md` for the higher-level model.
 //!
 //! ## Routes
 //!
-//! - `GET /` — landing page, every group rendered as a collapsed
-//!   `<details>`. The first group's chart payloads are inlined into the
-//!   HTML; the rest are shells fetched on first toggle.
-//! - `GET /chart/{slug}` — single-chart permalink.
-//! - `GET /group/{slug}` — every chart in one group on a single page.
+//! - `GET /` — landing page, every group rendered as chart shells plus
+//!   versioned shard metadata. Groups hydrate on intent/open.
+//! - `GET /chart/{slug}` — single-chart permalink. Defaults to the
+//!   materialized latest-100 window; `?n=all` uses the DB fallback.
+//! - `GET /group/{slug}` — every chart shell in one group on a single page,
+//!   opened by default and hydrated through the shard path.
 //! - `GET /static/...` — the bundled JS / CSS / logos.
 //! - `GET /api/groups` — flat list of every group with chart-link metadata.
-//! - `GET /api/chart/{slug}` — one chart's payload (`commits`, `series`,
-//!   `unit_kind`, ...).
-//! - `GET /api/group/{slug}` — every chart in one group, payload-inlined.
+//!   Defaults to a materialized artifact.
+//! - `GET /api/chart/{slug}` — one chart's payload (`history`, `commits`,
+//!   `series`, `unit_kind`, ...). Defaults to a materialized latest-100
+//!   artifact; `?n=all` and non-default windows use the DB fallback.
+//! - `GET /api/group/{slug}` — every chart in one group. Defaults to a
+//!   materialized latest-100 compatibility artifact.
+//! - `GET /api/artifacts/{generation}/groups/{group_slug}/shards/{index}` —
+//!   immutable versioned latest-100 group shard artifact for page hydration.
 //! - `GET /health` — liveness probe + per-table row counts.
 //! - `POST /api/ingest` — bearer-gated ingest. See [`ingest`] for the HTTP
 //!   matrix and [`auth`] for the bearer middleware.
@@ -33,16 +42,18 @@
 //!
 //! | Module        | Role                                                                                        |
 //! |---------------|---------------------------------------------------------------------------------------------|
-//! | [`app`]       | [`app::AppState`] (DB handle + bearer + path) and the Axum router composition.              |
+//! | [`app`]       | [`app::AppState`] (DB handle + bearer + read store + paths) and the Axum router composition. |
 //! | [`auth`]      | Bearer-token middleware for `/api/ingest`.                                                  |
-//! | [`db`]        | [`db::DbHandle`] task-local connection cloning + the per-fact-table `measurement_id_*` hash functions. |
+//! | [`db`]        | [`db::DbHandle`] task-local connection cloning + read backpressure + hash helpers.          |
 //! | [`schema`]    | DuckDB DDL ([`schema::SCHEMA_DDL`]) and the wire schema version.                            |
 //! | [`records`]   | Wire shapes for `POST /api/ingest`.                                                         |
-//! | [`ingest`]    | `POST /api/ingest` handler — envelope validation, transaction, upsert dispatch.             |
+//! | [`ingest`]    | `POST /api/ingest` handler, cache invalidation, and read-model rebuild scheduling.          |
 //! | [`error`]     | [`error::IngestError`] and [`error::ApiError`] with their HTTP-status mapping.              |
 //! | [`slug`]      | [`slug::ChartKey`] / [`slug::GroupKey`] enums + base64url round-trip.                       |
 //! | [`api`]       | Read API. `mod.rs` mounts the handlers; submodules are listed on its module doc.            |
 //! | [`html`]      | HTML pages — `mod.rs` mounts the routes; submodules render the body.                        |
+//! | [`read_model`]| Materialized latest-100 generations and encoded artifact serving.                           |
+//! | [`query_cache`]| Single-flight cache for non-materialized fallback reads.                                    |
 //!
 //! ## Request flow
 //!
@@ -51,16 +62,16 @@
 //!    routes skip auth.
 //! 3. The handler parses body / path / query into typed inputs (e.g.
 //!    [`slug::ChartKey::from_slug`]).
-//! 4. The handler hands a closure to [`db::run_blocking`], which clones a
-//!    task-local DuckDB connection and runs the synchronous call on
-//!    `tokio::task::spawn_blocking` so the runtime stays free.
-//! 5. The closure returns `Result<T, anyhow::Error>`. Errors are mapped
-//!    into [`error::IngestError`] / [`error::ApiError`] with the right
-//!    HTTP status.
-//! 6. The response is rendered (JSON via [`axum::Json`], HTML via the
-//!    `maud` router in [`html`]).
-//! 7. Every response passes through [`tower_http::compression::CompressionLayer`]
-//!    on the way out.
+//! 4. For default latest-100 API reads, the handler serves an encoded
+//!    [`read_model`] artifact directly from memory.
+//! 5. For ingest, `?n=all`, and non-default windows, the handler hands a
+//!    closure to [`db::run_blocking`], which clones a task-local DuckDB
+//!    connection and runs synchronous work on `tokio::task::spawn_blocking`.
+//! 6. Fallback chart/group reads go through [`query_cache`] so concurrent
+//!    identical misses share one compute.
+//! 7. Errors are mapped into [`error::IngestError`] / [`error::ApiError`]
+//!    with the right HTTP status. HTML responses are rendered via `maud`;
+//!    hot JSON artifacts are returned as already encoded bytes.
 
 pub mod api;
 pub mod app;