# xewdy444/playwright-recaptcha architecture

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

- Interactive diagram: https://gitdiagram.com/xewdy444/playwright-recaptcha
- Repository: https://github.com/xewdy444/playwright-recaptcha

## Overview

Playwright-reCAPTCHA is a Python library that returns a reCAPTCHA response token to browser-automation callers. For v2, callers invoke a synchronous or asynchronous solver, which locates and interacts with the challenge; audio solving transcribes audio, while optional image solving delegates classification to CapSolver. For v3, the solver listens for the browser’s reload response and extracts its token. The README documents Google speech recognition for v2 audio. Source excerpts are partial, so the graph omits unverified method-level wiring.

Main entry points: [`playwright_recaptcha/recaptchav2/sync_solver.py`](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/sync_solver.py) (Sync V2 solver), [`playwright_recaptcha/recaptchav2/async_solver.py`](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/async_solver.py) (Async V2 solver), [`playwright_recaptcha/recaptchav2/base_solver.py`](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/base_solver.py) (V2 solver base), [`playwright_recaptcha/recaptchav3/base_solver.py`](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav3/base_solver.py) (V3 solver base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_v2["reCAPTCHA v2"]
  node_v2api["V2 public API<br/>[__init__.py]"]
  node_v2base["V2 solver base<br/>[base_solver.py]"]
  node_v2sync["Sync V2 solver<br/>[sync_solver.py]"]
  node_v2async["Async V2 solver<br/>[async_solver.py]"]
  node_box["Challenge frames<br/>[recaptcha_box.py]"]
  node_translations["Challenge translations<br/>[translations.py]"]
end

subgraph group_v3["reCAPTCHA v3"]
  node_v3api["V3 public API<br/>[__init__.py]"]
  node_v3base["V3 solver base<br/>[base_solver.py]"]
  node_v3sync["Sync V3 solver<br/>[sync_solver.py]"]
  node_v3async["Async V3 solver<br/>[async_solver.py]"]
end

subgraph group_shared["Shared components"]
  node_errors["Solver errors<br/>[errors.py]"]
  node_package["Package exports<br/>[__init__.py]"]
end

node_caller(("Automation caller"))
node_page["Playwright page"]
node_token["Response token"]
node_google["reCAPTCHA service"]
node_speech["Speech recognition"]
node_capsolver["CapSolver API"]

node_caller -->|"imports solvers"| node_package
node_package -->|"exports V2"| node_v2api
node_package -->|"exports V3"| node_v3api
node_caller -->|"invokes"| node_v2sync
node_caller -->|"invokes"| node_v2async
node_caller -->|"invokes"| node_v3sync
node_caller -->|"invokes"| node_v3async
node_v2api -->|"exports"| node_v2sync
node_v2api -->|"exports"| node_v2async
node_v3api -->|"exports"| node_v3sync
node_v3api -->|"exports"| node_v3async
node_v2sync -->|"extends"| node_v2base
node_v2async -->|"extends"| node_v2base
node_v2sync -->|"interacts with"| node_box
node_v2async -->|"interacts with"| node_box
node_box -->|"uses labels"| node_translations
node_v2sync -.->|"posts image tasks"| node_capsolver
node_v2async -.->|"posts image tasks"| node_capsolver
node_v2sync -->|"transcribes audio"| node_speech
node_v2async -->|"transcribes audio"| node_speech
node_v2sync -->|"controls challenge"| node_page
node_v2async -->|"controls challenge"| node_page
node_page -->|"sends challenge requests"| node_google
node_google -->|"returns challenge responses"| node_page
node_v3sync -->|"extends"| node_v3base
node_v3async -->|"extends"| node_v3base
node_v3base -->|"registers response listener"| node_page
node_page -->|"sends reload request"| node_google
node_google -->|"returns reload response"| node_page
node_v3sync -->|"extracts token"| node_token
node_v3async -->|"extracts token"| node_token
node_v2base -->|"returns token"| node_token
node_token -->|"returns result"| node_caller
node_v2base -->|"raises solve errors"| node_errors
node_v3base -->|"raises timeout errors"| node_errors

click node_v2api "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/__init__.py"
click node_v2base "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/base_solver.py"
click node_v2sync "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/sync_solver.py"
click node_v2async "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/async_solver.py"
click node_box "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/recaptcha_box.py"
click node_translations "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/translations.py"
click node_v3api "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav3/__init__.py"
click node_v3base "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav3/base_solver.py"
click node_v3sync "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav3/sync_solver.py"
click node_v3async "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav3/async_solver.py"
click node_errors "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/errors.py"
click node_package "https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/__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_v2api,node_v2base,node_v2sync,node_v2async,node_box,node_translations toneBlue
class node_v3api,node_v3base,node_v3sync,node_v3async toneAmber
class node_errors,node_package,node_capsolver toneMint
class node_caller,node_page,node_token,node_google,node_speech toneIndigo
```

## Components

### reCAPTCHA v2

- [V2 public API](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/__init__.py): `playwright_recaptcha/recaptchav2/__init__.py`
- [V2 solver base](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/base_solver.py): `playwright_recaptcha/recaptchav2/base_solver.py`
- [Sync V2 solver](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/sync_solver.py): `playwright_recaptcha/recaptchav2/sync_solver.py`
- [Async V2 solver](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/async_solver.py): `playwright_recaptcha/recaptchav2/async_solver.py`
- [Challenge frames](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/recaptcha_box.py): `playwright_recaptcha/recaptchav2/recaptcha_box.py`
- [Challenge translations](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav2/translations.py): `playwright_recaptcha/recaptchav2/translations.py`

### reCAPTCHA v3

- [V3 public API](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav3/__init__.py): `playwright_recaptcha/recaptchav3/__init__.py`
- [V3 solver base](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav3/base_solver.py): `playwright_recaptcha/recaptchav3/base_solver.py`
- [Sync V3 solver](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav3/sync_solver.py): `playwright_recaptcha/recaptchav3/sync_solver.py`
- [Async V3 solver](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/recaptchav3/async_solver.py): `playwright_recaptcha/recaptchav3/async_solver.py`

### Shared components

- [Solver errors](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/errors.py): `playwright_recaptcha/errors.py`
- [Package exports](https://github.com/xewdy444/playwright-recaptcha/blob/main/playwright_recaptcha/__init__.py): `playwright_recaptcha/__init__.py`

### Other components

- **Automation caller**
- **Playwright page**
- **Response token**
- **reCAPTCHA service**
- **Speech recognition**
- **CapSolver API**

## Connections

- Automation caller → Package exports: imports solvers
- Package exports → V2 public API: exports V2
- Package exports → V3 public API: exports V3
- Automation caller → Sync V2 solver: invokes
- Automation caller → Async V2 solver: invokes
- Automation caller → Sync V3 solver: invokes
- Automation caller → Async V3 solver: invokes
- V2 public API → Sync V2 solver: exports
- V2 public API → Async V2 solver: exports
- V3 public API → Sync V3 solver: exports
- V3 public API → Async V3 solver: exports
- Sync V2 solver → V2 solver base: extends
- Async V2 solver → V2 solver base: extends
- Sync V2 solver → Challenge frames: interacts with
- Async V2 solver → Challenge frames: interacts with
- Challenge frames → Challenge translations: uses labels
- Sync V2 solver → CapSolver API: posts image tasks
- Async V2 solver → CapSolver API: posts image tasks
- Sync V2 solver → Speech recognition: transcribes audio
- Async V2 solver → Speech recognition: transcribes audio
- Sync V2 solver → Playwright page: controls challenge
- Async V2 solver → Playwright page: controls challenge
- Playwright page → reCAPTCHA service: sends challenge requests
- reCAPTCHA service → Playwright page: returns challenge responses
- Sync V3 solver → V3 solver base: extends
- Async V3 solver → V3 solver base: extends
- V3 solver base → Playwright page: registers response listener
- Playwright page → reCAPTCHA service: sends reload request
- reCAPTCHA service → Playwright page: returns reload response
- Sync V3 solver → Response token: extracts token
- Async V3 solver → Response token: extracts token
- V2 solver base → Response token: returns token
- Response token → Automation caller: returns result
- V2 solver base → Solver errors: raises solve errors
- V3 solver base → Solver errors: raises timeout errors