# webkit/speedometer architecture

> Architecture diagram of the GitHub repository webkit/speedometer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/webkit/speedometer
- Repository: https://github.com/webkit/speedometer

## Overview

##### Project Type and Purpose
- Speedometer is an open-source browser benchmark tool (not a full-stack app).
- It delivers static web assets (HTML/CSS/JS) that, when loaded in a browser, run a suite of simulated user interactions against small sample applications (“workloads”) and measure timing.
- It also provides Node.js-based automation scripts for running headless tests and CI integration (GitHub Actions).

##### High-Level File Structure Analysis
- Top level: build/config (babel.config.json, .eslintrc, package.json, netlify.toml), docs (README.md, Development.md, Testing.md), static pages (index.html, about.html, instructions.html).
- experimental/: proof-of-concept workloads (e.g. todomvc-localstorage).
- resources/: the heart of the benchmark –
– benchmark harness: benchmark-runner.mjs, suite-runner.mjs, shared modules (resources/shared/*.mjs).
– workload definitions/apps: charts/, editors/, newssite/, perf.webkit.org/, react-stockcharts/, todomvc/… plus utility scripts.
– data and helper modules (resources/main.mjs, resources/metric*.mjs, resources/translations.mjs).
- tests/: Node.js scripts to run unit- and end-to-end tests (run-unittests.mjs, run-end2end.mjs, server.mjs).
- package.json scripts and .github/workflows/test.yml define CI/CD pipelines.

##### README Insights
- Speedometer measures real-world-style end-to-end journeys (each “workload” is a small demo app with UI interactions).
- It measures both sync and async JS time per step.
- Final score is the inverse of the geometric mean of test durations.

##### Components
a. Main Components
1. Static Asset Host (e.g., Netlify, or any HTTP server)
2. Browser Environment (Chrome, Firefox, etc.)
3. Benchmark Harness (JavaScript modules in resources/, e.g. benchmark-runner.mjs, suite-runner.mjs)
4. Workload Modules (subfolders under resources/, each implementing a test scenario)
5. Measurement Engine (sync/async timing collectors, score calculator)
6. Reporting UI (HTML/CSS/JS pages that present timing charts and final score)
7. Node.js Automation (tests/ scripts + headless browser launch)
8. CI Pipeline (GitHub Actions invoking Node.js automation and reporting pass/fail)

b. Relationships and Interactions
- Browser <– HTTP GET –– Static Asset Host
- Browser → loads index.html → bootstraps Benchmark Harness
- Harness → dynamically loads each Workload Module (via ES modules or script tags)
- Workload Module ↔ Measurement Engine (harness invokes workload steps; measurement collects timestamps)
- Measurement Engine → aggregates metrics → Score Calculator
- Score Calculator → Reporting UI → renders graphs and numeric score
- Node.js Automation → spins up headless browser (Puppeteer or playwright) → loads benchmark → collects result → outputs JSON/CI logs
- CI Pipeline → triggers Node.js Automation → posts results/status

c. Architectural Patterns and Principles
- Plugin-style workload architecture: each test lives in its own folder under resources/ and adheres to a common API.
- Modular ES-module design: shared modules under resources/shared for common logic.
- Separation of concerns:
– Static hosting/build layer (package.json, netlify.toml)
– Runtime harness & workloads (resources/)
– Automation & CI (tests/, .github/)
- Measurement decoupled from UI: timing collectors feed a pure data output, then UI layers render graphs.

d. Key Technologies and Frameworks
- Core: HTML5, CSS, ES Modules, plain JavaScript
- Build tools: Babel, Rollup/Vite (in some workloads), npm scripts
- Automation: Node.js, MJS modules, headless browser tooling
- CI: GitHub Actions (test.yml), Netlify for static deploys

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Static Host Layer
    subgraph "Static Asset Host"
        direction TB
        Config["netlify.toml"]:::fs
        HomePage["index.html"]:::fs
        AboutPage["about.html"]:::fs
        Instructions["instructions.html"]:::fs
    end

    %% Browser Runtime
    Browser["Browser Environment\n(Chrome/Firefox)"]:::browser

    %% Benchmark Harness
    subgraph "Benchmark Harness" 
        direction TB
        Runner["benchmark-runner.mjs"]:::fs
        Suite["suite-runner.mjs"]:::fs
        MainMod["main.mjs"]:::fs
        SharedBM["shared/benchmark.mjs"]:::fs
        SharedHP["shared/helpers.mjs"]:::fs
        SharedPM["shared/params.mjs"]:::fs
        SharedTR["shared/test-runner.mjs"]:::fs
        SharedTI["shared/test-invoker.mjs"]:::fs
    end

    %% Workload Modules
    subgraph "Workload Modules" 
        direction TB
        Charts["resources/charts/"]:::workload
        Editors["resources/editors/"]:::workload
        NewsSite["resources/newssite/"]:::workload
        PerfWebkit["resources/perf.webkit.org/"]:::workload
        StockCharts["resources/react-stockcharts/"]:::workload
        TodoMVC["resources/todomvc/"]:::workload
        BigDOM["resources/big-dom-generator/"]:::workload
        TodoMVCCSS["resources/todomvc-css/"]:::workload
        VanillaEx["resources/vanilla-examples/"]:::workload
        ExpTodoMVC["experimental/todomvc-localstorage/"]:::workload
    end

    %% Measurement Engine
    subgraph "Measurement Engine"
        direction TB
        MetricCore["metric.mjs"]:::fs
        MetricUI["metric-ui.mjs"]:::fs
        Stats["statistics.mjs"]:::fs
        Translations["translations.mjs"]:::fs
    end

    %% Reporting UI
    subgraph "Reporting UI"
        direction TB
        DevReport["resources/charts/developer.html"]:::fs
        EdReport["resources/editors/index.html"]:::fs
        Style["resources/main.css"]:::fs
        UIHome["index.html"]:::fs
    end

    %% Node.js Automation
    subgraph "Node.js Automation" 
        direction TB
        End2End["tests/run-end2end.mjs"]:::automation
        UnitTests["tests/run-unittests.mjs"]:::automation
        Server["tests/server.mjs"]:::automation
        HelperTest["tests/helper.mjs"]:::automation
        UT_Bench["tests/unittests/benchmark-runner.mjs"]:::automation
        UT_Params["tests/unittests/params.mjs"]:::automation
    end

    %% CI Pipeline
    subgraph "CI Pipeline"
        direction TB
        Workflow[".github/workflows/test.yml"]:::ci
        Scripts["package.json scripts"]:::ci
    end

    %% Connections
    Config -->|HTTP GET| Browser
    HomePage -->|loads| Browser
    AboutPage -->|loads| Browser
    Instructions -->|loads| Browser

    Browser -->|bootstraps| Runner
    Runner -->|imports| Suite
    Suite -->|uses| MainMod

    Runner -->|dynamically loads| Charts
    Runner -->|dynamically loads| Editors
    Runner -->|dynamically loads| NewsSite
    Runner -->|dynamically loads| PerfWebkit
    Runner -->|dynamically loads| StockCharts
    Runner -->|dynamically loads| TodoMVC
    Runner -->|dynamically loads| BigDOM
    Runner -->|dynamically loads| TodoMVCCSS
    Runner -->|dynamically loads| VanillaEx
    Runner -->|dynamically loads| ExpTodoMVC

    Charts <-->|executes workloads| MetricCore
    Editors <-->|executes workloads| MetricCore
    NewsSite <-->|executes workloads| MetricCore
    PerfWebkit <-->|executes workloads| MetricCore
    StockCharts <-->|executes workloads| MetricCore
    TodoMVC <-->|executes workloads| MetricCore
    BigDOM <-->|executes workloads| MetricCore
    TodoMVCCSS <-->|executes workloads| MetricCore
    VanillaEx <-->|executes workloads| MetricCore
    ExpTodoMVC <-->|executes workloads| MetricCore

    MetricCore -->|collects data| MetricUI
    MetricCore -->|calculates stats| Stats
    MetricCore -->|loads translations| Translations

    Stats -->|aggregates metrics| DevReport
    Stats -->|aggregates metrics| EdReport
    Style -->|styles| DevReport
    Style -->|styles| EdReport
    UIHome -->|bootstraps UI| DevReport

    Workflow -->|triggers| End2End
    Workflow -->|triggers| UnitTests
    Scripts -->|invoke| End2End
    Scripts -->|invoke| UnitTests

    End2End -->|launches headless| Browser
    End2End -->|runs| Runner
    UnitTests -->|tests modules| Runner

    End2End -->|outputs| Server
    Server -->|serves| UIHome

    %% Click Events
    click Config "https://github.com/webkit/speedometer/blob/main/netlify.toml"
    click HomePage "https://github.com/webkit/speedometer/blob/main/index.html"
    click AboutPage "https://github.com/webkit/speedometer/blob/main/about.html"
    click Instructions "https://github.com/webkit/speedometer/blob/main/instructions.html"

    click Runner "https://github.com/webkit/speedometer/blob/main/resources/benchmark-runner.mjs"
    click Suite "https://github.com/webkit/speedometer/blob/main/resources/suite-runner.mjs"
    click MainMod "https://github.com/webkit/speedometer/blob/main/resources/main.mjs"
    click SharedBM "https://github.com/webkit/speedometer/blob/main/resources/shared/benchmark.mjs"
    click SharedHP "https://github.com/webkit/speedometer/blob/main/resources/shared/helpers.mjs"
    click SharedPM "https://github.com/webkit/speedometer/blob/main/resources/shared/params.mjs"
    click SharedTR "https://github.com/webkit/speedometer/blob/main/resources/shared/test-runner.mjs"
    click SharedTI "https://github.com/webkit/speedometer/blob/main/resources/shared/test-invoker.mjs"

    click Charts "https://github.com/webkit/speedometer/tree/main/resources/charts/"
    click Editors "https://github.com/webkit/speedometer/tree/main/resources/editors/"
    click NewsSite "https://github.com/webkit/speedometer/tree/main/resources/newssite/"
    click PerfWebkit "https://github.com/webkit/speedometer/tree/main/resources/perf.webkit.org/"
    click StockCharts "https://github.com/webkit/speedometer/tree/main/resources/react-stockcharts/"
    click TodoMVC "https://github.com/webkit/speedometer/tree/main/resources/todomvc/"
    click BigDOM "https://github.com/webkit/speedometer/tree/main/resources/big-dom-generator/"
    click TodoMVCCSS "https://github.com/webkit/speedometer/tree/main/resources/todomvc-css/"
    click VanillaEx "https://github.com/webkit/speedometer/tree/main/resources/vanilla-examples/"
    click ExpTodoMVC "https://github.com/webkit/speedometer/tree/main/experimental/todomvc-localstorage/"

    click MetricCore "https://github.com/webkit/speedometer/blob/main/resources/metric.mjs"
    click MetricUI "https://github.com/webkit/speedometer/blob/main/resources/metric-ui.mjs"
    click Stats "https://github.com/webkit/speedometer/blob/main/resources/statistics.mjs"
    click Translations "https://github.com/webkit/speedometer/blob/main/resources/translations.mjs"

    click DevReport "https://github.com/webkit/speedometer/blob/main/resources/charts/developer.html"
    click EdReport "https://github.com/webkit/speedometer/blob/main/resources/editors/index.html"
    click Style "https://github.com/webkit/speedometer/blob/main/resources/main.css"
    click UIHome "https://github.com/webkit/speedometer/blob/main/index.html"

    click End2End "https://github.com/webkit/speedometer/blob/main/tests/run-end2end.mjs"
    click UnitTests "https://github.com/webkit/speedometer/blob/main/tests/run-unittests.mjs"
    click Server "https://github.com/webkit/speedometer/blob/main/tests/server.mjs"
    click HelperTest "https://github.com/webkit/speedometer/blob/main/tests/helper.mjs"
    click UT_Bench "https://github.com/webkit/speedometer/blob/main/tests/unittests/benchmark-runner.mjs"
    click UT_Params "https://github.com/webkit/speedometer/blob/main/tests/unittests/params.mjs"

    click Workflow "https://github.com/webkit/speedometer/blob/main/.github/workflows/test.yml"
    click Scripts "https://github.com/webkit/speedometer/blob/main/package.json"

    %% Styles
    classDef browser fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef workload fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20;
    classDef fs fill:#F1F8E9,stroke:#4CAF50,color:#2E7D32;
    classDef automation fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef ci fill:#E1BEE7,stroke:#8E24AA,color:#4A148C;
```
