# adguardteam/contentblocker architecture

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

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

## Overview

##### Project Type and Purpose
- This is an Android application designed to block ads in browsers that support content-blocking (specifically Yandex Browser and Samsung Internet). Its primary function is to filter out unwanted ads by managing and applying filter lists.
- The app is open source and uses the standard Android technology stack (organized with Gradle, resource directories, AndroidManifest, etc).

##### Analyzing the File Structure
- The main code lies in the "adguard_cb" directory. Within it, you have the typical Android structure: an AndroidManifest, "src/main" code (including assets, Java packages, resources, layouts, etc), and test directories.
- Look into “adguard_cb/src/main/java/com/adguard/android/contentblocker” where the code is sub-divided into several packages:
- Packages related to UI (e.g., ui, ui/utils) for activities and dialogs.
- Service layer components (e.g., service, service/job) that encompass background tasks, jobs, notifications, and filter application.
- Data Access Object (DAO) packages and a “db” directory, including classes for managing and accessing the local database (likely built on SQLite).
- Network and API-related classes under “api” and “commons/network” indicate external communications (possibly for updating filters).
- Utility classes such as "BrowserUtils", "PackageUtils", etc.
- You also have test folders (androidTest and unit tests) and configuration/build files showing good practice separation.

##### Elements
- The UI communicates with service components.
- Services interact with the database and the network.
- System events (via BroadcastReceivers) trigger services.
- Jobs (from JobFactory/Worker classes) process tasks asynchronously.

## Diagram (Mermaid)

```mermaid
graph TD
    A("Android App Core"):::core

    subgraph "UI Layer"
        UI1("Activities & Fragments"):::ui
        UI2("Layouts & Resources"):::ui
    end

    subgraph "Service Layer"
        S1("FilterService/JobService/NotificationService"):::service
        S2("Job Subsystem"):::service
    end

    subgraph "Data Layer"
        D1("Local SQLite Database"):::database
        D2("DAO Components"):::database
        D3("SQL Scripts"):::database
    end

    subgraph "Network/API Module"
        N1("HTTP/Service API Clients"):::network
    end

    subgraph "Utility/Concurrency Layer"
        U1("Dispatcher & Executors"):::utility
        U2("Helper Utilities"):::utility
    end

    subgraph "Content Provider"
        CP1("FiltersContentProvider"):::provider
    end

    subgraph "Broadcast Receivers"
        BR1("BootUpReceiver"):::receiver
        BR2("UpdateReceiver"):::receiver
        BR3("StarsCountReceiver"):::receiver
    end

    A --> UI1
    A --> S1
    A --> D1
    A --> N1
    A --> U1
    A --> CP1
    A --> BR1

    UI1 -->|"UserAction"| S1
    UI2 -->|"UserAction"| S1
    S1 -->|"DatabaseQuery"| D1
    S1 -->|"NetworkRequest"| N1
    S1 -->|"AsyncTask"| U1
    BR1 -->|"TriggerService"| S1
    BR2 -->|"TriggerService"| S1
    BR3 -->|"TriggerService"| S1
    CP1 -->|"ExposesContent"| UI1

    %% Click Events
    click A "https://github.com/adguardteam/contentblocker/blob/master/adguard_cb/src/main/AndroidManifest.xml"
    click UI1 "https://github.com/adguardteam/contentblocker/tree/master/adguard_cb/src/main/java/com/adguard/android/contentblocker/ui"
    click UI2 "https://github.com/adguardteam/contentblocker/tree/master/adguard_cb/src/main/res/layout"
    click S1 "https://github.com/adguardteam/contentblocker/tree/master/adguard_cb/src/main/java/com/adguard/android/contentblocker/service"
    click S2 "https://github.com/adguardteam/contentblocker/tree/master/adguard_cb/src/main/java/com/adguard/android/contentblocker/service/job"
    click D1 "https://github.com/adguardteam/contentblocker/tree/master/adguard_cb/src/main/java/com/adguard/android/contentblocker/db"
    click D3 "https://github.com/adguardteam/contentblocker/tree/master/adguard_cb/src/main/res/raw"
    click N1 "https://github.com/adguardteam/contentblocker/tree/master/adguard_cb/src/main/java/com/adguard/android/contentblocker/api"
    click U1 "https://github.com/adguardteam/contentblocker/tree/master/adguard_cb/src/main/java/com/adguard/android/contentblocker/commons/concurrent"
    click U2 "https://github.com/adguardteam/contentblocker/tree/master/adguard_cb/src/main/java/com/adguard/android/contentblocker/commons"
    click CP1 "https://github.com/adguardteam/contentblocker/blob/master/adguard_cb/src/main/java/com/adguard/android/contentblocker/FiltersContentProvider.java"
    click BR1 "https://github.com/adguardteam/contentblocker/tree/master/adguard_cb/src/main/java/com/adguard/android/contentblocker/receiver"

    %% Styles
    classDef core fill:#DDA0DD,stroke:#4B0082,stroke-width:2px;
    classDef ui fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
    classDef service fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef database fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef network fill:#FFA07A,stroke:#FF4500,stroke-width:2px;
    classDef utility fill:#D3D3D3,stroke:#696969,stroke-width:2px;
    classDef provider fill:#F4A460,stroke:#A0522D,stroke-width:2px;
    classDef receiver fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
```
