# google/omaha architecture

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

- Interactive diagram: https://gitdiagram.com/google/omaha
- Repository: https://github.com/google/omaha

## Overview

Omaha is a Windows software update platform, not a typical app. Its architecture is centered on installing products, checking for updates, downloading packages, and coordinating silent/background execution through Windows services, COM, scheduled tasks, and installer technology.

1. **Top-level shape**
   The repo is split into a few major execution products:
   - `goopdate`: the main update client/runtime and COM server
   - `core`: launcher and scheduler logic
   - `service`: Windows service entrypoint
   - `setup` and `installers`: bootstrapper/installer generation
   - `enterprise`: MSI, Group Policy, and managed-install support
   - `crashhandler`: crash capture/reporting
   - `standalone`: standalone installer generation
   Supporting code lives in `base`, `common`, `net`, `ui`, `statsreport`, and `testing`.

2. **Primary runtime boundary: `goopdate`**
   `omaha/goopdate` contains the bulk of the runtime state machine. It manages app bundles, app state transitions, update requests/responses, package caching, installer orchestration, command-line parsing, and COM-facing APIs. If you are drawing the core architecture, this is the main “brains” box that coordinates everything else.

3. **Update workflow**
   The update flow is:
   - product/app metadata is read from the registry and local config
   - `update_request`/`update_response` types serialize and parse protocol traffic
   - `net` sends requests over HTTP/WinHTTP, sometimes through BITS
   - server responses describe available updates and download URLs
   - `download_manager` and `package_cache` fetch and stage packages
   - `install_manager`/`installer_wrapper` launch installers and track results
   - ping/metrics code records outcomes back to the service

4. **Protocol and server boundary**
   Omaha speaks multiple update protocols, documented in `doc/ServerProtocol*.md` and `doc/ClientUpdateProtocol*.md`. The boundary to the update service is intentionally explicit: request/response XML definitions in `omaha/common`, helper code in `goopdate`, and ECDSA/CUP support in `omaha/net`. This is where external servers, manifests, signatures, and anti-tamper checks enter the system.

5. **Client-side install and bootstrap**
   `omaha/client` handles the “install Omaha itself” and “install apps through Omaha” paths. It includes self-install logic, bundle creation, update/install progress observation, and user-agent or environment-specific behavior. This is distinct from the updater runtime: it is the bootstrap/installer path that gets Omaha onto the machine or updates it.

6. **Setup, bootstrapper, and package creation**
   `omaha/setup`, `omaha/installers`, `omaha/standalone`, and `omaha/enterprise/installer` generate the distributable artifacts:
   - MSIs, EXEs, and metainstallers
   - tagged installers and resource scripts
   - standalone installers for specific apps
   - enterprise installers with MSI custom actions
   These components are build-time and install-time, not runtime update logic, but they define how products enter the update ecosystem.

7. **Windows integration layer**
   Omaha is deeply Windows-specific. Important integration points include:
   - COM servers and IDL/proxy stubs in `goopdate`
   - Windows service entrypoints in `service` and `core`
   - scheduled tasks in `common/scheduled_task_utils`
   - registry access and monitoring in `base`
   - WinHTTP and BITS in `net`
   - ETW/event logging, shell/process utilities, and user/session handling in `base`
   This means the architecture is heavily split by OS boundary rather than by network/web tiers.

8. **Networking subsystem**
   `omaha/net` abstracts transport concerns: HTTP client code, WinHTTP adapters, BITS requests/jobs, proxy auth, network detection, and request wrappers. It also contains CUP/ECDSA request support and related metrics. This layer is the network edge between Omaha and update servers and hides transport selection and Windows API details from higher-level update logic.

9. **Shared domain logic**
   `omaha/common` holds cross-cutting update-domain code: app registry utilities, command-line handling, config, ping and telemetry models, XML parsing, protocol definitions, policy/group-policy helpers, and signature validation. This is the shared contract layer used by setup, goopdate, enterprise, and networking code.

10. **Core OS and utility library**
   `omaha/base` is a large platform foundation layer: files, paths, registry, processes, threading, timers, environment, security primitives, ETW, WMI, extraction, signature validation, and general Windows wrappers. Architecturally, it is the lowest reusable layer under the Omaha-specific subsystems.

