# go-rod/rod architecture

> Architecture diagram of the GitHub repository go-rod/rod, 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/go-rod/rod
- Repository: https://github.com/go-rod/rod

## Overview

#### Purpose and public surface
Rod is a Go library for Chrome/Chromium web automation and scraping, layered over the Chrome DevTools Protocol (CDP). Its primary user-facing API is the root package: browser lifecycle in `browser.go`, page operations in `page.go` and `page_eval.go`, DOM selection/actions in `element.go` and `query.go`, and cancellation/deadlines in `context.go`.

#### Browser lifecycle and attachment
A `Browser` represents a DevTools-connected browser and creates/manages pages. It can connect to an externally launched browser or work with the launcher subsystem. Browser startup, endpoint discovery, process ownership, and revision/download management are separated under `lib/launcher/launcher.go`, `lib/launcher/browser.go`, and `lib/launcher/manager.go`. This is the boundary between Rod’s API and the local browser process/remote debugging endpoint.

#### CDP transport and protocol model
`lib/cdp/client.go` provides the transport-facing CDP client, with WebSocket communication in `lib/cdp/websocket.go`. `lib/proto/` is the typed representation of CDP domains and commands, including `lib/proto/page.go`, `lib/proto/network.go`, and `lib/proto/runtime.go`. Root-level high-level operations ultimately issue these protocol requests and consume CDP events; advanced consumers can use these lower-level layers directly.

#### Page, frame, and DOM automation
`Page` is the main automation unit, coordinating navigation, evaluation, waits, events, and frame context. Core behavior is in `page.go`, `states.go`, and `page_eval.go`. DOM-facing abstractions in `element.go` and `query.go` resolve selectors and operate across nested iframes and shadow DOMs. The control flow is generally: caller configures a contextual `Page` → queries/evaluates through CDP Runtime/DOM/Page domains → waits for browser events or state transitions → returns typed page/element results.

#### Interaction and execution helpers
Input synthesis is exposed at the root through `input.go` and implemented against CDP through `lib/input/keyboard.go` and `lib/input/mouse.go`. JavaScript evaluation and injected helper code are supported by `page_eval.go` and generated assets in `lib/js/js.go`. These form the browser-execution boundary: Go values and commands are serialized to CDP; page JavaScript, rendered DOM state, and input events remain in Chromium.

#### Network interception and observability
`hijack.go` implements request interception/manipulation over CDP Fetch/Network functionality, enabling request inspection, replacement, or blocking during page execution. Debug/monitoring assets are embedded in `lib/assets/assets.go` and `lib/assets/monitor.html`. This keeps network control and diagnostic UI separate from the normal page-automation API.

#### Runtime, infrastructure, and distribution
The runtime is Go plus a Chromium-family browser reachable via DevTools WebSocket. Browser acquisition and cross-platform launch logic are in `lib/launcher/`; Docker packaging is defined by `lib/docker/Dockerfile` and `lib/docker/main.go`. Generated protocol, JavaScript, device, and asset packages (`lib/proto/generate/main.go`, `lib/js/generate/main.go`, `lib/devices/generate/main.go`) maintain typed/runtime artifacts derived from external browser protocol data.

