# adguardteam/adguardbrowserextension architecture

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

- Interactive diagram: https://gitdiagram.com/adguardteam/adguardbrowserextension
- Repository: https://github.com/adguardteam/adguardbrowserextension

## Overview

##### Project type and purpose
- From the README and file tree, this is a browser extension (AdGuard) that blocks ads and trackers and provides UI pages (popup, options, filtering log, devtools).
- It is not a web‑server or microservice suite but a packaged client application that runs inside Chromium‑based browsers (MV2/MV3), Firefox, Opera, Edge, etc.

##### File structure
- Top‑level “Extension” directory holds the shipped extension code:
- filters (static filter lists in `.txt`/`.json`),
- pages (popup, options, filtering‑log, devtools‐sidebar, content scripts).
- “src” under Extension contains TypeScript source organized by context:
- background (services, API handlers, storage adapters, filter engine integration),
- content‑script (injected page helpers and message handlers),
- common (shared utilities, messages, browser API wrappers),
- pages (React/Vue components or plain JS for UI pages),
- web‑accessible resources for redirects.
- “tools” holds CLI scripts and bundler configurations for building MV2/MV3 variants, filter conversion, localization, and CI pipelines (in “bamboo‑specs”).
- Configuration files: `tsconfig*.json`, `.eslintrc.cjs`, `postcss.config.js`, `package.json`, lockfile, CI YAML.

##### README for additional insights
- The README emphasizes build targets (dev, beta, release), pipelines (CI/CD with Bamboo), how MV2 and MV3 builds differ, tests (unit + integration), linking with `tsurlfilter` engine, localization workflows, and permissions required for browser APIs.

##### Main components
a. Browser host
- Represents Chrome, Firefox, Edge, Opera instance where the extension runs.
b. Extension contexts
1. Background context
- Persistent or service‑worker script
- Sub‑components:
– Filtering engine (tsurlfilter)
– Storage adapters (browser.storage, IndexedDB, hybrid)
– API handlers (network intercept, settings migrations, safebrowsing)
– UI notification & context menu managers
– Update & filter‑download manager
2. Content scripts
- Inject code into web pages (cosmetic fixes, popup notifications)
- Communicate with background via message passing
3. UI pages (extension UI)
- Popup, Options, Filtering Log, DevTools Sidebar, Fullscreen User Rules, etc.
- Each page is a mini‑SPA built in React/TS/JS, communicates with background via shared messaging API

c. Build & CI pipeline (external tooling)
- Bundler (Webpack + custom scripts) produces browser‑specific builds (MV2 vs MV3 manifests and declarativeNetRequest rules).
- Localization scripts (Crowdin integration).
- CI/CD (Bamboo) orchestrates tests, resource updates, builds, and auto‑publishing to stores.

d. External services & resources
- Filter lists download server (filters, public suffix).
- CrowdIn for translations.
- Browser Web Stores for extension distribution.

##### Relationships and interactions
- Browser host loads extension.
- Background context intercepts webRequests and applies filter rules from the filtering engine.
- Content scripts manipulate DOM or notify users, requesting rules or settings from background.
- UI pages send/receive messages to/from background to read or update settings, custom filters, and display stats.
- Build tools read source code, filter files, localization files, and emit bundles.
- CI/CD pulls code from GitHub, runs tests, updates filters, triggers builds, and deploys to Web Stores.

##### Highlighted architectural patterns and principles
- Modular separation by extension context (background vs content vs UI).
- Message‑based communication for decoupling contexts.
- Adapter layers for storage and browser API to enable MV2/MV3 compatibility.
- Single source of truth for filter engine via shared library (`tsurlfilter`).

