# simomat/lowcarb architecture

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

- Interactive diagram: https://gitdiagram.com/simomat/lowcarb
- Repository: https://github.com/simomat/lowcarb

## Overview

lowcarb is a Firefox extension for retaining approved cookies while removing others, optionally on browser startup. Users configure retained domains and cleanup settings in the options page, then trigger cleanup manually or let the startup handler invoke it. Cleanup enumerates cookies, applies whitelist and open-tab protections, removes eligible cookies, optionally clears related site data, and may notify the user. The graph includes the options model and sorting UI as a useful internal layer. Source excerpts support the shown calls; other README capabilities are included where documented.

Main entry points: [`src/actions.js`](https://github.com/simomat/lowcarb/blob/main/src/actions.js) (Cleanup Actions), [`src/browser.js`](https://github.com/simomat/lowcarb/blob/main/src/browser.js) (Browser Adapter), [`src/options/index.js`](https://github.com/simomat/lowcarb/blob/main/src/options/index.js) (Options Page), [`src/background.js`](https://github.com/simomat/lowcarb/blob/main/src/background.js) (Background Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Extension Runtime"]
  node_background["Background Handler<br/>[background.js]"]
end

subgraph group_cleanup["Cookie Cleanup"]
  node_actions["Cleanup Actions<br/>[actions.js]"]
  node_cookies["Cookie Access<br/>[cookies.js]"]
  node_tabs["Open Tab Hosts<br/>[tabs.js]"]
  node_site_data["Site Data Removal<br/>[siteData.js]"]
end

subgraph group_options["Options Interface"]
  node_options_page["Options Page<br/>[index.js]"]
  node_domain_model["Domain Model<br/>[domainModel.js]"]
  node_domain_list["Domain List"]
  node_domain_element["Domain Element<br/>[domainElement.js]"]
  node_domain_compare["Domain Sorting<br/>[domaincompare.js]"]
end

subgraph group_platform["Browser Access"]
  node_browser_access["Browser Adapter<br/>[browser.js]"]
  node_sync_storage[("Sync Storage")]
end

node_user(("User"))
node_firefox["Firefox APIs"]
node_startup(("Startup Event"))

node_user -->|"configures"| node_options_page
node_options_page -->|"loads domains"| node_domain_model
node_domain_model -->|"reads whitelist"| node_browser_access
node_domain_model -->|"gets cookies"| node_cookies
node_options_page -->|"updates list"| node_domain_list
node_domain_list -->|"renders entries"| node_domain_element
node_domain_list -->|"sorts domains"| node_domain_compare
node_domain_element -->|"toggles whitelist"| node_actions
node_options_page -->|"starts cleanup"| node_actions
node_options_page -->|"updates settings"| node_browser_access
node_startup -->|"triggers handler"| node_background
node_background -->|"checks settings"| node_browser_access
node_background -->|"runs cleanup"| node_actions
node_background -->|"opens on action"| node_options_page
node_actions -->|"reads cookies"| node_cookies
node_actions -->|"reads settings"| node_browser_access
node_actions -->|"reads whitelist"| node_browser_access
node_actions -->|"gets open hosts"| node_tabs
node_actions -->|"removes site data"| node_site_data
node_cookies -->|"enumerates cookies"| node_browser_access
node_tabs -->|"queries tabs"| node_browser_access
node_site_data -->|"requests data removal"| node_browser_access
node_browser_access -->|"calls browser APIs"| node_firefox
node_browser_access -->|"reads and writes"| node_sync_storage
node_actions -->|"removes cookies"| node_firefox
node_actions -->|"sends notification"| node_browser_access

click node_background "https://github.com/simomat/lowcarb/blob/main/src/background.js"
click node_options_page "https://github.com/simomat/lowcarb/blob/main/src/options/index.js"
click node_domain_model "https://github.com/simomat/lowcarb/blob/main/src/options/domainModel.js"
click node_domain_list "https://github.com/simomat/lowcarb/blob/main/src/options/domainElementList.js"
click node_domain_element "https://github.com/simomat/lowcarb/blob/main/src/options/domainElement.js"
click node_domain_compare "https://github.com/simomat/lowcarb/blob/main/src/options/domaincompare.js"
click node_actions "https://github.com/simomat/lowcarb/blob/main/src/actions.js"
click node_cookies "https://github.com/simomat/lowcarb/blob/main/src/cookies.js"
click node_tabs "https://github.com/simomat/lowcarb/blob/main/src/tabs.js"
click node_site_data "https://github.com/simomat/lowcarb/blob/main/src/siteData.js"
click node_browser_access "https://github.com/simomat/lowcarb/blob/main/src/browser.js"

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_background,node_user toneBlue
class node_actions,node_cookies,node_tabs,node_site_data toneAmber
class node_options_page,node_domain_model,node_domain_list,node_domain_element,node_domain_compare,node_firefox toneMint
class node_browser_access,node_sync_storage toneRose
class node_startup toneIndigo
```

## Components

### Extension Runtime

- [Background Handler](https://github.com/simomat/lowcarb/blob/main/src/background.js): `src/background.js`

### Cookie Cleanup

- [Cleanup Actions](https://github.com/simomat/lowcarb/blob/main/src/actions.js): `src/actions.js`
- [Cookie Access](https://github.com/simomat/lowcarb/blob/main/src/cookies.js): `src/cookies.js`
- [Open Tab Hosts](https://github.com/simomat/lowcarb/blob/main/src/tabs.js): `src/tabs.js`
- [Site Data Removal](https://github.com/simomat/lowcarb/blob/main/src/siteData.js): `src/siteData.js`

### Options Interface

- [Options Page](https://github.com/simomat/lowcarb/blob/main/src/options/index.js): `src/options/index.js`
- [Domain Model](https://github.com/simomat/lowcarb/blob/main/src/options/domainModel.js): `src/options/domainModel.js`
- [Domain List](https://github.com/simomat/lowcarb/blob/main/src/options/domainElementList.js): `src/options/domainElementList.js`
- [Domain Element](https://github.com/simomat/lowcarb/blob/main/src/options/domainElement.js): `src/options/domainElement.js`
- [Domain Sorting](https://github.com/simomat/lowcarb/blob/main/src/options/domaincompare.js): `src/options/domaincompare.js`

### Browser Access

- [Browser Adapter](https://github.com/simomat/lowcarb/blob/main/src/browser.js): `src/browser.js`
- **Sync Storage**

### Other components

- **User**
- **Firefox APIs**
- **Startup Event**

## Connections

- User → Options Page: configures (evidence: `src/options/index.js`)
- Options Page → Domain Model: loads domains (evidence: `src/options/index.js`)
- Domain Model → Browser Adapter: reads whitelist (evidence: `src/options/domainModel.js`)
- Domain Model → Cookie Access: gets cookies (evidence: `src/options/domainModel.js`)
- Options Page → Domain List: updates list (evidence: `src/options/index.js`)
- Domain List → Domain Element: renders entries (evidence: `src/options/domainElementList.js`)
- Domain List → Domain Sorting: sorts domains (evidence: `src/options/domainElementList.js`)
- Domain Element → Cleanup Actions: toggles whitelist (evidence: `src/options/domainElement.js`)
- Options Page → Cleanup Actions: starts cleanup (evidence: `src/options/index.js`)
- Options Page → Browser Adapter: updates settings (evidence: `src/options/index.js`)
- Startup Event → Background Handler: triggers handler (evidence: `src/background.js`)
- Background Handler → Browser Adapter: checks settings (evidence: `src/background.js`)
- Background Handler → Cleanup Actions: runs cleanup (evidence: `src/background.js`)
- Background Handler → Options Page: opens on action
- Cleanup Actions → Cookie Access: reads cookies (evidence: `src/actions.js`)
- Cleanup Actions → Browser Adapter: reads settings (evidence: `src/actions.js`)
- Cleanup Actions → Browser Adapter: reads whitelist (evidence: `src/actions.js`)
- Cleanup Actions → Open Tab Hosts: gets open hosts (evidence: `src/actions.js`)
- Cleanup Actions → Site Data Removal: removes site data (evidence: `src/actions.js`)
- Cookie Access → Browser Adapter: enumerates cookies (evidence: `src/cookies.js`)
- Open Tab Hosts → Browser Adapter: queries tabs (evidence: `src/tabs.js`)
- Site Data Removal → Browser Adapter: requests data removal (evidence: `src/siteData.js`)
- Browser Adapter → Firefox APIs: calls browser APIs (evidence: `src/browser.js`)
- Browser Adapter → Sync Storage: reads and writes (evidence: `src/browser.js`)
- Cleanup Actions → Firefox APIs: removes cookies (evidence: `src/actions.js`)
- Cleanup Actions → Browser Adapter: sends notification (evidence: `src/actions.js`)