How adguardteam/adguardbrowserextension works
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.