# cloudflare/worker-speedtest-template architecture

> Architecture diagram of the GitHub repository cloudflare/worker-speedtest-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudflare/worker-speedtest-template
- Repository: https://github.com/cloudflare/worker-speedtest-template

## Overview

##### What this project is (type + purpose)

This is a **Cloudflare Workers** edge-service (serverless “single binary” web service) that provides a minimal **HTTP API for client-side speed testing**. Clients measure:
- **Download bandwidth/latency** by requesting `/down?bytes=N` (worker returns N bytes)
- **Upload bandwidth/latency** by POSTing to `/up` (worker reads/discards body, responds when fully received)

The README explicitly frames it as a worker used by a browser client leveraging the **Performance Timing API**; so the system boundary includes **(a) the browser measurement logic** and **(b) the edge worker endpoints**. There’s no database and typically no persistent state.

##### What the file tree says about architecture

Top-level highlights:
- `wrangler.toml`: Cloudflare Workers deployment configuration (account, routes, compatibility date, etc.)
- `index.js`: likely the built/entry worker script used for deployment or distribution
- `src/`: the source modules composing the worker
- `src/index.js`: main entrypoint wiring the router to the fetch handler
- `src/router.js`: HTTP routing (maps paths/methods to handlers)
- `src/down.js`: implementation for download endpoint
- `src/up.js`: implementation for upload endpoint
- `src/test.js`: ad-hoc or unit test utilities (not a runtime component)
- `package.json`: build/test/dev tooling and dependencies (also “Dev/Build” lane)

##### Download
- Browser → (HTTPS GET) → Cloudflare Worker `/down?bytes=N`
- Worker router → down handler → returns **N-byte binary response**
- Browser measures: RTT, TTFB, download duration, throughput

##### Upload
- Browser → (HTTPS POST body) → Cloudflare Worker `/up`
- Worker router → up handler → reads/consumes full body → returns response
- Browser measures: upload duration, throughput

- Dev → Wrangler publish → Cloudflare Workers platform
- GitHub Actions → Semgrep scan → results (no runtime impact)

##### Architectural patterns/principles present

- **Single edge service** with **route-based handlers** (router pattern)
- **Stateless request processing** (no persistence)
- **Streaming I/O** for upload consumption (typical Workers pattern)
- **Separation of concerns** at module level:
- routing isolated in `router.js`
- endpoint logic isolated in `down.js` and `up.js`
- entrypoint glues them together in `src/index.js`

Shows: Browser ↔ Cloudflare Worker, plus CI/CD lanes.

Since there’s only one “container” (the Worker), go one level deeper and show **components inside the Worker** (router + handlers).

Use nested boundaries:
- Outer boundary: “Internet”
- Boundary: “Cloudflare Edge Network”
- Component: `fetch` handler (`src/index.js`)
- Component: Router (`src/router.js`)
- Component: Down handler (`src/down.js`)
- Component: Up handler (`src/up.js`)

##### Step 4 — Add deployment/config as a separate lane (not mixed into runtime)
- “Developer machine” → Wrangler → “Workers platform”
- “GitHub repo” → GitHub Actions (Semgrep)

- `src/index.js` → “fetch handler / entrypoint”
- `src/router.js` → “route matcher + dispatch”
- `src/down.js` → “GET /down implementation (size=bytes)”
- `src/up.js` → “POST /up implementation (consume body)”
Optionally:
- `index.js` → “bundled/compiled entry (distribution)”
- `wrangler.toml` → “deployment config”
- `.github/workflows/semgrep.yml` → “static analysis workflow”

