# googlechromelabs/chrome-for-testing architecture

> Architecture diagram of the GitHub repository googlechromelabs/chrome-for-testing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlechromelabs/chrome-for-testing
- Repository: https://github.com/googlechromelabs/chrome-for-testing

## Overview

##### Project Type and Purpose
- This is an open-source **static site generator + CLI utility suite** that publishes JSON API endpoints and HTML pages for “Chrome for Testing” version availability.
- It ingests “known good” Chrome version data, enriches it with download URLs, builds a static website (hosted via GitHub Pages), and provides command-line tools (`find-version.mjs`, `check-version.mjs`) to query those APIs or check asset availability.

##### File Structure Analysis
- Top-level scripts (`find-version.mjs`, `check-version.mjs`) form the CLI utilities.
- The `data/` folder holds raw JSON source files.
- Generator modules (`generate-*.mjs`, `html-utils.mjs`, `json-utils.mjs`, `url-utils.mjs`) read `data/` and templates (`_tpl/template.html`) to produce JSON endpoints and HTML files in `dist/`.
- CI and deployment are handled by GitHub Actions (`.github/workflows/build.yml`).
- Configuration is minimal: `package.json`, `.nvmrc`, `.editorconfig`, `.gitignore`.

##### Key Components
a. External Data Sources
- Google Cloud Storage (chrome-for-testing-public)
- Upstream “LATEST_RELEASE_*” endpoints
b. Local Repository
- `data/` (raw JSON snapshots)
- `_tpl/` (HTML template)
- Generator scripts (`generate-*.mjs`, `html-utils.mjs`, `json-utils.mjs`, `url-utils.mjs`)
- CLI tools (`find-version.mjs`, `check-version.mjs`, `check-version.mjs`)
c. Build Orchestrator
- GitHub Actions workflow (`build.yml`)
- npm scripts (`npm run generate`, `npm run find`, `npm run check`)
d. Output & Hosting
- `dist/` directory containing JSON API endpoints + HTML pages
- GitHub Pages hosting (via `gh-pages` or `actions-gh-pages`)
e. Consumers
- Browsers (human users viewing HTML)
- Automation tools or other services fetching JSON endpoints
- CLI users running `npm run find` / `npm run check`

##### Relationships & Data Flow
1. CI Trigger (push to main) → GitHub Actions
2. Actions checks out code → `npm install` → executes generator scripts
3. Generator scripts: read `data/*.json` → enrich with download URLs (via `url-utils`) → output new JSON API files and HTML pages to `dist/` (using `_tpl/template.html` + `html-utils`)
4. Actions deploys `dist/` to GitHub Pages
5. External consumers (browsers, clients, CLI) fetch JSON and HTML from GitHub Pages URLs
6. CLI tools (`find-version`, `check-version`) can also query Google Cloud Storage directly or fetch the generated JSON endpoints to validate asset availability

##### Architectural Patterns & Design Principles
- **Static Site Generator (SSG)** pattern: separation of content (`data/`) from presentation (`_tpl/`) and logic (`generate-*.mjs`).
- **Single-responsibility** per script: each `generate-*.mjs` has one job (directory index, extra JSON, HTML, latest-release JSON).
- **Modular utilities** (`json-utils`, `url-utils`, `html-utils`) to avoid duplication and simplify maintenance.
- **CI/CD via GitHub Actions** for fully automated build and deploy.
- **CLI Commands** leveraging shared modules for consistency.

