# thalissonvs/pydoll architecture

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

- Interactive diagram: https://gitdiagram.com/thalissonvs/pydoll
- Repository: https://github.com/thalissonvs/pydoll

## Overview

Pydoll is a Python browser-automation library that drives installed Chrome or Edge directly through the Chrome DevTools Protocol (CDP), with async, sync, and Playwright-compatible interfaces. The principal workflow is user code opening a browser and tab, issuing browser actions and queries through CDP, and receiving page data or typed extracted results. Additional branches provide human-like interactions, fingerprint injection, network control, and proxy configuration. The index and README establish these capabilities; several subsystem connections below are documented rather than verified from sampled implementation.

Main entry points: [`pydoll/browser/tab.py`](https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/tab.py) (Tab Automation), [`pydoll/browser/chromium/base.py`](https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/chromium/base.py) (Browser Control), [`pydoll/elements/web_element.py`](https://github.com/thalissonvs/pydoll/blob/main/pydoll/elements/web_element.py) (Web Elements), [`pydoll/connection/connection_handler.py`](https://github.com/thalissonvs/pydoll/blob/main/pydoll/connection/connection_handler.py) (WebSocket Connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["User APIs"]
  node_async_api["Async API<br/>[chrome.py]"]
  node_sync_api["Sync API<br/>[_generated.py]"]
  node_playwright["Playwright Layer<br/>[_playwright.py]"]
end

subgraph group_browser["Browser Control"]
  node_browser_control["Browser Control<br/>[base.py]"]
  node_options["Browser Options<br/>[options.py]"]
  node_proxy["Proxy Setup<br/>[proxy_manager.py]"]
  node_browser_process["Browser Process"]
end

subgraph group_page["Page Automation"]
  node_tab["Tab Automation<br/>[tab.py]"]
  node_element["Web Elements<br/>[web_element.py]"]
  node_selector["Element Queries"]
  node_iframe["Frame Access<br/>[iframe.py]"]
  node_extractor["Typed Extraction<br/>[engine.py]"]
end

subgraph group_features["Automation Features"]
  node_interaction["Human Interactions<br/>[mouse.py]"]
  node_fingerprint["Fingerprint Injection"]
  node_network["Network Control<br/>[request.py]"]
end

subgraph group_transport["CDP Transport"]
  node_commands["CDP Commands"]
  node_connection["WebSocket Connection"]
  node_protocol["CDP Protocol Types<br/>[base.py]"]
end

node_user(("Automation User"))
node_browser(("Chrome or Edge"))

node_user -->|"uses async"| node_async_api
node_user -->|"uses blocking"| node_sync_api
node_user -->|"adapts scripts"| node_playwright
node_async_api -.->|"opens browser"| node_browser_control
node_sync_api -->|"wraps browser"| node_browser_control
node_playwright -->|"uses tabs"| node_tab
node_browser_control -->|"configures with"| node_options
node_browser_control -.->|"manages process"| node_browser_process
node_options -->|"configures proxy"| node_proxy
node_browser_control -.->|"connects via CDP"| node_connection
node_browser_control -.->|"creates tabs"| node_tab
node_tab -->|"issues commands"| node_commands
node_tab -->|"returns elements"| node_element
node_tab -->|"extracts models"| node_extractor
node_tab -->|"applies fingerprint"| node_fingerprint
node_tab -->|"controls requests"| node_network
node_element -->|"delegates queries"| node_selector
node_element -->|"accesses frames"| node_iframe
node_element -->|"supports actions"| node_interaction
node_extractor -->|"reads page data"| node_element
node_connection -->|"sends messages"| node_protocol
node_commands -.->|"formats commands"| node_protocol
node_connection -->|"exchanges CDP"| node_browser
node_browser -.->|"serves page state"| node_tab

click node_async_api "https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/chromium/chrome.py"
click node_sync_api "https://github.com/thalissonvs/pydoll/blob/main/pydoll/sync/_generated.py"
click node_playwright "https://github.com/thalissonvs/pydoll/blob/main/pydoll/playwright/_playwright.py"
click node_browser_control "https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/chromium/base.py"
click node_options "https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/options.py"
click node_proxy "https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/managers/proxy_manager.py"
click node_browser_process "https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/managers/browser_process_manager.py"
click node_tab "https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/tab.py"
click node_element "https://github.com/thalissonvs/pydoll/blob/main/pydoll/elements/web_element.py"
click node_selector "https://github.com/thalissonvs/pydoll/blob/main/pydoll/elements/mixins/find_elements_mixin.py"
click node_iframe "https://github.com/thalissonvs/pydoll/blob/main/pydoll/interactions/iframe.py"
click node_extractor "https://github.com/thalissonvs/pydoll/blob/main/pydoll/extractor/engine.py"
click node_interaction "https://github.com/thalissonvs/pydoll/blob/main/pydoll/interactions/mouse.py"
click node_fingerprint "https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/fingerprint_applier.py"
click node_network "https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/requests/request.py"
click node_commands "https://github.com/thalissonvs/pydoll/tree/main/pydoll/commands"
click node_connection "https://github.com/thalissonvs/pydoll/blob/main/pydoll/connection/connection_handler.py"
click node_protocol "https://github.com/thalissonvs/pydoll/blob/main/pydoll/protocol/base.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_async_api,node_sync_api,node_playwright,node_user toneBlue
class node_browser_control,node_options,node_proxy,node_browser_process toneAmber
class node_tab,node_element,node_selector,node_iframe,node_extractor toneMint
class node_interaction,node_fingerprint,node_network toneRose
class node_commands,node_connection,node_protocol,node_browser toneIndigo
```

## Components

### User APIs

- [Async API](https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/chromium/chrome.py): `pydoll/browser/chromium/chrome.py`
- [Sync API](https://github.com/thalissonvs/pydoll/blob/main/pydoll/sync/_generated.py): `pydoll/sync/_generated.py`
- [Playwright Layer](https://github.com/thalissonvs/pydoll/blob/main/pydoll/playwright/_playwright.py): `pydoll/playwright/_playwright.py`

### Browser Control

- [Browser Control](https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/chromium/base.py): `pydoll/browser/chromium/base.py`
- [Browser Options](https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/options.py): `pydoll/browser/options.py`
- [Proxy Setup](https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/managers/proxy_manager.py): `pydoll/browser/managers/proxy_manager.py`
- [Browser Process](https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/managers/browser_process_manager.py): `pydoll/browser/managers/browser_process_manager.py`

### Page Automation

- [Tab Automation](https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/tab.py): `pydoll/browser/tab.py`
- [Web Elements](https://github.com/thalissonvs/pydoll/blob/main/pydoll/elements/web_element.py): `pydoll/elements/web_element.py`
- [Element Queries](https://github.com/thalissonvs/pydoll/blob/main/pydoll/elements/mixins/find_elements_mixin.py): `pydoll/elements/mixins/find_elements_mixin.py`
- [Frame Access](https://github.com/thalissonvs/pydoll/blob/main/pydoll/interactions/iframe.py): `pydoll/interactions/iframe.py`
- [Typed Extraction](https://github.com/thalissonvs/pydoll/blob/main/pydoll/extractor/engine.py): `pydoll/extractor/engine.py`

### Automation Features

- [Human Interactions](https://github.com/thalissonvs/pydoll/blob/main/pydoll/interactions/mouse.py): `pydoll/interactions/mouse.py`
- [Fingerprint Injection](https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/fingerprint_applier.py): `pydoll/browser/fingerprint_applier.py`
- [Network Control](https://github.com/thalissonvs/pydoll/blob/main/pydoll/browser/requests/request.py): `pydoll/browser/requests/request.py`

### CDP Transport

- [CDP Commands](https://github.com/thalissonvs/pydoll/tree/main/pydoll/commands): `pydoll/commands`
- [WebSocket Connection](https://github.com/thalissonvs/pydoll/blob/main/pydoll/connection/connection_handler.py): `pydoll/connection/connection_handler.py`
- [CDP Protocol Types](https://github.com/thalissonvs/pydoll/blob/main/pydoll/protocol/base.py): `pydoll/protocol/base.py`

### Other components

- **Automation User**
- **Chrome or Edge**

## Connections

- Automation User → Async API: uses async (evidence: `README.md`)
- Automation User → Sync API: uses blocking (evidence: `README.md`)
- Automation User → Playwright Layer: adapts scripts (evidence: `README.md`)
- Async API → Browser Control: opens browser
- Sync API → Browser Control: wraps browser (evidence: `pydoll/sync/_generated.py`)
- Playwright Layer → Tab Automation: uses tabs
- Browser Control → Browser Options: configures with
- Browser Control → Browser Process: manages process
- Browser Options → Proxy Setup: configures proxy (evidence: `pydoll/browser/managers/proxy_manager.py`)
- Browser Control → WebSocket Connection: connects via CDP
- Browser Control → Tab Automation: creates tabs (evidence: `pydoll/browser/tab.py`)
- Tab Automation → CDP Commands: issues commands (evidence: `pydoll/browser/tab.py`)
- Tab Automation → Web Elements: returns elements (evidence: `pydoll/browser/tab.py`)
- Tab Automation → Typed Extraction: extracts models (evidence: `pydoll/browser/tab.py`)
- Tab Automation → Fingerprint Injection: applies fingerprint (evidence: `pydoll/browser/tab.py`)
- Tab Automation → Network Control: controls requests (evidence: `pydoll/browser/tab.py`)
- Web Elements → Element Queries: delegates queries (evidence: `pydoll/elements/web_element.py`)
- Web Elements → Frame Access: accesses frames (evidence: `pydoll/elements/web_element.py`)
- Web Elements → Human Interactions: supports actions (evidence: `pydoll/elements/web_element.py`)
- Typed Extraction → Web Elements: reads page data (evidence: `pydoll/extractor/engine.py`)
- WebSocket Connection → CDP Protocol Types: sends messages (evidence: `pydoll/connection/connection_handler.py`)
- CDP Commands → CDP Protocol Types: formats commands (evidence: `pydoll/commands/storage_commands.py`)
- WebSocket Connection → Chrome or Edge: exchanges CDP (evidence: `README.md`)
- Chrome or Edge → Tab Automation: serves page state