##### What *not* to include (avoid inaccuracies)
- Databases, KV, Durable Objects, R2, Queues (not present in tree/README)
- An “API Gateway” separate from Workers (Workers *is* the edge ingress here)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ============ External / Client ============
  subgraph "Client (External)"
    Client["Browser / HTTP Client"]:::external
    Perf["Performance Timing API\n(measures RTT/TTFB/duration/throughput)"]:::note
    Client -->|"uses"| Perf
  end

  %% ============ Internet ============
  Internet["Internet (HTTPS)"]:::boundary

  %% ============ Cloudflare Edge Runtime ============
  subgraph "Cloudflare Edge Network"
    subgraph "Cloudflare Worker: speedtest (stateless)"
      Bundled["Worker Script (bundled entry)"]:::runtime
      Fetch["Fetch Event Handler / Entrypoint"]:::runtime
      Router["HTTP Router\n(route match + dispatch)"]:::runtime
      Down["/down handler\nGET /down?bytes=N\nreturns N bytes (binary)"]:::endpoint
      Up["/up handler\nPOST /up\nreads/discards full body\nresponds after fully received"]:::endpoint

      Bundled -->|"contains/builds"| Fetch
      Fetch -->|"dispatches"| Router
      Router -->|"routes GET /down"| Down
      Router -->|"routes POST /up"| Up
    end
  end

  %% ============ DevOps / Delivery (Non-runtime) ============
  subgraph "DevOps / Delivery (Non-runtime)"
    Dev["Developer Machine"]:::tooling
    Wrangler["Wrangler CLI"]:::tooling
    WConf["Wrangler Config"]:::tooling
    Repo["GitHub Repository"]:::tooling
    Actions["GitHub Actions"]:::tooling
    Semgrep["Semgrep Scan Workflow"]:::tooling
    Pkg["Build/Dev Tooling & Dependencies"]:::tooling
    Tests["Test Utilities (non-runtime)"]:::tooling

    Dev -.->|"publish"| Wrangler
    Wrangler -.->|"reads"| WConf
    Wrangler -.->|"deploys"| Bundled

    Repo -.->|"CI triggers"| Actions
    Actions -.->|"runs"| Semgrep
    Repo -.->|"contains"| Pkg
    Repo -.->|"contains"| Tests
  end

  %% ============ Primary Runtime Flows ============
  Client -->|"HTTPS GET /down?bytes=N"| Internet
  Internet -->|"to edge PoP"| Fetch
  Down -->|"HTTP 200: N-byte binary payload"| Internet
  Internet -->|"response"| Client

  Client -->|"HTTPS POST /up (request body payload)"| Internet
  Internet -->|"to edge PoP"| Fetch
  Up -->|"HTTP 200 after body fully received"| Internet
  Internet -->|"response"| Client

  %% ============ Click Events (from component mapping) ============
  click Bundled "https://github.com/cloudflare/worker-speedtest-template/blob/master/index.js"
  click Fetch "https://github.com/cloudflare/worker-speedtest-template/blob/master/src/index.js"
  click Router "https://github.com/cloudflare/worker-speedtest-template/blob/master/src/router.js"
  click Down "https://github.com/cloudflare/worker-speedtest-template/blob/master/src/down.js"
  click Up "https://github.com/cloudflare/worker-speedtest-template/blob/master/src/up.js"
  click Tests "https://github.com/cloudflare/worker-speedtest-template/blob/master/src/test.js"
  click WConf "https://github.com/cloudflare/worker-speedtest-template/blob/master/wrangler.toml"
  click Semgrep "https://github.com/cloudflare/worker-speedtest-template/blob/master/.github/workflows/semgrep.yml"
  click Pkg "https://github.com/cloudflare/worker-speedtest-template/blob/master/package.json"

  %% ============ Styles ============
  classDef external fill:#ECEFF4,stroke:#4C566A,color:#2E3440,stroke-width:1px
  classDef boundary fill:#F7F7F8,stroke:#9AA0A6,color:#3C4043,stroke-width:1px,stroke-dasharray:4 3
  classDef runtime fill:#D7E9FF,stroke:#1E6BD6,color:#0B2B4C,stroke-width:1.2px
  classDef endpoint fill:#BFE3FF,stroke:#005BBB,color:#05233D,stroke-width:1.2px
  classDef tooling fill:#FFF2B3,stroke:#B58900,color:#4A3B00,stroke-width:1px
  classDef note fill:#E9D8FF,stroke:#6B46C1,color:#2D1B4E,stroke-width:1px,stroke-dasharray:3 3
```
