# kaliiiiiiiiii-vinyzu/patchright architecture

> Architecture diagram of the GitHub repository kaliiiiiiiiii-vinyzu/patchright, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaliiiiiiiiii-vinyzu/patchright
- Repository: https://github.com/kaliiiiiiiiii-vinyzu/patchright

## Overview

##### Project type and purpose
- From the file tree and README, this is not a classic frontend/backend app but an open-source tooling project: “Patchright Driver,” a patched, undetectable drop-in replacement for Playwright’s Chromium driver. Its primary job is to load Playwright’s Chromium browser, apply a series of stealth patches (via CDP and JS injection), and expose the same API surface as Playwright.

##### File structure
- Top-level files:
- package.json – defines NodeJS package, dependencies, scripts
- patchright_driver_patch.js – main patch engine that applies CDP patches & ExecutionContext injections
- patchright.patch – the set of diffs used to patch Playwright’s driver code
- .github/workflows – CI/CD pipelines for building & publishing releases
- utils/*.sh – helper scripts for performing release tasks (version checks, driver downloads)
- No “src/” or “lib/” directories implies the repo itself is the code.

##### Read README for additional insights
- Explains the specific leaks patched (Runtime.enable, Console.enable, command flags, etc.)
- Mentions integration points: Playwright, Chromium, CDP-Patches, and usage by NodeJS & Python packages
- CI/CD automation for packaging and publishing

##### Main components & their interactions
a. Components:
1. GitHub Repository – source code, patch definitions, CI pipelines
2. CI/CD (GitHub Actions) – triggered on push/tags, runs utils scripts, builds artifacts
3. Release Scripts (utils/*.sh) – fetch Playwright driver, apply patchright.patch, produce patched driver binary & metadata
4. Patch Engine (patchright_driver_patch.js) – at runtime, intercepts Playwright’s CDP calls, injects JS into isolated contexts, disables Console API, tweaks default args
5. External Dependencies – Playwright library, Chromium browser binary, CDP-Patches project
6. Published Packages – NodeJS (npm) and Python (PyPI) wrappers that bundle the patched driver
7. End Users – import patchright-nodejs or patchright-python, run tests or automation scripts

b. Relationships & data flow:
- A developer pushes code → GitHub Actions pipeline triggers → utils scripts download official Playwright driver → patchright.patch is applied → artifacts (patched driver, version manifest) are built → published to GitHub Releases, npm, PyPI.
- At runtime, end users’ test code (using the patchright NodeJS/Python package) invokes the patch engine, which launches a Chromium browser via Playwright → patchright_driver_patch.js intercepts the DevTools Protocol (CDP) calls, applies runtime patches (console-disable, execContext injection), and launches the browser stealthily.

c. Architectural patterns & principles
- Separation of Concerns: build-time patching (scripts + .patch) vs. run-time patching (JS engine)
- Plug-in style: the patch engine wraps Playwright without modifying its public API
- CI/CD as code: workflows codified in .github/workflows

d. Key technologies & libraries
- NodeJS + npm (packaging & runtime)
- GitHub Actions (CI/CD)
- Playwright (automation driver)
- Chromium (browser to be automated)
- CDP-Patches (external patch definitions)
- Bash scripts for release tasks

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "GitHub Repository"
        Repo["GitHub Repository"] 
        PatchEngine["patchright_driver_patch.js"]
        PatchDef["patchright.patch"]
        PackageJSON["package.json"]
        Readme["README.md"]
    end
    Repo --> PatchEngine
    Repo --> PatchDef
    Repo --> PackageJSON
    Repo --> Readme

    subgraph "CI/CD Pipelines"
        PRWork["patchright_workflow.yml"]
        PRRelease["patch_release_workflow.yml"]
    end
    Repo -->|"triggers"| PRWork
    Repo -->|"triggers"| PRRelease

    subgraph "Release Scripts"
        RS1["utils/release_driver.sh"]
        RS2["utils/release_version_check.sh"]
    end
    PRWork -->|"run scripts"| RS1
    PRWork --> RS2
    PRRelease --> RS1
    PRRelease --> RS2

    PatchDef -->|"apply"| RS1
    RS1 -->|"build"| Artifacts["Patched Driver Artifact"]
    
    subgraph "Registries"
        NPM["npm Registry"]
        PYPI["PyPI Registry"]
    end
    Artifacts -->|"publish"| NPM
    Artifacts -->|"publish"| PYPI

    CDPP["CDP-Patches"]
    CDPP --> RS1

    subgraph "Runtime Flow"
        UE["End User Test Code (NodeJS/Python)"]
        PE["Patch Engine (patchright_driver_patch.js)"]
        PL["Playwright Library"]
        CB["Chromium Browser"]
    end
    UE -->|"invoke"| PE
    PE -->|"launch"| PL
    PL -->|"exec"| CB
    PE -->|"inject patches"| CB
    CDPP --> PE

    click Repo "https://github.com/kaliiiiiiiiii-vinyzu/patchright/tree/main//"
    click PatchEngine "https://github.com/kaliiiiiiiiii-vinyzu/patchright/blob/main/patchright_driver_patch.js"
    click PatchDef "https://github.com/kaliiiiiiiiii-vinyzu/patchright/blob/main/patchright.patch"
    click PRWork "https://github.com/kaliiiiiiiiii-vinyzu/patchright/blob/main/.github/workflows/patchright_workflow.yml"
    click PRRelease "https://github.com/kaliiiiiiiiii-vinyzu/patchright/blob/main/.github/workflows/patch_release_workflow.yml"
    click RS1 "https://github.com/kaliiiiiiiiii-vinyzu/patchright/blob/main/utils/release_driver.sh"
    click RS2 "https://github.com/kaliiiiiiiiii-vinyzu/patchright/blob/main/utils/release_version_check.sh"
    click PackageJSON "https://github.com/kaliiiiiiiiii-vinyzu/patchright/blob/main/package.json"
    click Readme "https://github.com/kaliiiiiiiiii-vinyzu/patchright/blob/main/README.md"

    classDef code fill:#D0E8FF,stroke:#333,stroke-width:1px;
    classDef extern fill:#DFFFD0,stroke:#333,stroke-width:1px;
    classDef pipeline fill:#FFE0B2,stroke:#333,stroke-width:1px;
    classDef user fill:#E0E0E0,stroke:#333,stroke-width:1px;

    class Repo,PatchEngine,PatchDef,PackageJSON,Readme,RS1,RS2,PE code;
    class PRWork,PRRelease,Artifacts,NPM,PYPI pipeline;
    class CDPP,PL,CB extern;
    class UE user;
```
