# ghostery/adblocker architecture

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

- Interactive diagram: https://gitdiagram.com/ghostery/adblocker
- Repository: https://github.com/ghostery/adblocker

## Overview

##### Main Components Overview

a) Core Engine Layer:
- Main components:
- Filter Engine (src/engine/engine.ts)
- Network Filtering
- Cosmetic Filtering
- HTML Filtering
- Resource Management

b) Platform Integration Layer:
- WebExtension Integration
- Electron Integration
- Puppeteer Integration
- Playwright Integration
- Content Script Integration

c) Filter Processing Pipeline:
Data flow for filter processing:
- Filter Lists Input
- Preprocessing
- Compression
- Optimization
- Storage

##### Component Relationships

- Data flow (→): Filter lists → Engine → Blocking decisions
- Dependencies (⇢): Platform integrations → Core engine
- Event flow (⇄): Content scripts ↔ Background processes

##### Detailed Component Breakdown

For each major component, show:

Core Engine:
**┌─ Engine Core ─────────────┐**
- Filter Matching        │
- Domain Management      │
- Request Processing     │
- Cosmetic Rules        │
- ┘

Platform Integration:
**┌─ Platform Adapters ──────┐**
- WebExtension          │
- Electron              │
- Puppeteer            │
- Playwright           │
- ┘

##### Technical Details

Annotations for:
- TypeScript/JavaScript implementation
- Filter format compatibility (uBlock Origin/Easylist)
- Compression techniques
- Performance metrics

##### Implementation Notes

Callouts for:
- Blazing fast performance
- Minimal memory footprint
- Cross-platform compatibility
- Filter list support

Remember to emphasize the project's key strengths:
- Efficiency and performance
- Cross-platform support
- Modular design
- Filter list compatibility

This will create a comprehensive yet clear representation of the adblocker's architecture that accurately reflects its sophisticated design while remaining accessible to technical stakeholders.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Core["Core Engine Layer"]
        Engine["Filter Engine"]:::core
        Network["Network Filtering"]:::core
        Cosmetic["Cosmetic Filtering"]:::core
        HTML["HTML Filtering"]:::core
        Resources["Resource Management"]:::core
        
        Engine --> Network
        Engine --> Cosmetic
        Engine --> HTML
        Engine --> Resources
    end

    subgraph Platform["Platform Integration Layer"]
        WebExt["WebExtension"]:::platform
        Electron["Electron"]:::platform
        Puppeteer["Puppeteer"]:::platform
        Playwright["Playwright"]:::platform
        Content["Content Script"]:::platform
    end

    subgraph Processing["Filter Processing Pipeline"]
        Lists["Filter Lists"]:::processing
        Preprocess["Preprocessing"]:::processing
        Compress["Compression"]:::processing
        Optimize["Optimization"]:::processing
        Storage["Storage"]:::processing

        Lists --> Preprocess
        Preprocess --> Compress
        Compress --> Optimize
        Optimize --> Storage
    end

    subgraph Components["Engine Components"]
        Domain["Domain Management"]:::component
        Request["Request Processing"]:::component
        NetworkFilters["Network Filters"]:::component
        CosmeticFilters["Cosmetic Filters"]:::component
        FilterDSL["Filter DSL"]:::component
    end

    Processing --> Core
    Core --> Platform
    Components --> Core

    classDef core fill:#2374ab
    classDef platform fill:#57a773
    classDef processing fill:#ff8c42
    classDef component fill:#747474
    
    %% Click events for components
    click Engine "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/engine/engine.ts"
    click Network "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/engine/bucket/network.ts"
    click Cosmetic "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/engine/bucket/cosmetic.ts"
    click HTML "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/html-filtering.ts"
    click Resources "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/resources.ts"
    click WebExt "https://github.com/ghostery/adblocker/blob/master/packages/adblocker-webextension/src/index.ts"
    click Electron "https://github.com/ghostery/adblocker/blob/master/packages/adblocker-electron/src/index.ts"
    click Puppeteer "https://github.com/ghostery/adblocker/blob/master/packages/adblocker-puppeteer/src/index.ts"
    click Playwright "https://github.com/ghostery/adblocker/blob/master/packages/adblocker-playwright/src/index.ts"
    click Content "https://github.com/ghostery/adblocker/blob/master/packages/adblocker-content/src/index.ts"
    click Preprocess "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/engine/bucket/preprocessor.ts"
    click Compress "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/compression.ts"
    click Optimize "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/engine/optimizer.ts"
    click Lists "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/lists.ts"
    click Domain "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/engine/domains.ts"
    click Request "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/request.ts"
    click NetworkFilters "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/filters/network.ts"
    click CosmeticFilters "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/filters/cosmetic.ts"
    click FilterDSL "https://github.com/ghostery/adblocker/blob/master/packages/adblocker/src/filters/dsl.ts"
```
