# brave/adblock-rust architecture

> Architecture diagram of the GitHub repository brave/adblock-rust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brave/adblock-rust
- Repository: https://github.com/brave/adblock-rust

## Overview

adblock-rust is an embeddable adblocking engine. A host supplies filter lists and requests; the engine parses and compiles rules, then evaluates network requests and exposes cosmetic-filter results and resource replacements. The README also documents content-blocking conversion, serialized engine data, and language bindings. Edges reflect the excerpts, SOURCE INDEX references, or README; unsampled implementation details are not inferred.

Main entry points: [`src/engine.rs`](https://github.com/brave/adblock-rust/blob/master/src/engine.rs) (Engine API), [`src/blocker.rs`](https://github.com/brave/adblock-rust/blob/master/src/blocker.rs) (Request blocker), [`src/cosmetic_filter_cache.rs`](https://github.com/brave/adblock-rust/blob/master/src/cosmetic_filter_cache.rs) (Cosmetic filter cache), [`src/lists.rs`](https://github.com/brave/adblock-rust/blob/master/src/lists.rs) (Filter list parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Engine API"]
  node_engine["Engine API<br/>[engine.rs]"]
end

subgraph group_rules["Rule Processing"]
  node_filterlists["Filter list parsing<br/>[lists.rs]"]
  node_networkrules["Network rule parsing<br/>[network.rs]"]
  node_cosmeticrules["Cosmetic rule parsing<br/>[cosmetic.rs]"]
  node_networkbuilder["Network compilation"]
  node_cosmeticbuilder["Cosmetic compilation"]
end

subgraph group_matching["Matching and Results"]
  node_blocker["Request blocker<br/>[blocker.rs]"]
  node_request["Request model<br/>[request.rs]"]
  node_networklist["Network filter list"]
  node_regex["Regex management<br/>[regex_manager.rs]"]
  node_cosmeticcache["Cosmetic filter cache"]
  node_cosmeticutils["Cosmetic utilities"]
  node_urlparser["URL parsing<br/>[mod.rs]"]
end

subgraph group_storage["Data and Resources"]
  node_resource["Resource replacements<br/>[mod.rs]"]
  node_resourcebackend["Resource storage"]
  node_datformat["Engine serialization<br/>[mod.rs]"]
  node_flatbuffer["Flatbuffer context"]
end

subgraph group_integrations["Host Integrations"]
  node_jsbinding["JavaScript bindings<br/>[lib.rs]"]
  node_contentblocking["Content-blocking conversion"]
end

node_host(("Embedding host"))

node_host -->|"uses"| node_engine
node_engine -->|"parses lists"| node_filterlists
node_filterlists -->|"parses network rules"| node_networkrules
node_filterlists -->|"parses cosmetic rules"| node_cosmeticrules
node_engine -->|"compiles rules"| node_networkbuilder
node_engine -->|"builds cache"| node_cosmeticbuilder
node_engine -->|"configures"| node_blocker
node_engine -->|"serializes engine"| node_datformat
node_engine -->|"exports rules"| node_contentblocking
node_engine -->|"queries cosmetics"| node_cosmeticcache
node_blocker -->|"uses filters"| node_networklist
node_blocker -->|"matches request"| node_request
node_blocker -->|"manages regexes"| node_regex
node_cosmeticcache -->|"uses rules"| node_cosmeticrules
node_cosmeticcache -->|"uses utilities"| node_cosmeticutils
node_cosmeticcache -->|"resolves resources"| node_resource
node_resource -->|"uses storage"| node_resourcebackend
node_engine -->|"holds filter data"| node_flatbuffer
node_host -->|"calls binding"| node_jsbinding
node_request -->|"parses URL"| node_urlparser
node_host -->|"provides replacements"| node_resource

click node_engine "https://github.com/brave/adblock-rust/blob/master/src/engine.rs"
click node_jsbinding "https://github.com/brave/adblock-rust/blob/master/js/src/lib.rs"
click node_filterlists "https://github.com/brave/adblock-rust/blob/master/src/lists.rs"
click node_networkrules "https://github.com/brave/adblock-rust/blob/master/src/filters/network.rs"
click node_cosmeticrules "https://github.com/brave/adblock-rust/blob/master/src/filters/cosmetic.rs"
click node_networkbuilder "https://github.com/brave/adblock-rust/blob/master/src/filters/fb_network_builder.rs"
click node_cosmeticbuilder "https://github.com/brave/adblock-rust/blob/master/src/cosmetic_filter_cache_builder.rs"
click node_blocker "https://github.com/brave/adblock-rust/blob/master/src/blocker.rs"
click node_request "https://github.com/brave/adblock-rust/blob/master/src/request.rs"
click node_networklist "https://github.com/brave/adblock-rust/blob/master/src/network_filter_list.rs"
click node_regex "https://github.com/brave/adblock-rust/blob/master/src/regex_manager.rs"
click node_cosmeticcache "https://github.com/brave/adblock-rust/blob/master/src/cosmetic_filter_cache.rs"
click node_cosmeticutils "https://github.com/brave/adblock-rust/blob/master/src/cosmetic_filter_utils.rs"
click node_resource "https://github.com/brave/adblock-rust/blob/master/src/resources/mod.rs"
click node_resourcebackend "https://github.com/brave/adblock-rust/blob/master/src/resources/resource_storage.rs"
click node_datformat "https://github.com/brave/adblock-rust/blob/master/src/data_format/mod.rs"
click node_flatbuffer "https://github.com/brave/adblock-rust/blob/master/src/filters/filter_data_context.rs"
click node_contentblocking "https://github.com/brave/adblock-rust/blob/master/src/content_blocking.rs"
click node_urlparser "https://github.com/brave/adblock-rust/blob/master/src/url_parser/mod.rs"

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_engine toneBlue
class node_filterlists,node_networkrules,node_cosmeticrules,node_networkbuilder,node_cosmeticbuilder toneAmber
class node_blocker,node_request,node_networklist,node_regex,node_cosmeticcache,node_cosmeticutils,node_urlparser toneMint
class node_resource,node_resourcebackend,node_datformat,node_flatbuffer toneRose
class node_jsbinding,node_contentblocking,node_host toneIndigo
```

## Components

### Engine API

- [Engine API](https://github.com/brave/adblock-rust/blob/master/src/engine.rs): `src/engine.rs`

### Rule Processing

- [Filter list parsing](https://github.com/brave/adblock-rust/blob/master/src/lists.rs): `src/lists.rs`
- [Network rule parsing](https://github.com/brave/adblock-rust/blob/master/src/filters/network.rs): `src/filters/network.rs`
- [Cosmetic rule parsing](https://github.com/brave/adblock-rust/blob/master/src/filters/cosmetic.rs): `src/filters/cosmetic.rs`
- [Network compilation](https://github.com/brave/adblock-rust/blob/master/src/filters/fb_network_builder.rs): `src/filters/fb_network_builder.rs`
- [Cosmetic compilation](https://github.com/brave/adblock-rust/blob/master/src/cosmetic_filter_cache_builder.rs): `src/cosmetic_filter_cache_builder.rs`

### Matching and Results

- [Request blocker](https://github.com/brave/adblock-rust/blob/master/src/blocker.rs): `src/blocker.rs`
- [Request model](https://github.com/brave/adblock-rust/blob/master/src/request.rs): `src/request.rs`
- [Network filter list](https://github.com/brave/adblock-rust/blob/master/src/network_filter_list.rs): `src/network_filter_list.rs`
- [Regex management](https://github.com/brave/adblock-rust/blob/master/src/regex_manager.rs): `src/regex_manager.rs`
- [Cosmetic filter cache](https://github.com/brave/adblock-rust/blob/master/src/cosmetic_filter_cache.rs): `src/cosmetic_filter_cache.rs`
- [Cosmetic utilities](https://github.com/brave/adblock-rust/blob/master/src/cosmetic_filter_utils.rs): `src/cosmetic_filter_utils.rs`
- [URL parsing](https://github.com/brave/adblock-rust/blob/master/src/url_parser/mod.rs): `src/url_parser/mod.rs`

### Data and Resources

- [Resource replacements](https://github.com/brave/adblock-rust/blob/master/src/resources/mod.rs): `src/resources/mod.rs`
- [Resource storage](https://github.com/brave/adblock-rust/blob/master/src/resources/resource_storage.rs): `src/resources/resource_storage.rs`
- [Engine serialization](https://github.com/brave/adblock-rust/blob/master/src/data_format/mod.rs): `src/data_format/mod.rs`
- [Flatbuffer context](https://github.com/brave/adblock-rust/blob/master/src/filters/filter_data_context.rs): `src/filters/filter_data_context.rs`

### Host Integrations

- [JavaScript bindings](https://github.com/brave/adblock-rust/blob/master/js/src/lib.rs): `js/src/lib.rs`
- [Content-blocking conversion](https://github.com/brave/adblock-rust/blob/master/src/content_blocking.rs): `src/content_blocking.rs`

### Other components

- **Embedding host**

## Connections

- Embedding host → Engine API: uses
- Engine API → Filter list parsing: parses lists (evidence: `src/engine.rs`)
- Filter list parsing → Network rule parsing: parses network rules (evidence: `src/lists.rs`)
- Filter list parsing → Cosmetic rule parsing: parses cosmetic rules (evidence: `src/lists.rs`)
- Engine API → Network compilation: compiles rules (evidence: `src/engine.rs`)
- Engine API → Cosmetic compilation: builds cache (evidence: `src/engine.rs`)
- Engine API → Request blocker: configures (evidence: `src/engine.rs`)
- Engine API → Engine serialization: serializes engine (evidence: `src/engine.rs`)
- Engine API → Content-blocking conversion: exports rules
- Engine API → Cosmetic filter cache: queries cosmetics (evidence: `src/engine.rs`)
- Request blocker → Network filter list: uses filters (evidence: `src/blocker.rs`)
- Request blocker → Request model: matches request (evidence: `src/blocker.rs`)
- Request blocker → Regex management: manages regexes (evidence: `src/blocker.rs`)
- Cosmetic filter cache → Cosmetic rule parsing: uses rules (evidence: `src/cosmetic_filter_cache.rs`)
- Cosmetic filter cache → Cosmetic utilities: uses utilities (evidence: `src/cosmetic_filter_cache.rs`)
- Cosmetic filter cache → Resource replacements: resolves resources (evidence: `src/cosmetic_filter_cache.rs`)
- Resource replacements → Resource storage: uses storage (evidence: `src/resources/mod.rs`)
- Engine API → Flatbuffer context: holds filter data (evidence: `src/engine.rs`)
- Embedding host → JavaScript bindings: calls binding
- Request model → URL parsing: parses URL (evidence: `src/request.rs`)
- Embedding host → Resource replacements: provides replacements
