# agnays/camoufox architecture

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

- Interactive diagram: https://gitdiagram.com/agnays/camoufox
- Repository: https://github.com/agnays/camoufox

## Overview

##### Project Type & Purpose
- Camoufox is an open-source, stealthy custom build of Firefox for web scraping and anti-bot evasion.
- It comprises two main “phases”:
a. Build time: fetch Firefox source, apply patches/additions, produce portable browser bundles.
b. Run time: expose the custom browser via a Python API (Playwright-style) or legacy CLI launcher, plus extensive tests and helper scripts.

A. External Dependencies
- Firefox Source (upstream)
- System Fonts (Windows, macOS, Linux)
- Default Add-ons (uBlock Origin, BPC)

B. Camoufox Repository
1. patches/        ← C++ & JS patches for fingerprint masking, debloat, stealth
2. additions/     ← Branding, Juggler (Playwright backend), browser components
3. assets/        ← Mozconfig files, search config, uBO assets
4. bundle/        ← Bundled fonts & font-config overrides
5. settings/      ← camoufox.cfg, defaults, distribution policies
6. legacy/        ← Deprecated Go-based launcher & loaders
7. pythonlib/     ← Camoufox Python package (sync & async API)
8. jsonvv/        ← JSON-based validator library
9. scripts/       ← Build helpers, packaging, developer UI, examples
10. tests/         ← Pytest suite, test assets, local test server

C. Build System
- Makefile & multibuild.py
- Dockerfile for containerized build
- CI workflow (GitHub Actions)

D. Distribution
- dist/ (outputs of make package-*)
- Portable bundles for Linux, Windows, macOS

E. Run-Time Interfaces
1. Python Interface
– camoufox.server.js ← spawns the browser
– camoufox.sync_api / async_api ← Playwright-style wrappers
– JSON config in memory
2. Legacy CLI Launcher
– launcher executable (Go binary)
– --config, --addons flags
3. Juggler / Playwright Protocol
– WebSocket or Pipe communication
– Dispatcher, Handlers (Page, Browser, Runtime)

F. Tests & Examples
- tests/ driven via pytest
- scripts/examples serve demo pages
- tests spin up testserver.py

##### Relationships & Data Flows
- Build Flow:
Firefox Source + patches/ + additions/ + bundle/ + assets/ → (Make/multibuild.py or Docker) → Portable browser bundles.
- Packaging Flow:
scripts/package.py & Make targets → dist/
- Runtime Flow:
Python API or CLI launcher → spawns Camoufox executable → applies settings from camoufox.cfg → Juggler bridges to Playwright client code → User scripts or tests drive pages.
- Test Flow:
tests/ → import Python API → launch browser → testassets served by tests/server.py → assertions.

