# mozilla/mozregression architecture

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

- Interactive diagram: https://gitdiagram.com/mozilla/mozregression
- Repository: https://github.com/mozilla/mozregression

## Overview

mozregression is an interactive Mozilla-build regression rangefinder. Users provide a known-good and known-bad build or date range, then mozregression finds candidate builds, downloads and launches them, and uses the user's verdicts to narrow the range. The GUI adds guided setup, single-build runs, preferences, and reports. The graph preserves the CLI and GUI entry paths and the core discovery, download, execution, and bisection stages; some GUI and runtime connections are based on the SOURCE INDEX rather than complete excerpts.

Main entry points: [`mozregression/main.py`](https://github.com/mozilla/mozregression/blob/main/mozregression/main.py) (CLI application), [`gui/mozregui/mainwindow.py`](https://github.com/mozilla/mozregression/blob/main/gui/mozregui/mainwindow.py) (Main window), [`mozregression/fetch_build_info.py`](https://github.com/mozilla/mozregression/blob/main/mozregression/fetch_build_info.py) (Build metadata lookup), [`gui/mozregui/main.py`](https://github.com/mozilla/mozregression/blob/main/gui/mozregui/main.py) (GUI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_app["CLI application<br/>[main.py]"]
  node_gui["GUI application<br/>[main.py]"]
  node_window["Main window<br/>[mainwindow.py]"]
  node_wizard["Guided setup<br/>[wizard.py]"]
end

subgraph group_discovery["Build discovery"]
  node_branches["Branch catalog<br/>[branches.py]"]
  node_fetchconfigs["Build configuration<br/>[fetch_configs.py]"]
  node_buildrange["Build ranges<br/>[build_range.py]"]
  node_fetchinfo["Build metadata lookup"]
  node_pushes["Push history<br/>[json_pushes.py]"]
  node_buildinfo["Build metadata<br/>[build_info.py]"]
  node_network["HTTP utilities<br/>[network.py]"]
end

subgraph group_execution["Build execution"]
  node_downloads["Build downloads"]
  node_storage[("Download cache limits<br/>[persist_limit.py]")]
  node_launchers["Application launchers<br/>[launchers.py]"]
  node_test_runner["Build test runner"]
end

subgraph group_bisection["Regression analysis"]
  node_bisector["Bisection engine<br/>[bisector.py]"]
  node_gui_bisector["GUI bisection runner<br/>[bisection.py]"]
  node_report["Run reports<br/>[report.py]"]
end

subgraph group_support["Settings and reporting"]
  node_config["Configuration<br/>[config.py]"]
  node_prefs["GUI preferences<br/>[global_prefs.py]"]
  node_logs["GUI log view<br/>[log_report.py]"]
  node_telemetry["Telemetry<br/>[telemetry.py]"]
end

node_user(("User"))
node_mozilla["Mozilla build services"]
node_browser["Mozilla application"]

node_user -->|"runs"| node_cli
node_user -->|"opens"| node_gui
node_cli -->|"starts"| node_app
node_app -->|"loads configuration"| node_fetchconfigs
node_app -->|"runs bisection"| node_bisector
node_app -->|"manages downloads"| node_downloads
node_app -->|"selects launcher"| node_launchers
node_fetchconfigs -->|"resolves branches"| node_branches
node_buildrange -->|"requests build metadata"| node_fetchinfo
node_fetchinfo -->|"constructs metadata"| node_buildinfo
node_fetchinfo -->|"queries push history"| node_pushes
node_fetchinfo -->|"uses HTTP"| node_network
node_pushes -->|"uses HTTP"| node_network
node_fetchinfo -.->|"retrieves build data"| node_mozilla
node_downloads -.->|"downloads builds"| node_mozilla
node_downloads -->|"enforces cache limit"| node_storage
node_app -->|"runs build tests"| node_test_runner
node_app -->|"initializes telemetry"| node_telemetry
node_launchers -.->|"launches"| node_browser
node_bisector -->|"creates range"| node_buildrange
node_bisector -->|"uses push history"| node_pushes
node_gui -->|"creates window"| node_window
node_gui -->|"sets defaults"| node_prefs
node_gui -->|"attaches log model"| node_logs
node_window -->|"opens setup"| node_wizard
node_window -->|"starts bisection"| node_gui_bisector
node_window -->|"displays reports"| node_report
node_window -->|"edits preferences"| node_prefs
node_gui_bisector -->|"runs bisection"| node_bisector
node_gui_bisector -->|"coordinates downloads"| node_downloads
node_gui_bisector -->|"collects verdicts"| node_test_runner
node_wizard -->|"builds configuration"| node_fetchconfigs
node_wizard -->|"checks runnable app"| node_launchers
node_prefs -->|"reads configuration"| node_config

click node_cli "https://github.com/mozilla/mozregression/blob/main/mozregression/cli.py"
click node_app "https://github.com/mozilla/mozregression/blob/main/mozregression/main.py"
click node_gui "https://github.com/mozilla/mozregression/blob/main/gui/mozregui/main.py"
click node_window "https://github.com/mozilla/mozregression/blob/main/gui/mozregui/mainwindow.py"
click node_wizard "https://github.com/mozilla/mozregression/blob/main/gui/mozregui/wizard.py"
click node_branches "https://github.com/mozilla/mozregression/blob/main/mozregression/branches.py"
click node_fetchconfigs "https://github.com/mozilla/mozregression/blob/main/mozregression/fetch_configs.py"
click node_buildrange "https://github.com/mozilla/mozregression/blob/main/mozregression/build_range.py"
click node_fetchinfo "https://github.com/mozilla/mozregression/blob/main/mozregression/fetch_build_info.py"
click node_pushes "https://github.com/mozilla/mozregression/blob/main/mozregression/json_pushes.py"
click node_buildinfo "https://github.com/mozilla/mozregression/blob/main/mozregression/build_info.py"
click node_network "https://github.com/mozilla/mozregression/blob/main/mozregression/network.py"
click node_downloads "https://github.com/mozilla/mozregression/blob/main/mozregression/download_manager.py"
click node_storage "https://github.com/mozilla/mozregression/blob/main/mozregression/persist_limit.py"
click node_launchers "https://github.com/mozilla/mozregression/blob/main/mozregression/launchers.py"
click node_test_runner "https://github.com/mozilla/mozregression/tree/main/mozregression"
click node_bisector "https://github.com/mozilla/mozregression/blob/main/mozregression/bisector.py"
click node_gui_bisector "https://github.com/mozilla/mozregression/blob/main/gui/mozregui/bisection.py"
click node_report "https://github.com/mozilla/mozregression/blob/main/gui/mozregui/report.py"
click node_config "https://github.com/mozilla/mozregression/blob/main/mozregression/config.py"
click node_prefs "https://github.com/mozilla/mozregression/blob/main/gui/mozregui/global_prefs.py"
click node_logs "https://github.com/mozilla/mozregression/blob/main/gui/mozregui/log_report.py"
click node_telemetry "https://github.com/mozilla/mozregression/blob/main/mozregression/telemetry.py"

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_app,node_gui,node_window,node_wizard,node_user toneBlue
class node_branches,node_fetchconfigs,node_buildrange,node_fetchinfo,node_pushes,node_buildinfo,node_network toneAmber
class node_downloads,node_storage,node_launchers,node_test_runner toneMint
class node_bisector,node_gui_bisector,node_report toneRose
class node_config,node_prefs,node_logs,node_telemetry,node_mozilla,node_browser toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/mozilla/mozregression/blob/main/mozregression/cli.py): `mozregression/cli.py`
- [CLI application](https://github.com/mozilla/mozregression/blob/main/mozregression/main.py): `mozregression/main.py`
- [GUI application](https://github.com/mozilla/mozregression/blob/main/gui/mozregui/main.py): `gui/mozregui/main.py`
- [Main window](https://github.com/mozilla/mozregression/blob/main/gui/mozregui/mainwindow.py): `gui/mozregui/mainwindow.py`
- [Guided setup](https://github.com/mozilla/mozregression/blob/main/gui/mozregui/wizard.py): `gui/mozregui/wizard.py`

### Build discovery

- [Branch catalog](https://github.com/mozilla/mozregression/blob/main/mozregression/branches.py): `mozregression/branches.py`
- [Build configuration](https://github.com/mozilla/mozregression/blob/main/mozregression/fetch_configs.py): `mozregression/fetch_configs.py`
- [Build ranges](https://github.com/mozilla/mozregression/blob/main/mozregression/build_range.py): `mozregression/build_range.py`
- [Build metadata lookup](https://github.com/mozilla/mozregression/blob/main/mozregression/fetch_build_info.py): `mozregression/fetch_build_info.py`
- [Push history](https://github.com/mozilla/mozregression/blob/main/mozregression/json_pushes.py): `mozregression/json_pushes.py`
- [Build metadata](https://github.com/mozilla/mozregression/blob/main/mozregression/build_info.py): `mozregression/build_info.py`
- [HTTP utilities](https://github.com/mozilla/mozregression/blob/main/mozregression/network.py): `mozregression/network.py`

### Build execution

- [Build downloads](https://github.com/mozilla/mozregression/blob/main/mozregression/download_manager.py): `mozregression/download_manager.py`
- [Download cache limits](https://github.com/mozilla/mozregression/blob/main/mozregression/persist_limit.py): `mozregression/persist_limit.py`
- [Application launchers](https://github.com/mozilla/mozregression/blob/main/mozregression/launchers.py): `mozregression/launchers.py`
- [Build test runner](https://github.com/mozilla/mozregression/tree/main/mozregression): `mozregression`

### Regression analysis

- [Bisection engine](https://github.com/mozilla/mozregression/blob/main/mozregression/bisector.py): `mozregression/bisector.py`
- [GUI bisection runner](https://github.com/mozilla/mozregression/blob/main/gui/mozregui/bisection.py): `gui/mozregui/bisection.py`
- [Run reports](https://github.com/mozilla/mozregression/blob/main/gui/mozregui/report.py): `gui/mozregui/report.py`

### Settings and reporting

- [Configuration](https://github.com/mozilla/mozregression/blob/main/mozregression/config.py): `mozregression/config.py`
- [GUI preferences](https://github.com/mozilla/mozregression/blob/main/gui/mozregui/global_prefs.py): `gui/mozregui/global_prefs.py`
- [GUI log view](https://github.com/mozilla/mozregression/blob/main/gui/mozregui/log_report.py): `gui/mozregui/log_report.py`
- [Telemetry](https://github.com/mozilla/mozregression/blob/main/mozregression/telemetry.py): `mozregression/telemetry.py`

### Other components

- **User**
- **Mozilla build services**
- **Mozilla application**

## Connections

- User → CLI: runs (evidence: `README.md`)
- User → GUI application: opens (evidence: `README.md`)
- CLI → CLI application: starts (evidence: `mozregression/cli.py`)
- CLI application → Build configuration: loads configuration (evidence: `mozregression/main.py`)
- CLI application → Bisection engine: runs bisection (evidence: `mozregression/main.py`)
- CLI application → Build downloads: manages downloads (evidence: `mozregression/main.py`)
- CLI application → Application launchers: selects launcher (evidence: `mozregression/main.py`)
- Build configuration → Branch catalog: resolves branches (evidence: `mozregression/fetch_configs.py`)
- Build ranges → Build metadata lookup: requests build metadata (evidence: `mozregression/build_range.py`)
- Build metadata lookup → Build metadata: constructs metadata (evidence: `mozregression/fetch_build_info.py`)
- Build metadata lookup → Push history: queries push history (evidence: `mozregression/fetch_build_info.py`)
- Build metadata lookup → HTTP utilities: uses HTTP (evidence: `mozregression/fetch_build_info.py`)
- Push history → HTTP utilities: uses HTTP (evidence: `mozregression/json_pushes.py`)
- Build metadata lookup → Mozilla build services: retrieves build data
- Build downloads → Mozilla build services: downloads builds
- Build downloads → Download cache limits: enforces cache limit (evidence: `mozregression/download_manager.py`)
- CLI application → Build test runner: runs build tests (evidence: `mozregression/main.py`)
- CLI application → Telemetry: initializes telemetry (evidence: `mozregression/main.py`)
- Application launchers → Mozilla application: launches
- Bisection engine → Build ranges: creates range (evidence: `mozregression/bisector.py`)
- Bisection engine → Push history: uses push history (evidence: `mozregression/bisector.py`)
- GUI application → Main window: creates window (evidence: `gui/mozregui/main.py`)
- GUI application → GUI preferences: sets defaults (evidence: `gui/mozregui/main.py`)
- GUI application → GUI log view: attaches log model (evidence: `gui/mozregui/main.py`)
- Main window → Guided setup: opens setup (evidence: `gui/mozregui/mainwindow.py`)
- Main window → GUI bisection runner: starts bisection (evidence: `gui/mozregui/mainwindow.py`)
- Main window → Run reports: displays reports (evidence: `gui/mozregui/mainwindow.py`)
- Main window → GUI preferences: edits preferences (evidence: `gui/mozregui/mainwindow.py`)
- GUI bisection runner → Bisection engine: runs bisection (evidence: `gui/mozregui/bisection.py`)
- GUI bisection runner → Build downloads: coordinates downloads (evidence: `gui/mozregui/bisection.py`)
- GUI bisection runner → Build test runner: collects verdicts (evidence: `gui/mozregui/bisection.py`)
- Guided setup → Build configuration: builds configuration (evidence: `gui/mozregui/wizard.py`)
- Guided setup → Application launchers: checks runnable app (evidence: `gui/mozregui/wizard.py`)
- GUI preferences → Configuration: reads configuration (evidence: `gui/mozregui/global_prefs.py`)