Main entry points: [`lib/cdp/client.go`](https://github.com/go-rod/rod/blob/main/lib/cdp/client.go) (CDP client), [`page.go`](https://github.com/go-rod/rod/blob/main/page.go) (Page operations), [`browser.go`](https://github.com/go-rod/rod/blob/main/browser.go) (Browser lifecycle), [`page_eval.go`](https://github.com/go-rod/rod/blob/main/page_eval.go) (Evaluation & context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Rod API"]
  node_browser_api["Browser lifecycle<br/>root API<br/>[browser.go]"]
  node_page_api["Page operations<br/>root API<br/>[page.go]"]
  node_page_eval["Evaluation &amp; context<br/>root API<br/>[page_eval.go]"]
  node_dom_api["Element queries<br/>root API<br/>[element.go]"]
end

subgraph group_browser["Browser Runtime"]
  node_launcher["Launcher subsystem<br/>browser launcher<br/>[launcher.go]"]
  node_chromium{{"Chromium browser<br/>external runtime"}}
end

subgraph group_cdp["CDP Stack"]
  node_cdp_client["CDP client<br/>protocol client<br/>[client.go]"]
  node_websocket["DevTools WebSocket<br/>transport<br/>[websocket.go]"]
  node_proto["Typed CDP domains<br/>protocol model"]
end

subgraph group_execution["Browser Execution"]
  node_dom_runtime["DOM &amp; frame control<br/>automation flow<br/>[query.go]"]
  node_js_assets["Injected JS helpers<br/>generated runtime assets<br/>[js.go]"]
  node_input["Input synthesis<br/>interaction<br/>[input.go]"]
  node_hijack["Network interception<br/>network control<br/>[hijack.go]"]
  node_monitor["Monitor assets<br/>observability UI<br/>[monitor.html]"]
end

subgraph group_distribution["Tooling &amp; Distribution"]
  node_generators["Artifact generators<br/>code generation<br/>[main.go]"]
  node_docker["Docker packaging<br/>container runtime"]
end

node_caller(("Go caller<br/>consumer"))

node_caller -->|"creates/connects"| node_browser_api
node_caller -->|"automates"| node_page_api
node_browser_api -->|"launches or attaches via"| node_launcher
node_launcher -->|"starts/manages"| node_chromium
node_browser_api -->|"uses"| node_cdp_client
node_page_api -->|"evaluates through"| node_page_eval
node_page_api -->|"queries and acts through"| node_dom_api
node_dom_api -->|"issues CDP commands"| node_cdp_client
node_page_eval -->|"issues Runtime/Page commands"| node_cdp_client
node_page_eval -->|"injects"| node_js_assets
node_input -->|"sends input via"| node_cdp_client
node_hijack -->|"uses Fetch/Network"| node_cdp_client
node_cdp_client -->|"serializes typed messages"| node_proto
node_cdp_client -->|"communicates over"| node_websocket
node_websocket -->|"DevTools endpoint"| node_chromium
node_monitor -.->|"observes"| node_page_api
node_generators -->|"generates"| node_proto
node_generators -->|"generates"| node_js_assets
node_docker -->|"packages runtime for"| node_launcher
node_docker -->|"includes"| node_chromium

click node_browser_api "https://github.com/go-rod/rod/blob/main/browser.go"
click node_page_api "https://github.com/go-rod/rod/blob/main/page.go"
click node_page_eval "https://github.com/go-rod/rod/blob/main/page_eval.go"
click node_dom_api "https://github.com/go-rod/rod/blob/main/element.go"
click node_launcher "https://github.com/go-rod/rod/blob/main/lib/launcher/launcher.go"
click node_cdp_client "https://github.com/go-rod/rod/blob/main/lib/cdp/client.go"
click node_websocket "https://github.com/go-rod/rod/blob/main/lib/cdp/websocket.go"
click node_dom_runtime "https://github.com/go-rod/rod/blob/main/query.go"
click node_js_assets "https://github.com/go-rod/rod/blob/main/lib/js/js.go"
click node_input "https://github.com/go-rod/rod/blob/main/input.go"
click node_hijack "https://github.com/go-rod/rod/blob/main/hijack.go"
click node_monitor "https://github.com/go-rod/rod/blob/main/lib/assets/monitor.html"
click node_generators "https://github.com/go-rod/rod/blob/main/lib/proto/generate/main.go"
click node_docker "https://github.com/go-rod/rod/blob/main/lib/docker/Dockerfile"

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_browser_api,node_page_api,node_page_eval,node_dom_api toneBlue
class node_launcher,node_chromium toneAmber
class node_cdp_client,node_websocket,node_proto toneMint
class node_dom_runtime,node_js_assets,node_input,node_hijack,node_monitor toneRose
class node_generators,node_docker toneIndigo
class node_caller toneNeutral
```

## Components

### Rod API

User-facing Go automation surface.

- [Browser lifecycle](https://github.com/go-rod/rod/blob/main/browser.go): root API · Connects to DevTools and manages pages. · `browser.go`
- [Page operations](https://github.com/go-rod/rod/blob/main/page.go): root API · Navigation, waits, events, and frame context. · `page.go`
- [Evaluation & context](https://github.com/go-rod/rod/blob/main/page_eval.go): root API · Evaluation plus cancellation and deadline control. · `page_eval.go`
- [Element queries](https://github.com/go-rod/rod/blob/main/element.go): root API · Selector-based DOM actions across frames and shadow DOM. · `element.go`

### Browser Runtime

Browser process lifecycle and DevTools attachment.

- [Launcher subsystem](https://github.com/go-rod/rod/blob/main/lib/launcher/launcher.go): browser launcher · Discovers endpoints, owns processes, and manages browser revisions. · `lib/launcher/launcher.go`
- **Chromium browser**: external runtime · Exposes a remote debugging WebSocket endpoint.

### CDP Stack

Transport and typed Chrome DevTools Protocol model.

- [CDP client](https://github.com/go-rod/rod/blob/main/lib/cdp/client.go): protocol client · Issues commands and routes protocol events. · `lib/cdp/client.go`
- [DevTools WebSocket](https://github.com/go-rod/rod/blob/main/lib/cdp/websocket.go): transport · `lib/cdp/websocket.go`
- **Typed CDP domains**: protocol model · Page, Network, Runtime, and other typed commands/events.

### Browser Execution

DOM, JavaScript, input, and network control.

- [DOM & frame control](https://github.com/go-rod/rod/blob/main/query.go): automation flow · Resolves DOM state through Page, DOM, and Runtime protocol domains. · `query.go`
- [Injected JS helpers](https://github.com/go-rod/rod/blob/main/lib/js/js.go): generated runtime assets · `lib/js/js.go`
- [Input synthesis](https://github.com/go-rod/rod/blob/main/input.go): interaction · Keyboard and mouse commands sent through CDP. · `input.go`
- [Network interception](https://github.com/go-rod/rod/blob/main/hijack.go): network control · Inspects, replaces, or blocks requests via Fetch/Network. · `hijack.go`
- [Monitor assets](https://github.com/go-rod/rod/blob/main/lib/assets/monitor.html): observability UI · Embedded diagnostic interface. · `lib/assets/monitor.html`

### Tooling & Distribution

Generated artifacts and container packaging.

- [Artifact generators](https://github.com/go-rod/rod/blob/main/lib/proto/generate/main.go): code generation · Maintains protocol, JavaScript, device, and asset artifacts. · `lib/proto/generate/main.go`
- [Docker packaging](https://github.com/go-rod/rod/blob/main/lib/docker/Dockerfile): container runtime · Packages Rod with its browser runtime. · `lib/docker/Dockerfile`

### Other components

- **Go caller**: consumer

## Connections

- Go caller → Browser lifecycle: creates/connects
- Go caller → Page operations: automates
- Browser lifecycle → Launcher subsystem: launches or attaches via
- Launcher subsystem → Chromium browser: starts/manages
- Browser lifecycle → CDP client: uses
- Page operations → Evaluation & context: evaluates through
- Page operations → Element queries: queries and acts through
- Element queries → CDP client: issues CDP commands
- Evaluation & context → CDP client: issues Runtime/Page commands
- Evaluation & context → Injected JS helpers: injects
- Input synthesis → CDP client: sends input via
- Network interception → CDP client: uses Fetch/Network
- CDP client → Typed CDP domains: serializes typed messages
- CDP client → DevTools WebSocket: communicates over
- DevTools WebSocket → Chromium browser: DevTools endpoint
- Monitor assets → Page operations: observes
- Artifact generators → Typed CDP domains: generates
- Artifact generators → Injected JS helpers: generates
- Docker packaging → Launcher subsystem: packages runtime for
- Docker packaging → Chromium browser: includes
