# renattt121/aggle architecture

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

- Interactive diagram: https://gitdiagram.com/renattt121/aggle
- Repository: https://github.com/renattt121/aggle

## Overview

Aggle is a browser-extension companion that combines network ad blocking, an AI sidebar, browser settings and resource profiles, and supporting new-tab, command-palette, and stats surfaces. The main user workflows are configuring features in Options and using the sidebar to chat with an AI provider, optionally with page context; the background coordinates blocker startup and extension messages. The graph includes major features visible in the tree, but unsampled new-tab and stats internals are not inferred. Edges reflect the provided excerpts or SOURCE INDEX references.

Main entry points: [`aggle/extension/src/sidebar/panel.ts`](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/panel.ts) (Sidebar panel), [`aggle/extension/src/blocker/engine.ts`](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/blocker/engine.ts) (Request blocker), [`aggle/extension/src/utils/storage.ts`](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/utils/storage.ts) (Settings storage), [`aggle/extension/src/background.ts`](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/background.ts) (Background router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_blocking["Network blocking"]
  node_filterlists["Bundled filters<br/>[lists.ts]"]
  node_parser["Filter parser<br/>[parser.ts]"]
  node_engine["Request blocker<br/>[engine.ts]"]
  node_blockerui["Blocker controls<br/>[ui.ts]"]
end

subgraph group_assistant["AI sidebar"]
  node_panel["Sidebar panel<br/>[panel.ts]"]
  node_chat["Chat builder<br/>[chat.ts]"]
  node_providers["Provider registry<br/>[registry.ts]"]
  node_client["Streaming client<br/>[client.ts]"]
  node_markdown["Markdown renderer<br/>[markdown.ts]"]
end

subgraph group_settings["Settings and profiles"]
  node_options["Options UI<br/>[options.ts]"]
  node_prefs["User.js preferences<br/>[prefs.ts]"]
end

subgraph group_surfaces["Browser surfaces"]
  node_content["Page context script<br/>[content.ts]"]
  node_palette["Command palette<br/>[palette.ts]"]
  node_newtab["Custom new tab<br/>[newtab.ts]"]
  node_stats["Stats dashboard<br/>[dashboard.ts]"]
end

subgraph group_shared["Shared runtime"]
  node_background["Background router<br/>[background.ts]"]
  node_storageutil["Settings storage<br/>[storage.ts]"]
  node_store[("Extension local storage")]
end

node_user(("Extension user"))
node_browser["Browser runtime"]
node_ai["AI provider APIs"]

node_user -->|"configures"| node_options
node_options -->|"loads and saves"| node_storageutil
node_options -->|"generates snippet"| node_prefs
node_storageutil -->|"reads and writes"| node_store
node_background -->|"initializes"| node_engine
node_background -->|"refreshes badge"| node_blockerui
node_engine -->|"loads settings"| node_storageutil
node_engine -->|"parses filters"| node_parser
node_engine -->|"uses bundled rules"| node_filterlists
node_engine -->|"intercepts requests"| node_browser
node_engine -->|"writes block stats"| node_store
node_user -->|"uses sidebar"| node_panel
node_panel -->|"loads and persists"| node_storageutil
node_panel -->|"selects provider"| node_providers
node_panel -->|"streams chat"| node_client
node_panel -->|"builds messages"| node_chat
node_panel -->|"renders responses"| node_markdown
node_panel -->|"extracts page context"| node_content
node_client -->|"sends chat requests"| node_ai
node_providers -->|"loads custom providers"| node_storageutil
node_content -->|"uses palette"| node_palette
node_background -->|"opens dashboard"| node_stats
node_stats -->|"reads stats data"| node_storageutil
node_user -.->|"opens new tab"| node_newtab

click node_filterlists "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/blocker/lists.ts"
click node_parser "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/blocker/parser.ts"
click node_engine "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/blocker/engine.ts"
click node_blockerui "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/blocker/ui.ts"
click node_background "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/background.ts"
click node_panel "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/panel.ts"
click node_chat "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/chat.ts"
click node_providers "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/providers/registry.ts"
click node_client "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/client.ts"
click node_markdown "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/markdown.ts"
click node_content "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/content.ts"
click node_palette "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/palette.ts"
click node_newtab "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/newtab/newtab.ts"
click node_options "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/options/options.ts"
click node_prefs "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/utils/prefs.ts"
click node_stats "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/stats/dashboard.ts"
click node_storageutil "https://github.com/renattt121/aggle/blob/main/aggle/extension/src/utils/storage.ts"

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_filterlists,node_parser,node_engine,node_blockerui,node_user,node_browser toneBlue
class node_panel,node_chat,node_providers,node_client,node_markdown toneAmber
class node_options,node_prefs,node_ai toneMint
class node_content,node_palette,node_newtab,node_stats toneRose
class node_background,node_storageutil,node_store toneIndigo
```

## Components

### Network blocking

- [Bundled filters](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/blocker/lists.ts): `aggle/extension/src/blocker/lists.ts`
- [Filter parser](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/blocker/parser.ts): `aggle/extension/src/blocker/parser.ts`
- [Request blocker](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/blocker/engine.ts): `aggle/extension/src/blocker/engine.ts`
- [Blocker controls](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/blocker/ui.ts): `aggle/extension/src/blocker/ui.ts`

### AI sidebar

- [Sidebar panel](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/panel.ts): `aggle/extension/src/sidebar/panel.ts`
- [Chat builder](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/chat.ts): `aggle/extension/src/sidebar/chat.ts`
- [Provider registry](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/providers/registry.ts): `aggle/extension/src/sidebar/providers/registry.ts`
- [Streaming client](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/client.ts): `aggle/extension/src/sidebar/client.ts`
- [Markdown renderer](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/markdown.ts): `aggle/extension/src/sidebar/markdown.ts`

### Settings and profiles

- [Options UI](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/options/options.ts): `aggle/extension/src/options/options.ts`
- [User.js preferences](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/utils/prefs.ts): `aggle/extension/src/utils/prefs.ts`

### Browser surfaces

- [Page context script](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/content.ts): `aggle/extension/src/content.ts`
- [Command palette](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/sidebar/palette.ts): `aggle/extension/src/sidebar/palette.ts`
- [Custom new tab](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/newtab/newtab.ts): `aggle/extension/src/newtab/newtab.ts`
- [Stats dashboard](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/stats/dashboard.ts): `aggle/extension/src/stats/dashboard.ts`

### Shared runtime

- [Background router](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/background.ts): `aggle/extension/src/background.ts`
- [Settings storage](https://github.com/renattt121/aggle/blob/main/aggle/extension/src/utils/storage.ts): `aggle/extension/src/utils/storage.ts`
- **Extension local storage**

### Other components

- **Extension user**
- **Browser runtime**
- **AI provider APIs**

## Connections

- Extension user → Options UI: configures
- Options UI → Settings storage: loads and saves (evidence: `aggle/extension/src/options/options.ts`)
- Options UI → User.js preferences: generates snippet (evidence: `aggle/extension/src/options/options.ts`)
- Settings storage → Extension local storage: reads and writes (evidence: `aggle/extension/src/utils/storage.ts`)
- Background router → Request blocker: initializes (evidence: `aggle/extension/src/background.ts`)
- Background router → Blocker controls: refreshes badge (evidence: `aggle/extension/src/background.ts`)
- Request blocker → Settings storage: loads settings (evidence: `aggle/extension/src/blocker/engine.ts`)
- Request blocker → Filter parser: parses filters (evidence: `aggle/extension/src/blocker/engine.ts`)
- Request blocker → Bundled filters: uses bundled rules (evidence: `aggle/extension/src/blocker/engine.ts`)
- Request blocker → Browser runtime: intercepts requests (evidence: `aggle/extension/src/blocker/engine.ts`)
- Request blocker → Extension local storage: writes block stats (evidence: `aggle/extension/src/blocker/engine.ts`)
- Extension user → Sidebar panel: uses sidebar
- Sidebar panel → Settings storage: loads and persists (evidence: `aggle/extension/src/sidebar/panel.ts`)
- Sidebar panel → Provider registry: selects provider (evidence: `aggle/extension/src/sidebar/panel.ts`)
- Sidebar panel → Streaming client: streams chat (evidence: `aggle/extension/src/sidebar/panel.ts`)
- Sidebar panel → Chat builder: builds messages (evidence: `aggle/extension/src/sidebar/panel.ts`)
- Sidebar panel → Markdown renderer: renders responses (evidence: `aggle/extension/src/sidebar/panel.ts`)
- Sidebar panel → Page context script: extracts page context (evidence: `aggle/extension/src/sidebar/panel.ts`)
- Streaming client → AI provider APIs: sends chat requests (evidence: `aggle/extension/src/sidebar/client.ts`)
- Provider registry → Settings storage: loads custom providers (evidence: `aggle/extension/src/sidebar/providers/registry.ts`)
- Page context script → Command palette: uses palette (evidence: `aggle/extension/src/content.ts`)
- Background router → Stats dashboard: opens dashboard (evidence: `aggle/extension/src/background.ts`)
- Stats dashboard → Settings storage: reads stats data (evidence: `aggle/extension/src/stats/dashboard.ts`)
- Extension user → Custom new tab: opens new tab