##### Architectural Patterns
- Layered architecture:
- “External → Build → Package → Runtime → Client/Test”
- Modular separation:
- Patches, Additions, Assets are orthogonal concerns.
- Python wrapper decouples control logic from browser binary.
- CI/CD integration (GitHub Actions for build & test).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "External Dependencies"
        FirefoxSource[(Firefox Source)]:::external
        SystemFonts[(System Fonts)]:::external
        DefaultAddons[(Default Add-ons)]:::external
    end

    subgraph "Build & Repo Modules"
        patches["patches/"]:::build
        additions_browser["additions/browser/"]:::build
        additions_branding["additions/browser/branding/camoufox/"]:::build
        additions_juggler["additions/juggler/"]:::build
        assets["assets/"]:::build
        bundle["bundle/"]:::build
        settings["settings/"]:::build
        legacy_cli["legacy/launcher/"]:::legacy
        python_core["pythonlib/camoufox/"]:::runtime
        jsonvv["jsonvv/jsonvv/"]:::build
        scripts_all["scripts/"]:::build
    end

    subgraph "Build System"
        Makefile["Makefile"]:::build
        multibuild["multibuild.py"]:::build
        Dockerfile["Dockerfile"]:::build
        CI[".github/workflows/build.yml"]:::build
        upstream["upstream.sh"]:::build
    end

    subgraph "Packaging"
        pkg_script["scripts/package.py"]:::build
        pkg_helper["scripts/package-helper.sh"]:::build
        dist["dist/"]:::build
    end

    subgraph "Distribution Artifacts"
        bundles[(Portable Bundles)]:::build
    end

    subgraph "Run-Time Interfaces"
        cli["Legacy CLI Launcher"]:::legacy
        py_server["pythonlib/camoufox/server.py"]:::runtime
        py_launch_js["pythonlib/camoufox/launchServer.js"]:::runtime
        sync_api["pythonlib/camoufox/sync_api.py"]:::runtime
        async_api["pythonlib/camoufox/async_api.py"]:::runtime
        dispatcher["additions/juggler/protocol/Dispatcher.js"]:::runtime
        pageHandler["additions/juggler/protocol/PageHandler.js"]:::runtime
        browserHandler["additions/juggler/protocol/BrowserHandler.js"]:::runtime
    end

    subgraph "Clients & Tests"
        user_scripts[(User Scripts)]:::external
        pytest["tests/"]:::tests
        test_server["tests/server.py"]:::tests
        test_assets["tests/assets/"]:::tests
        examples["scripts/examples/"]:::build
    end

    FirefoxSource -->|"base source"| Makefile
    patches -->|"apply patches"| Makefile
    additions_browser -->|"include UI additions"| Makefile
    additions_branding -->|"branding"| Makefile
    additions_juggler -->|"include backend"| Makefile
    assets -->|"include assets"| Makefile
    bundle -->|"include bundle"| Makefile
    settings -->|"include settings"| Makefile
    upstream -->|"update source"| FirefoxSource

    Makefile -->|"build bundles"| dist
    multibuild -->|"alternative build"| dist
    Dockerfile -->|"containerized build"| dist
    CI -->|"CI runs build"| dist

    dist -->|"packaging"| pkg_script
    pkg_helper -->|"helper"| dist
    pkg_script --> dist
    dist --> bundles

    user_scripts -->|"drive via API"| sync_api
    user_scripts -->|"drive via API"| async_api
    sync_api --> py_launch_js
    async_api --> py_launch_js
    py_launch_js --> py_server
    py_server --> bundles
    cli --> bundles

    py_server --> dispatcher
    dispatcher --> pageHandler
    dispatcher --> browserHandler
    pageHandler -->|"handle Page events"| py_server
    browserHandler -->|"handle Browser events"| py_server

    pytest -->|"import API"| sync_api
    pytest -->|"import API"| async_api
    pytest --> test_server
    test_server --> test_assets
    test_assets --> py_server
    examples --> user_scripts

    click patches "https://github.com/agnays/camoufox/tree/main/patches/"
    click additions_browser "https://github.com/agnays/camoufox/tree/main/additions/browser/"
    click additions_branding "https://github.com/agnays/camoufox/tree/main/additions/browser/branding/camoufox/"
    click additions_juggler "https://github.com/agnays/camoufox/tree/main/additions/juggler/"
    click assets "https://github.com/agnays/camoufox/tree/main/assets/"
    click bundle "https://github.com/agnays/camoufox/tree/main/bundle/"
    click settings "https://github.com/agnays/camoufox/tree/main/settings/"
    click legacy_cli "https://github.com/agnays/camoufox/tree/main/legacy/launcher/"
    click python_core "https://github.com/agnays/camoufox/tree/main/pythonlib/camoufox/"
    click py_server "https://github.com/agnays/camoufox/blob/main/pythonlib/camoufox/server.py"
    click py_launch_js "https://github.com/agnays/camoufox/blob/main/pythonlib/camoufox/launchServer.js"
    click sync_api "https://github.com/agnays/camoufox/blob/main/pythonlib/camoufox/sync_api.py"
    click async_api "https://github.com/agnays/camoufox/blob/main/pythonlib/camoufox/async_api.py"
    click Makefile "https://github.com/agnays/camoufox/tree/main/Makefile"
    click multibuild "https://github.com/agnays/camoufox/blob/main/multibuild.py"
    click Dockerfile "https://github.com/agnays/camoufox/tree/main/Dockerfile"
    click CI "https://github.com/agnays/camoufox/blob/main/.github/workflows/build.yml"
    click upstream "https://github.com/agnays/camoufox/blob/main/upstream.sh"
    click pkg_script "https://github.com/agnays/camoufox/blob/main/scripts/package.py"
    click pkg_helper "https://github.com/agnays/camoufox/blob/main/scripts/package-helper.sh"
    click dispatcher "https://github.com/agnays/camoufox/blob/main/additions/juggler/protocol/Dispatcher.js"
    click pageHandler "https://github.com/agnays/camoufox/blob/main/additions/juggler/protocol/PageHandler.js"
    click browserHandler "https://github.com/agnays/camoufox/blob/main/additions/juggler/protocol/BrowserHandler.js"
    click pytest "https://github.com/agnays/camoufox/tree/main/tests/"
    click test_server "https://github.com/agnays/camoufox/blob/main/tests/server.py"
    click test_assets "https://github.com/agnays/camoufox/tree/main/tests/assets/"
    click examples "https://github.com/agnays/camoufox/tree/main/scripts/examples/"

    classDef external fill:#D6DBDF,stroke:#333,stroke-width:1px
    classDef build fill:#AED6F1,stroke:#333,stroke-width:1px
    classDef runtime fill:#A9DFBF,stroke:#333,stroke-width:1px
    classDef tests fill:#F9E79F,stroke:#333,stroke-width:1px
    classDef legacy fill:#D5DBDB,stroke:#333,stroke-width:1px
```
