# googlechrome/lighthouse architecture

> Architecture diagram of the GitHub repository googlechrome/lighthouse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlechrome/lighthouse
- Repository: https://github.com/googlechrome/lighthouse

## Overview

#### Purpose and public entry points
Lighthouse is a Node.js (Node 22+) web-page analysis engine. It drives local Chrome to collect performance, accessibility, SEO, best-practice, security, and agentic-web evidence, then produces a Lighthouse Result (LHR) as JSON/HTML/CSV. Primary interfaces are the CLI (`cli/bin.js`, `cli/index.js`), programmatic core exports (`core/index.js`, `core/index.cjs`), and embedded/browser clients (`clients/devtools/devtools-entry.js`, `clients/extension/manifest.json`).

#### Invocation and lifecycle orchestration
CLI flags select URL, Chrome connection/launch behavior, configuration, output, and independent gather/audit modes. `cli/run.js` coordinates parsing and execution; `core/runner.js` is the central audit pipeline. The system supports normal navigation runs plus snapshot and timespan/user-flow modes through `core/gather/navigation-runner.js`, `core/gather/snapshot-runner.js`, and `core/gather/timespan-runner.js`. Gathered artifacts can be persisted and later audited without a browser.

#### Configuration as the execution contract
A resolved config defines audits, gatherers, categories, groups, emulation/throttling, and plugins; it is the boundary for customization. Built-in presets and config composition live in `core/config/default-config.js`, `core/config/config.js`, and `core/config/config-plugin.js`. Custom plugins can inject audits/gatherers while validation protects the runner’s required artifact and metadata contracts.

#### Browser collection layer
The gather layer owns Chrome DevTools Protocol interaction, lifecycle timing, page preparation, navigation, network monitoring, storage reset, and target/frame handling. `core/gather/driver.js` mediates browser commands; `core/gather/session.js` manages a run session; gatherers under `core/gather/gatherers/` collect raw artifacts such as traces, DevTools logs, DOM-derived elements, accessibility data, screenshots, source maps, and WebMCP/agentic metadata. This is the key external boundary: Chrome/Chromium and the audited URL/network.

#### Artifact derivation and performance analysis
Computed artifacts transform raw traces, network records, screenshots, and DOM results into reusable analysis products. Key stages include trace processing (`core/computed/processed-trace.js`, `core/computed/trace-engine-result.js`), network/dependency modeling (`core/computed/network-records.js`, `core/computed/page-dependency-graph.js`), and metric/simulation analysis (`core/computed/metrics/`, `core/computed/load-simulator.js`). Lantern models load behavior under configured throttling, separating observed browser data from simulated performance estimates.

#### Audits, scoring, and result assembly
Audits consume declared raw/computed artifacts and emit standardized results with details and numeric scores. The audit framework is `core/audits/audit.js`; domain implementations span `core/audits/accessibility/`, `core/audits/metrics/`, `core/audits/insights/`, and `core/audits/seo/`. `core/scoring.js` calculates category scoring, while `core/runner.js` assembles audit results, categories, timing, environment, and artifacts into the LHR contract defined under `types/lhr/`.

#### Report and delivery surfaces
The report generator converts LHR JSON to self-contained or asset-backed HTML using `report/generator/report-generator.js` and `report/generator/report-assets.js`; browser rendering is implemented in `report/renderer/report-renderer.js`. Specialized consumers include the React flow-report UI (`flow-report/src/app.tsx`), static JSON viewer with GitHub/Gist sharing and PSI integration (`viewer/app/src/lighthouse-report-viewer.js`, `viewer/app/src/github-api.js`), and bundle-analysis treemap (`treemap/app/src/main.js`). Localization is shared across core and presentation through `shared/localization/`.