##### Essential Elements to Capture
- All six generator scripts and their inputs/outputs
- Template folder `_tpl/template.html` as the presentation layer
- The `data/` source JSON and the `dist/` output directory
- GitHub Actions workflow triggering build and deploy
- External Google Cloud Storage as a source of binary assets
- Consumers: browsers/API clients and the command-line utilities

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Source
    subgraph "External Data Sources"
        direction TB
        GCS(("Google Cloud Storage")):::data
        UpstreamEndpoints["Upstream LATEST_RELEASE_* endpoints"]:::data
    end

    %% Local Repository Data
    subgraph "Local Repository"
        direction TB
        subgraph "data/" 
            direction TB
            KG1["known-good-versions.json"]:::data
            KG2["known-good-versions-with-downloads.json"]:::data
            LK1["last-known-good-versions.json"]:::data
            LK2["last-known-good-versions-with-downloads.json"]:::data
            LP1["latest-patch-versions-per-build.json"]:::data
            LP2["latest-patch-versions-per-build-with-downloads.json"]:::data
            LM1["latest-versions-per-milestone.json"]:::data
            LM2["latest-versions-per-milestone-with-downloads.json"]:::data
        end
        _TPL["_tpl/template.html"]:::data
        subgraph "Generator Scripts"
            direction TB
            GDIR["generate-directory-index.mjs"]:::generator
            GEXTRA["generate-extra-json.mjs"]:::generator
            GHTML["generate-html.mjs"]:::generator
            GLATEST["generate-latest-release.mjs"]:::generator
        end
        subgraph "Shared Utilities"
            direction TB
            HTMLU["html-utils.mjs"]:::generator
            JSONU["json-utils.mjs"]:::generator
            URLU["url-utils.mjs"]:::generator
            VERSIONH["is-older-version.mjs"]:::generator
        end
    end

    %% Build Orchestrator
    subgraph "CI/CD & Build"
        direction TB
        GH_ACTIONS(("GitHub Actions")):::ci
        BUILD_YML[".github/workflows/build.yml"]:::ci
        PKG["package.json"]:::ci
        NPM_INSTALL["npm install & npm run generate"]:::ci
        GH_PAGES(("GitHub Pages")):::ci
    end

    %% Output
    subgraph "Output & Hosting"
        direction TB
        DIST(("dist/ (JSON & HTML)")):::data
        NOJEKYLL[".nojekyll"]:::data
    end

    %% CLI Tools
    subgraph "CLI Tools"
        direction TB
        FIND["find-version.mjs"]:::cli
        CHECK["check-version.mjs"]:::cli
    end

    %% Consumers
    subgraph "Consumers"
        direction TB
        BROWSERS["Browsers / Human Users"]:::external
        API_CLIENTS["Automation / API Clients"]:::external
        CLI_USERS["CLI Users"]:::external
    end

    %% Data Flows
    GCS -->|provides raw assets| KG1
    GCS -->|provides raw assets| KG2
    GCS -->|provides raw assets| LK1
    GCS -->|provides raw assets| LK2
    GCS -->|provides raw assets| LP1
    GCS -->|provides raw assets| LP2
    GCS -->|provides raw assets| LM1
    GCS -->|provides raw assets| LM2
    UpstreamEndpoints --> KG1
    UpstreamEndpoints --> LK1
    KG1 & KG2 & LK1 & LK2 & LP1 & LP2 & LM1 & LM2 --> GDIR
    _TPL --> GHTML
    GDIR --> DIST
    GEXTRA --> DIST
    GHTML --> DIST
    GLATEST --> DIST
    HTMLU & JSONU & URLU & VERSIONH --> GDIR
    HTMLU & JSONU & URLU & VERSIONH --> GEXTRA
    HTMLU & JSONU & URLU & VERSIONH --> GHTML
    HTMLU & JSONU & URLU & VERSIONH --> GLATEST

    %% CI/CD Flow
    GH_ACTIONS -->|checkout & install| NPM_INSTALL
    BUILD_YML --> GH_ACTIONS
    PKG --> NPM_INSTALL
    NPM_INSTALL --> GDIR
    NPM_INSTALL --> GEXTRA
    NPM_INSTALL --> GHTML
    NPM_INSTALL --> GLATEST
    NPM_INSTALL --> DIST
    GH_ACTIONS -->|deploy| GH_PAGES
    DIST --> GH_PAGES

    %% Consumption Flows
    BROWSERS -->|view HTML| GH_PAGES
    API_CLIENTS -->|fetch JSON endpoints| GH_PAGES
    CLI_USERS -->|run find-version| FIND
    CLI_USERS -->|run check-version| CHECK
    FIND -->|fetch from JSON endpoints| GH_PAGES
    FIND -->|query assets| GCS
    CHECK -->|fetch from JSON endpoints| GH_PAGES
    CHECK -->|query assets| GCS

    %% Click Events
    click FIND "https://github.com/googlechromelabs/chrome-for-testing/blob/main/find-version.mjs"
    click CHECK "https://github.com/googlechromelabs/chrome-for-testing/blob/main/check-version.mjs"
    click KG1 "https://github.com/googlechromelabs/chrome-for-testing/blob/main/data/known-good-versions.json"
    click KG2 "https://github.com/googlechromelabs/chrome-for-testing/blob/main/data/known-good-versions-with-downloads.json"
    click LK1 "https://github.com/googlechromelabs/chrome-for-testing/blob/main/data/last-known-good-versions.json"
    click LK2 "https://github.com/googlechromelabs/chrome-for-testing/blob/main/data/last-known-good-versions-with-downloads.json"
    click LP1 "https://github.com/googlechromelabs/chrome-for-testing/blob/main/data/latest-patch-versions-per-build.json"
    click LP2 "https://github.com/googlechromelabs/chrome-for-testing/blob/main/data/latest-patch-versions-per-build-with-downloads.json"
    click LM1 "https://github.com/googlechromelabs/chrome-for-testing/blob/main/data/latest-versions-per-milestone.json"
    click LM2 "https://github.com/googlechromelabs/chrome-for-testing/blob/main/data/latest-versions-per-milestone-with-downloads.json"
    click _TPL "https://github.com/googlechromelabs/chrome-for-testing/blob/main/_tpl/template.html"
    click GDIR "https://github.com/googlechromelabs/chrome-for-testing/blob/main/generate-directory-index.mjs"
    click GEXTRA "https://github.com/googlechromelabs/chrome-for-testing/blob/main/generate-extra-json.mjs"
    click GHTML "https://github.com/googlechromelabs/chrome-for-testing/blob/main/generate-html.mjs"
    click GLATEST "https://github.com/googlechromelabs/chrome-for-testing/blob/main/generate-latest-release.mjs"
    click HTMLU "https://github.com/googlechromelabs/chrome-for-testing/blob/main/html-utils.mjs"
    click JSONU "https://github.com/googlechromelabs/chrome-for-testing/blob/main/json-utils.mjs"
    click URLU "https://github.com/googlechromelabs/chrome-for-testing/blob/main/url-utils.mjs"
    click VERSIONH "https://github.com/googlechromelabs/chrome-for-testing/blob/main/is-older-version.mjs"
    click BUILD_YML "https://github.com/googlechromelabs/chrome-for-testing/blob/main/.github/workflows/build.yml"
    click PKG "https://github.com/googlechromelabs/chrome-for-testing/blob/main/package.json"
    click DIST "https://github.com/googlechromelabs/chrome-for-testing/tree/main/dist/"

    %% Styles
    classDef data fill:#bbdefb,stroke:#2196f3,stroke-width:1px
    classDef generator fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef ci fill:#ffe0b2,stroke:#f57c00,stroke-width:1px
    classDef cli fill:#e1bee7,stroke:#8e24aa,stroke-width:1px
    classDef external fill:#f0f4c3,stroke:#afb42b,stroke-width:1px
```
