docs: initial spec for the web-siteweb-site-spec

1 files changed, 326 insertions, 0 deletions

diff --git a/web-site/docs/SPEC.md b/web-site/docs/SPEC.md
new file mode 100644
index 0000000..59fdd2a
--- /dev/null
+++ b/web-site/docs/SPEC.md
@@ -0,0 +1,326 @@
+# zkVM Benchmarks Website Specification
+
+## Overview
+
+The zkVM Benchmarks website (`zk-wars.blocksense.network`) presents performance data for various Zero-Knowledge Virtual Machines (zkVMs). It enables technical users (developers, engineers, researchers) to quickly determine the best-performing toolchain and hardware configuration for specific cryptographic benchmarks.
+
+## Audience
+
+* Primary: Developers, engineers, researchers in ZK technology.
+* Secondary: Accessible to non-technical users interested in performance comparisons.
+
+## User Goals
+
+* Quickly identify the best-performing toolchain overall.
+* Evaluate toolchain performance for predefined and custom cryptographic benchmarks.
+* Determine optimal hardware configurations.
+
+## Key Features
+
+### Benchmark Data Display
+
+For each toolchain and benchmark program, the website displays:
+
+* Proof generation time
+* Proof generation memory usage
+* Proof verification time
+* Proof verification memory usage
+* Circuit compilation time
+* Circuit compilation memory usage
+* Proof size
+
+Results are presented per hardware configuration. Cold/hot executions are reported separately when available.
+
+### Data Visualization Components
+
+* **Ranked Horizontal Bar Chart**: Best-performing toolchains listed clearly with visual bar representations.
+* **Performance Metrics Table**: Numeric values with background-colored cells acting as proportional bars.
+* **Line Charts**: Visualize performance trends based on input variables.
+
+### Benchmark Definition
+
+#### Predefined Benchmarks
+
+Examples include:
+
+* Merkle Tree generation
+* Merkle proof verification
+* ECDSA signature verification
+
+#### Custom Comparison Builder
+
+* Users select primitives (e.g., signature verification, hashing) and specify execution counts.
+* UI is analogous to an online shopping cart:
+
+  * Users select primitives via an auto-complete search box or hierarchical browsing.
+  * Primitives organized in categories (e.g., Hashing, Signatures, Arithmetic Operations, Symmetric Encryption).
+
+### Combined Comparison Calculation
+
+* Metrics are calculated as a simple linear sum of individual primitives.
+* Results displayed as aggregated metrics, with detailed breakdown accessible via tap-to-expand interaction.
+* Detailed breakdown shows percentage contributions for each primitive.
+
+## UI/UX Considerations
+
+### Interaction Model
+
+* Tap-to-expand interactions for detailed breakdowns (desktop and mobile).
+* Dropdown menus for selecting comparison metrics (proof generation time, verification time, both).
+
+### Tables and Charts
+
+* Numeric tables use cell backgrounds to visually indicate performance proportionally.
+* Combined metric charts use color-coded bars to indicate different contributions (generation vs verification).
+
+### Hardware Configuration
+
+* Predefined hardware presets (limited set).
+* Detailed hardware specs shown upon selection.
+
+### Navigation Structure
+
+Hybrid approach:
+
+* SPA-like dynamic interactions with deep-linked, SEO-friendly URLs.
+* Descriptive path segments for benchmarks, toolchain-specific pages, hardware-specific pages.
+
+### URL Structure
+
+* Benchmark pages: `zk-wars.blocksense.network/benchmarks/<use-case>?hardware=<preset>&hash=<hash>&metric=<metric>`
+* Custom benchmarks: `zk-wars.blocksense.network/benchmarks/custom?data=<encoded-state>`
+* Toolchain pages: `zk-wars.blocksense.network/toolchains/<toolchain-name>?hardware=<preset>`
+* Hardware pages: `zk-wars.blocksense.network/hardware/<preset-name>`
+* Hardware comparisons: `zk-wars.blocksense.network/hardware/<preset-name>/vs/<second-preset-name>`
+
+### URL State Management
+
+* Dropdown selection changes use `replaceState` (no new history entry).
+* Navigating between pages or comparisons uses `pushState`.
+
+### Shared URLs
+
+* Users can share/bookmark benchmarks via a generated URL encoding the UI state.
+* Invalid URL parameters load defaults with subtle warning icons next to affected UI components.
+
+### Responsive Design
+
+* Fully responsive; all data/features available on both desktop and mobile.
+* Tables adapt by stacking columns/rows vertically on smaller screens.
+
+## Technical Implementation
+
+### Frontend
+
+* Next.js (React framework).
+* Server-side rendering (SSR) or Static Site Generation (SSG) for SEO and performance.
+* Client-side JSON fetching for dynamic data interactions.
+
+### Data Management
+
+Benchmark data stored as structured JSON files with the following schema:
+
+```json
+{
+  "benchmarking": [{
+    "name": "<benchmark-program-name>",
+    "compile": {
+      "timeStarted": "<ISO-timestamp>",
+      "runs": <number-of-runs>,
+      "totalDuration": <total-duration-seconds>,
+      "mean": <mean-duration-seconds>,
+      "deviation": <standard-deviation-seconds>,
+      "min": <min-duration-seconds>,
+      "max": <max-duration-seconds>,
+      "memory": <memory-usage-bytes>,
+      "size": <proof-or-circuit-size-in-bytes>
+    },
+    "prove": { <same-as-compile> },
+    "verify": { <same-as-compile> }
+  }],
+  "hardware": {
+    "cpu": [{"model": "<cpu-model>", "cores": <cores-count>, "speed": <speed-GHz>}],
+    "memory": {"model": "<memory-model>", "size": <size-bytes>, "speed": <speed-MHz>},
+    "hardwareAcceleration": [{"model": "<gpu-model>", "cores": <cores-count>, "speed": <speed-MHz>}],
+    "accelerated": false
+  }
+}
+```
+
+In the static build of the web-site. The client will have a pre-populated cache with all benchmark
+data available without making requests to the server.
+
+### Development Dependencies
+
+* Managed via Nix, provided as a Nix flake.
+
+### Hosting & Deployment
+
+* Hosted statically via Cloudflare.
+* Consider exporting the complete site as static HTML files for performance.
+
+## Performance and Accessibility Goals
+
+* Extremely fast initial page loads (target ≤1s).
+* Compliance with WCAG 2.1 AA standards.
+* Compatible with all major desktop/mobile browsers.
+
+## Branding & Visual Design
+
+* Matches existing BlockSense Network branding (see `https://blocksense.network`).
+* Domain: `zk-wars.blocksense.network`.
+
+## Scalability & Maintenance
+
+* Adding new hardware configurations or benchmarks is straightforward (structured JSON updates).
+* Initially manageable dataset size; potential infinite scrolling if datasets grow significantly.
+
+---
+
+# Detailed Page & Visual Design
+
+> **Branding Note** – All visual examples assume the BlockSense design language (see [https://blocksense.network](https://blocksense.network)). **Primary font is `Geist`** for all headings and body copy, backed by `sans-serif`. Example palette (confirm with latest brand assets): primary accent `#2F80ED`, secondary accent `#9747FF`, dark text `#1B1F23`, light text `#6B7280`, background `#F9FAFB`.
+
+## Shared Design Tokens
+
+| Token        | Usage                 | Example                                    |
+| ------------ | --------------------- | ------------------------------------------ |
+| Font family  | Primary text          | `Geist`, 1.2 rem base, 1.5 rem line‑height |
+| Radius‑md    | Card & button corners | `0.75 rem`                                 |
+| Elevation‑1  | Card shadow           | `0 2px 6px rgba(0,0,0,.06)`                |
+| Spacing‑unit | Base grid             | `0.5 rem`                                  |
+
+All pages use a **12‑column fluid grid** (`max‑width: 1440px`) with generous whitespace. Cards always span full width on ≤ 768 px screens and collapse to an 8‑column grid on tablets.
+
+---
+
+## 1. Landing / "Benchmarks Overview" Page
+
+**Purpose** – Entry point; lets users pick a predefined benchmark or jump to custom builder.
+
+### Layout
+
+1. **Hero bar** (full‑width, gradient accent): title *"Blocksense ZK Wars"*, subtitle "Your performance guide to the ZK world", CTA buttons:
+
+   * "Browse Standard Benchmarks" → scrolls to benchmark list
+   * "Build Custom Comparison" → `/benchmarks/custom`
+2. **Benchmark cards grid** – 8 predefined benchmarks in a `Card` component (image/emoji, title, short description). 3‑column desktop ▸ 1‑column mobile. A card named "More" that leads to `/benchmarks/`
+3. **Featured Rankings** – horizontal bar chart comparing top 5 toolchains for the default hardware preset & an aggregated set of benchmarks; embedded in a card with dropdowns (metric & hardware). Two charts will be displayed (best on CPU and best on GPU).
+4. **Footer** – links, GitHub repo badge, BlockSense branding.
+
+### Interactions
+
+* Benchmark card click → `/benchmarks/<slug>`
+* Dropdown changes update chart via `replaceState`.
+
+### Visual Notes
+
+* Cards use Elevation‑1 shadow; on hover desk‑top card lifts (`translate‑y‑1`, shadow‑lg). Mobile: subtle scale‑in.
+
+---
+
+## 2. Predefined Benchmark Detail Page `/benchmarks/<slug>`
+
+### Header
+
+* Breadcrumb: Home ▸ Benchmark ▸ *Merkle Proof Verification*
+* Title; dropdowns for **hardware** + **metric** (proof‑gen / verify / both).
+
+### Main Section
+
+| Column          | Content                                                                                                                                                                                                                      |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 8‑col (desktop) | **Performance Table** – toolchain in first column; proof times in second; cell background renders proportional bar (best = 100%). Third narrow column optional \:info: icon opens side drawer with raw JSON snippet for that row. |
+| 4‑col (desktop) | **Benchmark Info Card** – text summary, primitive list & counts, link "Re‑mix in Builder".                                                                                                                                    |
+
+### Expanded Row
+
+* Clicking a toolchain row accordion reveals a horizontal stacked bar (gen vs verify) + memory & proof size chips.
+
+### Mobile
+
+* Table transforms: each toolchain becomes a `Disclosure` card; metrics stack vertically; bars shrink to 100 % width of card.
+
+---
+
+## 3. Custom Comparison Builder `/benchmarks/custom`
+
+### Builder Panel (left on desktop, top on mobile)
+
+* **Primitive Search** (command‑palette style): type to filter, ↵ to add.
+* **Cart List** – each primitive row: name, qty stepper, subtotal metric preview badge.
+* **Hardware & Metric dropdowns** at bottom.
+* Sticky "Update Results" button triggers recalculation & URL `replaceState`.
+
+### Results Panel (right on desktop, below on mobile)
+
+* Aggregated result card: big number for total proof time; stacked bar showing breakdown (hover/tap segments → tooltip with % and ms).
+* Full results table identical to Benchmark Detail.
+
+### UX Notes
+
+* Builder uses slide‑in side sheet on ≤ 1024 px to maximise space.
+
+---
+
+## 4. Toolchain Detail Page `/toolchains/<name>`
+
+### Header
+
+* Avatar/logo, repository link, commit SHA, hardware dropdown.
+
+### Body
+
+1. **Benchmark List Table** – each benchmark row: benchmark icon, metric bar cell, comparison badge "+12 % vs best".
+2. **Filter chip bar** – filter by primitive category (hashing, signatures …).
+
+### Expansion
+
+* Row expand shows line chart of performance vs input size (if data). Chart built with Recharts; accessible via keyboard.
+
+---
+
+## 5. Hardware Detail Page `/hardware/<preset>`
+
+### Masthead Card
+
+* Hardware name, specs grid (CPU, RAM, optional GPU). Button "Compare with…" → opens modal to pick second preset (`pushState`).
+
+### Aggregated Rankings Section
+
+* Horizontal bar ranking of toolchain totals across all benchmarks.
+
+### Benchmark Tabs
+
+* Tab list of benchmark categories; contents: same table pattern.
+
+---
+
+## 6. Hardware Comparison Page `/hardware/<a>/vs/<b>`
+
+### Split‑view Layout
+
+* Sticky header showing A vs B specs side‑by‑side.
+* **Comparison Table**: rows = benchmark categories; two metric cells with background bars; difference column coloured subtle gray. Expandable accordions show per‑benchmark table (bars again) identical to row pattern. Multiple sections can be expanded concurrently.
+
+---
+
+## 7. Global Components
+
+* **Warning Icon** (invalid URL param): outline ⚠ icon next to dropdown; tooltip reveals issue.
+* **Share Button**: Icon button copies current canonical URL; toast “Link copied!”.
+* **Loading Skeletons**: shimmer rectangles mimic bar charts & table cells.
+
+---
+
+# Implementation Checklist (Visual)
+
+* [ ] Design tokens defined in Tailwind config.
+* [ ] Components scaffolded with shadcn/ui.
+* [ ] Charts implemented with Recharts + accessible labels.
+* [ ] Mobile breakpoints tested ≤ 360 px wide.
+* [ ] Colour contrast verified (WCAG 2.1 AA).
+
+---
+
+*End of visual design section.*