# sexfrance/truedriver architecture

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

- Interactive diagram: https://gitdiagram.com/sexfrance/truedriver
- Repository: https://github.com/sexfrance/truedriver

## Overview

Truedriver is an async Python browser-automation and scraping framework built on Chrome DevTools Protocol (CDP). A developer starts a Browser, opens a page through a Tab, locates and interacts with Elements (including within iframes), then reads page content or saves outputs. The main internal layers are browser lifecycle/configuration, tab and element APIs, and the CDP command/event transport. The README also documents cookies/profiles, proxy authentication, stealth configuration, and broad CDP capabilities. Some feature wiring is inferred only from documentation and the sampled excerpts, so uncertain links are omitted.

Main entry points: [`truedriver/core/tab.py`](https://github.com/sexfrance/truedriver/blob/main/truedriver/core/tab.py) (Tab navigation), [`truedriver/cdp/__init__.py`](https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/__init__.py) (CDP domains), [`truedriver/core/browser.py`](https://github.com/sexfrance/truedriver/blob/main/truedriver/core/browser.py) (Browser lifecycle), [`truedriver/core/element.py`](https://github.com/sexfrance/truedriver/blob/main/truedriver/core/element.py) (Element operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Automation API"]
  node_public_api["Public API<br/>[__init__.py]"]
  node_start["Startup helpers<br/>[util.py]"]
end

subgraph group_browser["Browser Runtime"]
  node_config["Browser config<br/>[config.py]"]
  node_browser_runtime["Browser lifecycle<br/>[browser.py]"]
end

subgraph group_interaction["Page Interaction"]
  node_tab["Tab navigation<br/>[tab.py]"]
  node_element["Element operations<br/>[element.py]"]
  node_expect["Wait conditions<br/>[expect.py]"]
  node_intercept["Request interception<br/>[intercept.py]"]
end

subgraph group_protocol["CDP Protocol"]
  node_connection["WebSocket transport<br/>[connection.py]"]
  node_cdp_page["Page commands<br/>[page.py]"]
  node_cdp_dom["DOM commands<br/>[dom.py]"]
  node_cdp_runtime["Runtime commands<br/>[runtime.py]"]
  node_cdp_input["Input commands<br/>[input_.py]"]
  node_cdp_network["Network commands<br/>[network.py]"]
  node_cdp_fetch["Fetch commands<br/>[fetch.py]"]
  node_cdp_catalog["CDP domains<br/>[__init__.py]"]
end

node_developer(("Python developer"))
node_chrome["Chrome-family browser"]
node_proxy["Proxy service"]

node_developer -->|"uses"| node_public_api
node_public_api -->|"exports"| node_start
node_start -->|"configures"| node_config
node_start -->|"starts"| node_browser_runtime
node_browser_runtime -->|"opens transport"| node_connection
node_browser_runtime -->|"opens tabs"| node_tab
node_tab -->|"sends commands"| node_connection
node_tab -->|"navigates via"| node_cdp_page
node_tab -->|"queries via"| node_cdp_dom
node_tab -->|"evaluates via"| node_cdp_runtime
node_tab -->|"returns elements"| node_element
node_element -->|"uses tab"| node_tab
node_element -->|"resolves nodes"| node_cdp_dom
node_element -->|"dispatches input"| node_cdp_input
node_expect -->|"waits on"| node_tab
node_intercept -->|"uses commands"| node_cdp_fetch
node_browser_runtime -->|"handles proxy auth"| node_cdp_network
node_browser_runtime -->|"reads settings"| node_config
node_connection -->|"exchanges CDP"| node_chrome
node_cdp_catalog -->|"includes"| node_cdp_page
node_cdp_catalog -->|"includes"| node_cdp_dom
node_cdp_catalog -->|"includes"| node_cdp_runtime
node_cdp_catalog -->|"includes"| node_cdp_input
node_cdp_catalog -->|"includes"| node_cdp_network
node_cdp_catalog -->|"includes"| node_cdp_fetch
node_config -.->|"configures proxy"| node_proxy

click node_public_api "https://github.com/sexfrance/truedriver/blob/main/truedriver/__init__.py"
click node_start "https://github.com/sexfrance/truedriver/blob/main/truedriver/core/util.py"
click node_config "https://github.com/sexfrance/truedriver/blob/main/truedriver/core/config.py"
click node_browser_runtime "https://github.com/sexfrance/truedriver/blob/main/truedriver/core/browser.py"
click node_connection "https://github.com/sexfrance/truedriver/blob/main/truedriver/core/connection.py"
click node_tab "https://github.com/sexfrance/truedriver/blob/main/truedriver/core/tab.py"
click node_element "https://github.com/sexfrance/truedriver/blob/main/truedriver/core/element.py"
click node_expect "https://github.com/sexfrance/truedriver/blob/main/truedriver/core/expect.py"
click node_intercept "https://github.com/sexfrance/truedriver/blob/main/truedriver/core/intercept.py"
click node_cdp_page "https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/page.py"
click node_cdp_dom "https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/dom.py"
click node_cdp_runtime "https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/runtime.py"
click node_cdp_input "https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/input_.py"
click node_cdp_network "https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/network.py"
click node_cdp_fetch "https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/fetch.py"
click node_cdp_catalog "https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/__init__.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_public_api,node_start,node_chrome toneBlue
class node_config,node_browser_runtime toneAmber
class node_tab,node_element,node_expect,node_intercept toneMint
class node_connection,node_cdp_page,node_cdp_dom,node_cdp_runtime,node_cdp_input,node_cdp_network,node_cdp_fetch,node_cdp_catalog toneRose
class node_developer,node_proxy toneIndigo
```

## Components

### Automation API

- [Public API](https://github.com/sexfrance/truedriver/blob/main/truedriver/__init__.py): `truedriver/__init__.py`
- [Startup helpers](https://github.com/sexfrance/truedriver/blob/main/truedriver/core/util.py): `truedriver/core/util.py`

### Browser Runtime

- [Browser config](https://github.com/sexfrance/truedriver/blob/main/truedriver/core/config.py): `truedriver/core/config.py`
- [Browser lifecycle](https://github.com/sexfrance/truedriver/blob/main/truedriver/core/browser.py): `truedriver/core/browser.py`

### Page Interaction

- [Tab navigation](https://github.com/sexfrance/truedriver/blob/main/truedriver/core/tab.py): `truedriver/core/tab.py`
- [Element operations](https://github.com/sexfrance/truedriver/blob/main/truedriver/core/element.py): `truedriver/core/element.py`
- [Wait conditions](https://github.com/sexfrance/truedriver/blob/main/truedriver/core/expect.py): `truedriver/core/expect.py`
- [Request interception](https://github.com/sexfrance/truedriver/blob/main/truedriver/core/intercept.py): `truedriver/core/intercept.py`

### CDP Protocol

- [WebSocket transport](https://github.com/sexfrance/truedriver/blob/main/truedriver/core/connection.py): `truedriver/core/connection.py`
- [Page commands](https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/page.py): `truedriver/cdp/page.py`
- [DOM commands](https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/dom.py): `truedriver/cdp/dom.py`
- [Runtime commands](https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/runtime.py): `truedriver/cdp/runtime.py`
- [Input commands](https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/input_.py): `truedriver/cdp/input_.py`
- [Network commands](https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/network.py): `truedriver/cdp/network.py`
- [Fetch commands](https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/fetch.py): `truedriver/cdp/fetch.py`
- [CDP domains](https://github.com/sexfrance/truedriver/blob/main/truedriver/cdp/__init__.py): `truedriver/cdp/__init__.py`

### Other components

- **Python developer**
- **Chrome-family browser**
- **Proxy service**

## Connections

- Python developer → Public API: uses
- Public API → Startup helpers: exports
- Startup helpers → Browser config: configures
- Startup helpers → Browser lifecycle: starts
- Browser lifecycle → WebSocket transport: opens transport
- Browser lifecycle → Tab navigation: opens tabs
- Tab navigation → WebSocket transport: sends commands
- Tab navigation → Page commands: navigates via
- Tab navigation → DOM commands: queries via
- Tab navigation → Runtime commands: evaluates via
- Tab navigation → Element operations: returns elements
- Element operations → Tab navigation: uses tab
- Element operations → DOM commands: resolves nodes
- Element operations → Input commands: dispatches input
- Wait conditions → Tab navigation: waits on
- Request interception → Fetch commands: uses commands
- Browser lifecycle → Network commands: handles proxy auth
- Browser lifecycle → Browser config: reads settings
- WebSocket transport → Chrome-family browser: exchanges CDP
- CDP domains → Page commands: includes
- CDP domains → DOM commands: includes
- CDP domains → Runtime commands: includes
- CDP domains → Input commands: includes
- CDP domains → Network commands: includes
- CDP domains → Fetch commands: includes
- Browser config → Proxy service: configures proxy