##### Essential architectural elements not to omit
- Background context with filter engine and storage adapters.
- Content script message channel.
- UI pages and their communication to background.
- Build process bifurcation (MV2 vs MV3).
- External resource downloads and CI/CD auto‑publishing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Host
    BrowserHost("Browser Host (Chrome/Firefox/Edge/Opera)"):::external

    %% Extension Contexts
    subgraph "Extension Contexts"
        direction TB

        subgraph "Background Context"
            direction TB
            BGCore("Background Context Core"):::component
            Engine("Filtering Engine Integration"):::engine
            Storage("Storage Adapters Layer"):::storage
            API("API Handlers (network, settings, safebrowsing)"):::component
            UISvc("UI Notification & Context‑Menu Services"):::component
            FilterUpdate("Filter Update & Download Manager"):::component
            MsgHandler("Message Handling in Background"):::component
            ConnHandler("Background Connection Handler"):::component
            KeepAlive("Background Keep‑Alive"):::component

            BGCore -->|uses| Engine
            BGCore -->|uses| Storage
            BGCore -->|uses| API
            BGCore -->|uses| UISvc
            BGCore -->|schedules| FilterUpdate
            BGCore -->|handles| MsgHandler
            BGCore -->|manages| ConnHandler
            BGCore -->|keeps alive| KeepAlive
        end

        Content("Content Scripts"):::component
        UIPagesSrc("UI Pages (source)"):::component

        BrowserHost -->|loads extension| BGCore
        BrowserHost -->|injects| Content
        BrowserHost -->|renders| UIPagesSrc

        Content -->|message passing| MsgHandler
        UIPagesSrc -->|message passing| MsgHandler
    end

    %% Static Resources
    subgraph "Static Resources"
        direction TB
        Filters("Static Filter Lists"):::resource
        Assets("Static Assets"):::resource
        WebRes("Web‑Accessible Resources"):::resource
    end

    Filters -->|consumed by| BGCore
    Assets -->|included in| UIPagesSrc
    WebRes -->|included in| UIPagesSrc

    %% UI Pages Built
    UIPagesBuilt("Built UI Pages"):::resource
    UIPagesSrc -->|build output| UIPagesBuilt
    BrowserHost -->|serves| UIPagesBuilt

    %% Build & CI Pipeline
    subgraph "Build & CI Pipeline"
        direction TB
        ToolsBundle("Build & Bundler Configurations"):::pipeline
        ToolsCLI("CLI Scripts & Helpers"):::pipeline
        Locales("Localization Workflow Tools"):::pipeline
        CI("CI/CD Pipeline Definitions"):::pipeline
        Tests("Unit & Integration Tests"):::pipeline

        ToolsBundle -->|bundle source| UIPagesBuilt
        ToolsBundle -->|bundle background| BGCore
        ToolsCLI -->|convert filters| Filters
        Locales -->|translations| UIPagesSrc
        CI -->|runs tests| Tests
        CI -->|triggers| ToolsBundle
        CI -->|publishes to| WebStore
    end

    %% External Services
    subgraph "External Services"
        FilterServer("Filter Lists Server"):::external
        Crowdin("CrowdIn (Localization)"):::external
        WebStore("Browser Web Stores"):::external
    end

    FilterServer -->|provides lists| Filters
    Crowdin -->|provides translations| Locales
    ToolsBundle -->|deploy to| WebStore
    CI -->|auto‑publish to| WebStore

    %% Click Events
    click BGCore "https://github.com/adguardteam/adguardbrowserextension/tree/master/Extension/src/background"
    click Engine "https://github.com/adguardteam/adguardbrowserextension/tree/master/Extension/src/background/engine"
    click Storage "https://github.com/adguardteam/adguardbrowserextension/tree/master/Extension/src/background/storages"
    click API "https://github.com/adguardteam/adguardbrowserextension/tree/master/Extension/src/background/api"
    click UISvc "https://github.com/adguardteam/adguardbrowserextension/tree/master/Extension/src/background/services/ui"
    click FilterUpdate "https://github.com/adguardteam/adguardbrowserextension/blob/master/Extension/src/background/services/filter-update.ts"
    click MsgHandler "https://github.com/adguardteam/adguardbrowserextension/blob/master/Extension/src/background/message-handler.ts"
    click ConnHandler "https://github.com/adguardteam/adguardbrowserextension/blob/master/Extension/src/background/connection-handler.ts"
    click KeepAlive "https://github.com/adguardteam/adguardbrowserextension/blob/master/Extension/src/background/keep-alive.ts"
    click Content "https://github.com/adguardteam/adguardbrowserextension/tree/master/Extension/src/content-script"
    click UIPagesSrc "https://github.com/adguardteam/adguardbrowserextension/tree/master/Extension/src/pages"
    click UIPagesBuilt "https://github.com/adguardteam/adguardbrowserextension/tree/master/Extension/pages"
    click Filters "https://github.com/adguardteam/adguardbrowserextension/tree/master/Extension/filters"
    click Assets "https://github.com/adguardteam/adguardbrowserextension/tree/master/Extension/assets"
    click WebRes "https://github.com/adguardteam/adguardbrowserextension/tree/master/Extension/web-accessible-resources"
    click ToolsBundle "https://github.com/adguardteam/adguardbrowserextension/tree/master/tools/bundle"
    click ToolsCLI "https://github.com/adguardteam/adguardbrowserextension/blob/master/tools/converter.ts"
    click Locales "https://github.com/adguardteam/adguardbrowserextension/tree/master/tools/locales"
    click CI "https://github.com/adguardteam/adguardbrowserextension/tree/master/bamboo-specs"

    %% Styles
    classDef component fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef storage fill:#FFE4B5,stroke:#000,stroke-width:1px;
    classDef resource fill:#E6E6FA,stroke:#000,stroke-width:1px;
    classDef engine fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef pipeline fill:#98FB98,stroke:#000,stroke-width:1px;
    classDef external fill:#F0E68C,stroke:#000,stroke-width:1px;
```
