# chromedp/chromedp architecture

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

- Interactive diagram: https://gitdiagram.com/chromedp/chromedp
- Repository: https://github.com/chromedp/chromedp

## Overview

chromedp is a Go library for automating browsers through the Chrome DevTools Protocol. Its main workflow creates a browser context, runs actions such as navigation and element queries against a tab, and returns values or observes page events. The runtime also includes browser allocation and target/session management, plus input, emulation, JavaScript, console, screenshot, and PDF capabilities. A separate remote module supports websocket connections to existing browsers. Relationships below follow the README’s documented workflow and capabilities; unsampled implementation details are not assumed.

Main entry points: [`target.go`](https://github.com/chromedp/chromedp/blob/main/target.go) (Tab targets), [`chromedp.go`](https://github.com/chromedp/chromedp/blob/main/chromedp.go) (Context and Run), [`action.go`](https://github.com/chromedp/chromedp/blob/main/action.go) (Action API), [`query.go`](https://github.com/chromedp/chromedp/blob/main/query.go) (Element queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Actions and queries"]
  node_actions["Action API<br/>[action.go]"]
  node_queries["Element queries<br/>[query.go]"]
  node_input["Input actions<br/>[input.go]"]
  node_keyboard["Keyboard mappings<br/>[kb.go]"]
end

subgraph group_runtime["Browser runtime"]
  node_context["Context and Run<br/>[chromedp.go]"]
  node_allocator["Browser allocator<br/>[allocate.go]"]
  node_pipealloc["Pipe allocation<br/>[allocate_pipe.go]"]
  node_browser["Browser connection<br/>[browser.go]"]
  node_target["Tab targets<br/>[target.go]"]
  node_session["Protocol sessions<br/>[session.go]"]
end

subgraph group_features["Browser capabilities"]
  node_navigation["Navigation<br/>[nav.go]"]
  node_evaluation["JavaScript evaluation<br/>[eval.go]"]
  node_console["Console and events<br/>[console.go]"]
  node_expose["Go function exposure<br/>[expose.go]"]
  node_screenshots["Screenshots<br/>[screenshot.go]"]
  node_pdf["PDF output<br/>[pdf.go]"]
  node_emulation["Device emulation<br/>[emulate.go]"]
  node_devices["Device profiles<br/>[device.go]"]
end

subgraph group_remote["Remote connection"]
  node_remoteallocator["Remote allocator<br/>[allocator.go]"]
  node_websocket["WebSocket transport<br/>[conn.go]"]
end

node_caller(("Go application"))
node_chrome(("Chrome browser"))
node_existing(("Existing browser"))

node_caller -->|"creates context"| node_context
node_caller -->|"runs actions"| node_actions
node_caller -->|"navigates pages"| node_navigation
node_caller -->|"selects elements"| node_queries
node_context -->|"starts browser"| node_allocator
node_allocator -->|"uses pipe"| node_pipealloc
node_pipealloc -->|"connects by pipe"| node_chrome
node_browser -->|"speaks DevTools"| node_chrome
node_context -->|"runs against tab"| node_target
node_actions -->|"runs on tab"| node_target
node_queries -->|"queries tab"| node_target
node_input -->|"sends input"| node_target
node_keyboard -->|"maps keys"| node_input
node_caller -->|"evaluates JavaScript"| node_evaluation
node_caller -->|"reads events"| node_console
node_caller -->|"exposes functions"| node_expose
node_caller -->|"captures screens"| node_screenshots
node_caller -->|"prints pages"| node_pdf
node_caller -->|"emulates devices"| node_emulation
node_devices -->|"provides profiles"| node_emulation
node_caller -->|"attaches remotely"| node_remoteallocator
node_remoteallocator -.->|"uses transport"| node_websocket
node_websocket -->|"connects by websocket"| node_existing

click node_actions "https://github.com/chromedp/chromedp/blob/main/action.go"
click node_queries "https://github.com/chromedp/chromedp/blob/main/query.go"
click node_input "https://github.com/chromedp/chromedp/blob/main/input.go"
click node_keyboard "https://github.com/chromedp/chromedp/blob/main/kb/kb.go"
click node_context "https://github.com/chromedp/chromedp/blob/main/chromedp.go"
click node_allocator "https://github.com/chromedp/chromedp/blob/main/allocate.go"
click node_pipealloc "https://github.com/chromedp/chromedp/blob/main/allocate_pipe.go"
click node_browser "https://github.com/chromedp/chromedp/blob/main/browser.go"
click node_target "https://github.com/chromedp/chromedp/blob/main/target.go"
click node_session "https://github.com/chromedp/chromedp/blob/main/session.go"
click node_navigation "https://github.com/chromedp/chromedp/blob/main/nav.go"
click node_evaluation "https://github.com/chromedp/chromedp/blob/main/eval.go"
click node_console "https://github.com/chromedp/chromedp/blob/main/console.go"
click node_expose "https://github.com/chromedp/chromedp/blob/main/expose.go"
click node_screenshots "https://github.com/chromedp/chromedp/blob/main/screenshot.go"
click node_pdf "https://github.com/chromedp/chromedp/blob/main/pdf.go"
click node_emulation "https://github.com/chromedp/chromedp/blob/main/emulate.go"
click node_devices "https://github.com/chromedp/chromedp/blob/main/device/device.go"
click node_remoteallocator "https://github.com/chromedp/chromedp/blob/main/remote/allocator.go"
click node_websocket "https://github.com/chromedp/chromedp/blob/main/remote/conn.go"

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_actions,node_queries,node_input,node_keyboard,node_chrome,node_existing toneBlue
class node_context,node_allocator,node_pipealloc,node_browser,node_target,node_session toneAmber
class node_navigation,node_evaluation,node_console,node_expose,node_screenshots,node_pdf,node_emulation,node_devices toneMint
class node_remoteallocator,node_websocket toneRose
class node_caller toneIndigo
```

## Components

### Actions and queries

- [Action API](https://github.com/chromedp/chromedp/blob/main/action.go): `action.go`
- [Element queries](https://github.com/chromedp/chromedp/blob/main/query.go): `query.go`
- [Input actions](https://github.com/chromedp/chromedp/blob/main/input.go): `input.go`
- [Keyboard mappings](https://github.com/chromedp/chromedp/blob/main/kb/kb.go): `kb/kb.go`

### Browser runtime

- [Context and Run](https://github.com/chromedp/chromedp/blob/main/chromedp.go): `chromedp.go`
- [Browser allocator](https://github.com/chromedp/chromedp/blob/main/allocate.go): `allocate.go`
- [Pipe allocation](https://github.com/chromedp/chromedp/blob/main/allocate_pipe.go): `allocate_pipe.go`
- [Browser connection](https://github.com/chromedp/chromedp/blob/main/browser.go): `browser.go`
- [Tab targets](https://github.com/chromedp/chromedp/blob/main/target.go): `target.go`
- [Protocol sessions](https://github.com/chromedp/chromedp/blob/main/session.go): `session.go`

### Browser capabilities

- [Navigation](https://github.com/chromedp/chromedp/blob/main/nav.go): `nav.go`
- [JavaScript evaluation](https://github.com/chromedp/chromedp/blob/main/eval.go): `eval.go`
- [Console and events](https://github.com/chromedp/chromedp/blob/main/console.go): `console.go`
- [Go function exposure](https://github.com/chromedp/chromedp/blob/main/expose.go): `expose.go`
- [Screenshots](https://github.com/chromedp/chromedp/blob/main/screenshot.go): `screenshot.go`
- [PDF output](https://github.com/chromedp/chromedp/blob/main/pdf.go): `pdf.go`
- [Device emulation](https://github.com/chromedp/chromedp/blob/main/emulate.go): `emulate.go`
- [Device profiles](https://github.com/chromedp/chromedp/blob/main/device/device.go): `device/device.go`

### Remote connection

- [Remote allocator](https://github.com/chromedp/chromedp/blob/main/remote/allocator.go): `remote/allocator.go`
- [WebSocket transport](https://github.com/chromedp/chromedp/blob/main/remote/conn.go): `remote/conn.go`

### Other components

- **Go application**
- **Chrome browser**
- **Existing browser**

## Connections

- Go application → Context and Run: creates context
- Go application → Action API: runs actions
- Go application → Navigation: navigates pages
- Go application → Element queries: selects elements
- Context and Run → Browser allocator: starts browser
- Browser allocator → Pipe allocation: uses pipe
- Pipe allocation → Chrome browser: connects by pipe
- Browser connection → Chrome browser: speaks DevTools
- Context and Run → Tab targets: runs against tab
- Action API → Tab targets: runs on tab
- Element queries → Tab targets: queries tab
- Input actions → Tab targets: sends input
- Keyboard mappings → Input actions: maps keys (evidence: `input.go`)
- Go application → JavaScript evaluation: evaluates JavaScript
- Go application → Console and events: reads events
- Go application → Go function exposure: exposes functions
- Go application → Screenshots: captures screens
- Go application → PDF output: prints pages
- Go application → Device emulation: emulates devices
- Device profiles → Device emulation: provides profiles (evidence: `device/device.go`)
- Go application → Remote allocator: attaches remotely
- Remote allocator → WebSocket transport: uses transport
- WebSocket transport → Existing browser: connects by websocket
