# duckduckgo/trackerradarkit architecture

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

- Interactive diagram: https://gitdiagram.com/duckduckgo/trackerradarkit
- Repository: https://github.com/duckduckgo/trackerradarkit

## Overview

##### Main Components
- Library Core (TrackerRadarKit): This is the heart of the package and contains the primary logic.
- TrackerData: A struct that models the JSON data sourced from DuckDuckGo’s Tracker Radar file.
- ContentBlockerRule: A data structure representing individual web content blocking rules.
- ContentBlockerRulesBuilder: The component that takes in TrackerData and an optional exception list (allowList) and transforms it into a set of content blocker rules.
- Utility Extensions: Files like ArrayExtension.swift, URLExtension.swift, and TrackerException.swift provide helper functionality which supports the core transformation and data handling.

##### Supporting Structures
- Swift Package Manager & Build Files:
- Package.swift: Shows how the package is structured and its dependency, notably the swift-argument-parser.
- .swiftlint.yml: Indicates enforced coding style and conventions.
- Xcode configuration folders (swiftpm/xcode): Infrastructure for building the package in Xcode.
- Validator Tool (Implicit Component):
- Although not directly seen in a separate source file, the README mentions a Validator tool that validates the Tracker Radar data by parsing, transforming, and compiling it into a rule list; this can be represented as a “runtime component” or “utility executable” that operates on the same core logic.
- Testing Suite:
- The Tests directory, which contains unit tests for critical modules (e.g., ArrayExtensionTests, ContentBlockerRulesBuilderTests, URLExtensionTests) along with test utilities and mock data, ensuring correctness.

##### Relationships and Interactions
- Data Flow:
- TrackerData (parsed JSON) → passed to ContentBlockerRulesBuilder.
- ContentBlockerRulesBuilder → processes TrackerData along with any exception/allowList → generates an array of ContentBlockerRule objects.
- Output of ContentBlockerRulesBuilder → encoded as JSON, which is then ultimately used for compiling a content rule list via WKContentRuleListStore.
- External Integration:
- The library serves as a bridge between raw Tracker Radar data and Apple’s WebKit content blocker mechanism.
- Testing & Validation:
- The tests validate the transformation and building process using mock JSON data and targeted test utilities.

##### Architectural Patterns and Design Principles
- Modularization: The project isolates different functionalities into separate files (data model, rule builder, utility extensions) to keep concerns separated.
- Reusability: By offering a Swift package that can be imported into various projects, the design supports extensibility.
- Testability: The clear separation between production code and testing (with dedicated test utilities) supports high test coverage.
- Command-Line/Automation Friendly: The presence of Swift Package Manager configurations as well as integration with GitHub Actions (in the .github folder) indicate a CI/CD-friendly structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Configuration Layer
    subgraph "Build & Configuration"
        BPM["Package.swift"]:::config
        SL[".swiftlint.yml"]:::config
        XCODE["Xcode Config (.swiftpm/xcode)"]:::config
    end

    %% Core Library (TrackerRadarKit)
    subgraph "TrackerRadarKit Core"
        TD["TrackerData"]:::model
        CBRB["ContentBlockerRulesBuilder"]:::logic
        CBR["ContentBlockerRule"]:::model
        subgraph "Utility Extensions"
            AE["ArrayExtension"]:::utility
            UE["URLExtension"]:::utility
            TE["TrackerException"]:::utility
        end
    end

    %% Validator Tool (Command-line Utility)
    VT["Validator Tool"]:::logic

    %% External Integration
    WK["WKContentRuleListStore (External)"]:::integration

    %% Testing Suite
    subgraph "Testing Suite"
        TEST["TrackerRadarKit Tests"]:::test
    end

    %% Data Flow Connections
    TD -->|"parses JSON"| CBRB
    CBRB -->|"builds rules"| CBR
    CBR -->|"encoded as JSON"| WK
    VT -->|"validates data using"| TD
    VT -->|"validates transformation via"| CBRB

    %% Testing connections verifying core modules
    TEST -->|"tests"| TD
    TEST -->|"tests"| CBRB
    TEST -->|"tests"| CBR
    TEST -->|"tests"| AE
    TEST -->|"tests"| UE

    %% Build & Config supports the Core Package
    BPM ---|"configures"| TD
    SL ---|"enforces style for"| TD
    XCODE ---|"builds"| TD

    %% Utility Extensions integration into ContentBlockerRulesBuilder
    AE ---|"provides helper"| CBRB
    UE ---|"provides helper"| CBRB
    TE ---|"provides exception logic"| CBRB

    %% Click Events
    click TD "https://github.com/duckduckgo/trackerradarkit/blob/main/Sources/TrackerRadarKit/TrackerData.swift"
    click CBRB "https://github.com/duckduckgo/trackerradarkit/blob/main/Sources/TrackerRadarKit/ContentBlockerRulesBuilder.swift"
    click CBR "https://github.com/duckduckgo/trackerradarkit/blob/main/Sources/TrackerRadarKit/ContentBlockerRule.swift"
    click AE "https://github.com/duckduckgo/trackerradarkit/blob/main/Sources/TrackerRadarKit/ArrayExtension.swift"
    click UE "https://github.com/duckduckgo/trackerradarkit/blob/main/Sources/TrackerRadarKit/URLExtension.swift"
    click TE "https://github.com/duckduckgo/trackerradarkit/blob/main/Sources/TrackerRadarKit/TrackerException.swift"
    click BPM "https://github.com/duckduckgo/trackerradarkit/blob/main/Package.swift"
    click SL "https://github.com/duckduckgo/trackerradarkit/blob/main/.swiftlint.yml"
    click XCODE "https://github.com/duckduckgo/trackerradarkit/tree/main/.swiftpm/xcode"
    click TEST "https://github.com/duckduckgo/trackerradarkit/tree/main/Tests/TrackerRadarKitTests"

    %% Styles for Nodes
    classDef model fill:#a8d8ea,stroke:#0077b6,stroke-width:2px
    classDef logic fill:#ffb703,stroke:#fb8500,stroke-width:2px
    classDef utility fill:#90be6d,stroke:#43aa8b,stroke-width:2px
    classDef config fill:#f9844a,stroke:#f3722c,stroke-width:2px
    classDef integration fill:#b56576,stroke:#d7263d,stroke-width:2px
    classDef test fill:#f9c74f,stroke:#f9844a,stroke-width:2px
```