#### Build, integrations, and operational boundaries
Build scripts package distinct Node, DevTools, extension, report, viewer, treemap, lightrider, and DevTools-MCP targets (`build/build-bundle.js`, `build/build-extension.js`, `build/build-bundle-mcp.js`). Runtime integrations include Chrome DevTools Protocol/Chrome, Puppeteer-compatible flows, optional Sentry error reporting (`core/lib/sentry.js`), and Viewer-side GitHub API/secret Gists. CI is GitHub Actions (`.github/workflows/ci.yml`); no application backend is required for core Lighthouse runs.

Main entry points: [`core/runner.js`](https://github.com/googlechrome/lighthouse/blob/main/core/runner.js) (Audit runner), [`build/build-bundle.js`](https://github.com/googlechrome/lighthouse/blob/main/build/build-bundle.js) (Multi-target build), [`core/audits/audit.js`](https://github.com/googlechrome/lighthouse/blob/main/core/audits/audit.js) (Audit framework & domains), [`cli/run.js`](https://github.com/googlechrome/lighthouse/blob/main/cli/run.js) (CLI orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry Surfaces"]
  node_cli["CLI<br/>Node entry<br/>[bin.js]"]
  node_core_exports["Core API<br/>programmatic entry<br/>[index.js]"]
  node_embedded_clients["DevTools &amp; extension<br/>embedded clients<br/>[devtools-entry.js]"]
end

subgraph group_execution["Core Execution"]
  node_cli_run["CLI orchestration<br/>invocation coordinator<br/>[run.js]"]
  node_config["Resolved config<br/>execution contract<br/>[config.js]"]
  node_runner["Audit runner<br/>pipeline orchestrator<br/>[runner.js]"]
  node_run_modes["Navigation, snapshot &amp; timespan<br/>gather modes"]
end

subgraph group_collection["Browser Collection"]
  node_driver{{"Chrome driver<br/>CDP adapter<br/>[driver.js]"}}
  node_session["Gather session<br/>run lifecycle<br/>[session.js]"]
  node_gatherers["Evidence gatherers<br/>raw artifact collectors"]
  node_chrome_target(("Chrome &amp; audited page<br/>external boundary"))
end

subgraph group_analysis["Analysis &amp; Results"]
  node_computed["Computed artifacts<br/>artifact derivation<br/>[processed-trace.js]"]
  node_simulation["Metrics &amp; Lantern simulation<br/>performance analysis<br/>[load-simulator.js]"]
  node_audits["Audit framework &amp; domains<br/>artifact consumers<br/>[audit.js]"]
  node_scoring["Category scoring<br/>score aggregation<br/>[scoring.js]"]
  node_lhr["Lighthouse Result<br/>result contract"]
end

subgraph group_presentation["Reports &amp; Consumers"]
  node_report_generator["Report generator<br/>LHR formatter"]
  node_report_renderer["Report renderer<br/>browser renderer<br/>[report-renderer.js]"]
  node_consumer_uis["Flow report, viewer &amp; treemap<br/>specialized consumers<br/>[app.tsx]"]
end

subgraph group_distribution["Build Targets"]
  node_build["Multi-target build<br/>packaging pipeline<br/>[build-bundle.js]"]
end

node_cli -->|"invokes"| node_cli_run
node_core_exports -->|"uses"| node_runner
node_embedded_clients -->|"runs audits"| node_runner
node_cli_run -->|"resolves"| node_config
node_cli_run -->|"executes"| node_runner
node_config -->|"governs"| node_runner
node_runner -->|"selects mode"| node_run_modes
node_run_modes -->|"creates"| node_session
node_session -->|"controls through"| node_driver
node_driver -->|"CDP / navigation"| node_chrome_target
node_session -->|"runs"| node_gatherers
node_gatherers -->|"collects from"| node_chrome_target
node_gatherers -->|"raw artifacts"| node_computed
node_computed -->|"trace &amp; network models"| node_simulation
node_computed -->|"computed artifacts"| node_audits
node_simulation -->|"metric estimates"| node_audits
node_config -->|"selects"| node_audits
node_audits -->|"audit results"| node_scoring
node_scoring -->|"category scores"| node_lhr
node_runner -->|"assembles"| node_lhr
node_lhr -->|"JSON input"| node_report_generator
node_report_generator -->|"HTML/assets"| node_report_renderer
node_lhr -->|"visualized by"| node_consumer_uis
node_build -.->|"packages"| node_cli
node_build -.->|"packages"| node_embedded_clients
node_build -.->|"packages"| node_report_generator
node_build -.->|"packages"| node_consumer_uis

click node_cli "https://github.com/googlechrome/lighthouse/blob/main/cli/bin.js"
click node_core_exports "https://github.com/googlechrome/lighthouse/blob/main/core/index.js"
click node_embedded_clients "https://github.com/googlechrome/lighthouse/blob/main/clients/devtools/devtools-entry.js"
click node_cli_run "https://github.com/googlechrome/lighthouse/blob/main/cli/run.js"
click node_config "https://github.com/googlechrome/lighthouse/blob/main/core/config/config.js"
click node_runner "https://github.com/googlechrome/lighthouse/blob/main/core/runner.js"
click node_run_modes "https://github.com/googlechrome/lighthouse/blob/main/core/gather/navigation-runner.js"
click node_driver "https://github.com/googlechrome/lighthouse/blob/main/core/gather/driver.js"
click node_session "https://github.com/googlechrome/lighthouse/blob/main/core/gather/session.js"
click node_computed "https://github.com/googlechrome/lighthouse/blob/main/core/computed/processed-trace.js"
click node_simulation "https://github.com/googlechrome/lighthouse/blob/main/core/computed/load-simulator.js"
click node_audits "https://github.com/googlechrome/lighthouse/blob/main/core/audits/audit.js"
click node_scoring "https://github.com/googlechrome/lighthouse/blob/main/core/scoring.js"
click node_report_generator "https://github.com/googlechrome/lighthouse/blob/main/report/generator/report-generator.js"
click node_report_renderer "https://github.com/googlechrome/lighthouse/blob/main/report/renderer/report-renderer.js"
click node_consumer_uis "https://github.com/googlechrome/lighthouse/blob/main/flow-report/src/app.tsx"
click node_build "https://github.com/googlechrome/lighthouse/blob/main/build/build-bundle.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_core_exports,node_embedded_clients toneBlue
class node_cli_run,node_config,node_runner,node_run_modes toneAmber
class node_driver,node_session,node_gatherers,node_chrome_target toneMint
class node_computed,node_simulation,node_audits,node_scoring,node_lhr toneRose
class node_report_generator,node_report_renderer,node_consumer_uis toneIndigo
class node_build toneTeal
```

## Components

### Entry Surfaces

- [CLI](https://github.com/googlechrome/lighthouse/blob/main/cli/bin.js): Node entry · `cli/bin.js`
- [Core API](https://github.com/googlechrome/lighthouse/blob/main/core/index.js): programmatic entry · `core/index.js`
- [DevTools & extension](https://github.com/googlechrome/lighthouse/blob/main/clients/devtools/devtools-entry.js): embedded clients · `clients/devtools/devtools-entry.js`

### Core Execution

- [CLI orchestration](https://github.com/googlechrome/lighthouse/blob/main/cli/run.js): invocation coordinator · `cli/run.js`
- [Resolved config](https://github.com/googlechrome/lighthouse/blob/main/core/config/config.js): execution contract · Defines audits, gatherers, categories, emulation, throttling, and plugins. · `core/config/config.js`
- [Audit runner](https://github.com/googlechrome/lighthouse/blob/main/core/runner.js): pipeline orchestrator · Coordinates gathering, artifact audit, scoring, and LHR assembly. · `core/runner.js`
- [Navigation, snapshot & timespan](https://github.com/googlechrome/lighthouse/blob/main/core/gather/navigation-runner.js): gather modes · `core/gather/navigation-runner.js`

### Browser Collection

Chrome DevTools Protocol boundary and raw evidence collection.

- [Chrome driver](https://github.com/googlechrome/lighthouse/blob/main/core/gather/driver.js): CDP adapter · Mediates Chrome commands and browser lifecycle control. · `core/gather/driver.js`
- [Gather session](https://github.com/googlechrome/lighthouse/blob/main/core/gather/session.js): run lifecycle · `core/gather/session.js`
- **Evidence gatherers**: raw artifact collectors · Collect traces, logs, DOM, accessibility, screenshots, source maps, and agentic metadata.
- **Chrome & audited page**: external boundary · Chromium, target page, and network interaction.

### Analysis & Results

- [Computed artifacts](https://github.com/googlechrome/lighthouse/blob/main/core/computed/processed-trace.js): artifact derivation · Derives reusable trace, network, dependency, and DOM analysis products. · `core/computed/processed-trace.js`
- [Metrics & Lantern simulation](https://github.com/googlechrome/lighthouse/blob/main/core/computed/load-simulator.js): performance analysis · Separates observed browser data from throttled load estimates. · `core/computed/load-simulator.js`
- [Audit framework & domains](https://github.com/googlechrome/lighthouse/blob/main/core/audits/audit.js): artifact consumers · Accessibility, metrics, insights, SEO, and other standardized audit results. · `core/audits/audit.js`
- [Category scoring](https://github.com/googlechrome/lighthouse/blob/main/core/scoring.js): score aggregation · `core/scoring.js`
- **Lighthouse Result**: result contract · JSON result containing audit results, categories, timing, environment, and artifacts.

### Reports & Consumers

- [Report generator](https://github.com/googlechrome/lighthouse/blob/main/report/generator/report-generator.js): LHR formatter · Produces self-contained or asset-backed HTML from LHR JSON. · `report/generator/report-generator.js`
- [Report renderer](https://github.com/googlechrome/lighthouse/blob/main/report/renderer/report-renderer.js): browser renderer · `report/renderer/report-renderer.js`
- [Flow report, viewer & treemap](https://github.com/googlechrome/lighthouse/blob/main/flow-report/src/app.tsx): specialized consumers · `flow-report/src/app.tsx`

### Build Targets

- [Multi-target build](https://github.com/googlechrome/lighthouse/blob/main/build/build-bundle.js): packaging pipeline · Packages Node, DevTools, extension, report, viewer, treemap, and MCP targets. · `build/build-bundle.js`

## Connections

- CLI → CLI orchestration: invokes
- Core API → Audit runner: uses
- DevTools & extension → Audit runner: runs audits
- CLI orchestration → Resolved config: resolves
- CLI orchestration → Audit runner: executes
- Resolved config → Audit runner: governs
- Audit runner → Navigation, snapshot & timespan: selects mode
- Navigation, snapshot & timespan → Gather session: creates
- Gather session → Chrome driver: controls through
- Chrome driver → Chrome & audited page: CDP / navigation
- Gather session → Evidence gatherers: runs
- Evidence gatherers → Chrome & audited page: collects from
- Evidence gatherers → Computed artifacts: raw artifacts
- Computed artifacts → Metrics & Lantern simulation: trace & network models
- Computed artifacts → Audit framework & domains: computed artifacts
- Metrics & Lantern simulation → Audit framework & domains: metric estimates
- Resolved config → Audit framework & domains: selects
- Audit framework & domains → Category scoring: audit results
- Category scoring → Lighthouse Result: category scores
- Audit runner → Lighthouse Result: assembles
- Lighthouse Result → Report generator: JSON input
- Report generator → Report renderer: HTML/assets
- Lighthouse Result → Flow report, viewer & treemap: visualized by
- Multi-target build → CLI: packages
- Multi-target build → DevTools & extension: packages
- Multi-target build → Report generator: packages
- Multi-target build → Flow report, viewer & treemap: packages