11. **UI and user interaction**
   `omaha/ui` provides dialogs and progress windows for interactive update/install flows. Most background updates are silent, but UI is used for consent, progress, and error presentation when user interaction is required. This is a boundary between unattended service behavior and foreground user experience.

12. **Crash handling and diagnostics**
   `omaha/crashhandler` is a separate executable/service-style component that analyzes dumps, processes crash events, and records crash metrics. The repo also includes Breakpad-related pieces and tools for crash reproduction/handling. This subsystem is isolated because crash collection must survive or outlive the crashing process.

13. **Telemetry, metrics, and reporting**
   `statsreport` and the various `*_metrics.cc` files collect local telemetry such as update progress, installer outcomes, and crash statistics. This data typically flows from runtime components to event logs or upload mechanisms, and is separate from the update protocol itself.

14. **Enterprise and policy management**
   `omaha/enterprise` adds administrative control: ADMX/ADML/ADM templates, MSI custom actions, and installer support for managed deployments. This is the policy boundary where machine-level settings, OEM behavior, and enterprise constraints alter how updates are checked, installed, or suppressed.

15. **Testing, fixtures, and build**
   The repo is test-heavy, with many `*_unittest.cc` files and a dedicated `omaha/testing` fixture corpus containing signed binaries, manifests, certs, cached downloads, and minidumps. Build orchestration is primarily SCons (`build.scons`, `main.scons`) with Python helpers and some WiX/MSI tooling. The fixtures are architecturally important because the system depends on exact signatures, packaging formats, and installer behaviors.

16. **Key data flow to diagram**
   A good architecture diagram should show: installer/bootstrapper creates/launches Omaha; Omaha stores state in registry/files and schedules background work; the updater runtime builds requests from app metadata and policy; the network layer talks to update servers; download/package logic stages artifacts; installer logic executes app updates; metrics/pings and crash data flow back to logging/reporting paths; enterprise policy and Windows service/COM boundaries modulate the whole path.

Main entry points: [`omaha/goopdate`](https://github.com/google/omaha/tree/main/omaha/goopdate) (Goopdate), [`omaha/goopdate/update_request_utils.cc`](https://github.com/google/omaha/blob/main/omaha/goopdate/update_request_utils.cc) (Protocol I/O), [`omaha/common`](https://github.com/google/omaha/tree/main/omaha/common) (Common), [`omaha/setup`](https://github.com/google/omaha/tree/main/omaha/setup) (Setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_goopdate["Goopdate<br/>update runtime"]
  node_goopdate_state["App state<br/>state machine<br/>[app_state.cc]"]
  node_goopdate_network["Protocol I/O<br/>protocol client"]
  node_goopdate_download["Downloads<br/>package fetch"]
  node_goopdate_install["Installs<br/>installer orchestration<br/>[install_manager.cc]"]
  node_core["Core"]
  node_service["Service"]
end

subgraph group_install["Install/Bootstrap"]
  node_client["Client"]
  node_setup["Setup<br/>bootstrapper"]
  node_installers["Installers<br/>artifact builder"]
  node_standalone["Standalone"]
  node_enterprise["Enterprise<br/>policy/installer support"]
end

subgraph group_platform["Platform"]
  node_common["Common<br/>shared domain"]
  node_base["Base<br/>windows foundation"]
  node_net["Net<br/>transport layer"]
  node_ui["UI"]
end

subgraph group_diagnostics["Diagnostics"]
  node_statsreport["Statsreport<br/>metrics library"]
  node_crashhandler["Crashhandler<br/>crash service"]
end

subgraph group_tooling["Tooling"]
  node_testing["Testing<br/>fixtures/test harness"]
  node_tools["Tools"]
end

node_setup -->|"installs/starts"| node_service
node_installers -->|"packages"| node_setup
node_standalone -->|"packages"| node_setup
node_enterprise -->|"extends"| node_installers
node_client -->|"boots"| node_goopdate
node_service -->|"hosts"| node_core
node_core -->|"launches"| node_goopdate
node_goopdate -->|"uses"| node_common
node_goopdate -->|"uses"| node_base
node_goopdate -->|"requests"| node_net
node_goopdate -->|"shows"| node_ui
node_goopdate -->|"reports"| node_statsreport
node_goopdate -->|"reports"| node_crashhandler
node_goopdate -->|"coordinates"| node_goopdate_state
node_goopdate_state -->|"requests"| node_goopdate_network
node_goopdate_network -->|"sends via"| node_net
node_goopdate_network -->|"describes"| node_goopdate_download
node_goopdate_download -->|"hands off"| node_goopdate_install
node_goopdate_install -->|"serves"| node_client
node_common -->|"built on"| node_base
node_common -->|"feeds"| node_net
node_tools -.->|"uses"| node_testing
node_testing -.->|"exercises"| node_goopdate

click node_goopdate "https://github.com/google/omaha/tree/main/omaha/goopdate"
click node_goopdate_state "https://github.com/google/omaha/blob/main/omaha/goopdate/app_state.cc"
click node_goopdate_network "https://github.com/google/omaha/blob/main/omaha/goopdate/update_request_utils.cc"
click node_goopdate_download "https://github.com/google/omaha/blob/main/omaha/goopdate/download_manager.cc"
click node_goopdate_install "https://github.com/google/omaha/blob/main/omaha/goopdate/install_manager.cc"
click node_core "https://github.com/google/omaha/tree/main/omaha/core"
click node_service "https://github.com/google/omaha/tree/main/omaha/service"
click node_client "https://github.com/google/omaha/tree/main/omaha/client"
click node_setup "https://github.com/google/omaha/tree/main/omaha/setup"
click node_installers "https://github.com/google/omaha/tree/main/omaha/installers"
click node_standalone "https://github.com/google/omaha/tree/main/omaha/standalone"
click node_enterprise "https://github.com/google/omaha/tree/main/omaha/enterprise"
click node_common "https://github.com/google/omaha/tree/main/omaha/common"
click node_base "https://github.com/google/omaha/tree/main/omaha/base"
click node_net "https://github.com/google/omaha/tree/main/omaha/net"
click node_ui "https://github.com/google/omaha/tree/main/omaha/ui"
click node_statsreport "https://github.com/google/omaha/tree/main/omaha/statsreport"
click node_crashhandler "https://github.com/google/omaha/tree/main/omaha/crashhandler"
click node_testing "https://github.com/google/omaha/tree/main/omaha/testing"
click node_tools "https://github.com/google/omaha/tree/main/omaha/tools"

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_goopdate,node_goopdate_state,node_goopdate_network,node_goopdate_download,node_goopdate_install,node_core,node_service toneBlue
class node_client,node_setup,node_installers,node_standalone,node_enterprise toneAmber
class node_common,node_base,node_net,node_ui toneMint
class node_statsreport,node_crashhandler toneRose
class node_testing,node_tools toneIndigo
```

## Components

### Runtime

Updater execution and state management

- [Goopdate](https://github.com/google/omaha/tree/main/omaha/goopdate): update runtime · Main updater brain: COM server, app orchestration, state machine, request/response handling, downloads, and installs · `omaha/goopdate`
- [App state](https://github.com/google/omaha/blob/main/omaha/goopdate/app_state.cc): state machine · App bundle and app lifecycle states from init through check, download, install, and stop · `omaha/goopdate/app_state.cc`
- [Protocol I/O](https://github.com/google/omaha/blob/main/omaha/goopdate/update_request_utils.cc): protocol client · Builds update requests, parses responses, and drives web-service interactions · `omaha/goopdate/update_request_utils.cc`
- [Downloads](https://github.com/google/omaha/blob/main/omaha/goopdate/download_manager.cc): package fetch · Download manager, package objects, cache, and staging for update payloads · `omaha/goopdate/download_manager.cc`
- [Installs](https://github.com/google/omaha/blob/main/omaha/goopdate/install_manager.cc): installer orchestration · Launches installers, wraps results, and coordinates install completion · `omaha/goopdate/install_manager.cc`
- [Core](https://github.com/google/omaha/tree/main/omaha/core): scheduler/service core · Launcher, scheduler, and system monitoring for background execution · `omaha/core`
- [Service](https://github.com/google/omaha/tree/main/omaha/service): windows service · Windows service entrypoint for background update execution · `omaha/service`

### Install/Bootstrap

Paths that create, package, or install Omaha and apps

- [Client](https://github.com/google/omaha/tree/main/omaha/client): bootstrap/install client · Installs Omaha itself and app bundles; foreground install paths and progress observation · `omaha/client`
- [Setup](https://github.com/google/omaha/tree/main/omaha/setup): bootstrapper · Installer/bootstrap logic for setting up Omaha and its service · `omaha/setup`
- [Installers](https://github.com/google/omaha/tree/main/omaha/installers): artifact builder · Metainstaller and tagged installer generation · `omaha/installers`
- [Standalone](https://github.com/google/omaha/tree/main/omaha/standalone): standalone installer · Standalone app installer generation and manifests · `omaha/standalone`
- [Enterprise](https://github.com/google/omaha/tree/main/omaha/enterprise): policy/installer support · Managed deployment templates, MSI custom actions, and enterprise installer generation · `omaha/enterprise`

### Platform

Shared Windows and domain infrastructure

- [Common](https://github.com/google/omaha/tree/main/omaha/common): shared domain · Shared update-domain models, protocol definitions, pings, policy helpers, XML, and scheduled tasks · `omaha/common`
- [Base](https://github.com/google/omaha/tree/main/omaha/base): windows foundation · Lowest reusable Windows utility layer: files, registry, threading, processes, security, ETW, and system wrappers · `omaha/base`
- [Net](https://github.com/google/omaha/tree/main/omaha/net): transport layer · HTTP/WinHTTP/BITS transport, network detection, proxy auth, and CUP/ECDSA request support · `omaha/net`
- [UI](https://github.com/google/omaha/tree/main/omaha/ui): foreground UI · Dialogs and progress windows for interactive installs and consent/error presentation · `omaha/ui`

### Diagnostics

Crash and telemetry reporting

- [Statsreport](https://github.com/google/omaha/tree/main/omaha/statsreport): metrics library · Metrics aggregation, formatting, and persistent reporting helpers · `omaha/statsreport`
- [Crashhandler](https://github.com/google/omaha/tree/main/omaha/crashhandler): crash service · Crash dump analysis, worker, and crash metrics subsystem · `omaha/crashhandler`

### Tooling

Build-time and inspection tools

- [Testing](https://github.com/google/omaha/tree/main/omaha/testing): fixtures/test harness · Reusable unittest harnesses and signed/package fixtures used across the repo · `omaha/testing`
- [Tools](https://github.com/google/omaha/tree/main/omaha/tools): utility tools · Developer utilities for tags, dumps, updates, and recovery support · `omaha/tools`

## Connections

- Setup → Service: installs/starts · Bootstrapper lays down the service and runtime pieces
- Installers → Setup: packages · Metainstallers are assembled for deployment
- Standalone → Setup: packages · Standalone app installers feed the install path
- Enterprise → Installers: extends · Enterprise deployment artifacts build on installer generation
- Client → Goopdate: boots · Client-side install path hands off to the updater runtime
- Service → Core: hosts · Windows service hosts the background scheduler/core
- Core → Goopdate: launches · Core schedules and launches update work
- Goopdate → Common: uses · Runtime depends on shared domain models and protocol helpers
- Goopdate → Base: uses · Updater runtime relies on Windows foundation utilities
- Goopdate → Net: requests · Builds protocol traffic and sends it through transport layer
- Goopdate → UI: shows · Foreground update/install flows surface dialogs and progress UI
- Goopdate → Statsreport: reports · Runtime emits local metrics and telemetry
- Goopdate → Crashhandler: reports · Crashes and dumps are handed to crash handling paths
- Goopdate → App state: coordinates · Main runtime drives the bundle and app state machine
- App state → Protocol I/O: requests · State transitions trigger update check and protocol I/O
- Protocol I/O → Net: sends via · Protocol layer delegates transport to networking subsystem
- Protocol I/O → Downloads: describes · Responses provide URLs and package metadata for downloads
- Downloads → Installs: hands off · Fetched packages are staged for installer execution
- Installs → Client: serves · Installer orchestration supports app and Omaha install flows
- Common → Base: built on · Shared domain code uses the Windows foundation layer
- Common → Net: feeds · Protocol definitions and request models drive network traffic
- Tools → Testing: uses · Developer tools and fixtures are validated through tests
- Testing → Goopdate: exercises · Test harness targets the updater runtime and related components
