# aakashkardam/twintabtracker architecture

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

- Interactive diagram: https://gitdiagram.com/aakashkardam/twintabtracker
- Repository: https://github.com/aakashkardam/twintabtracker

## Overview

TwinTabTracker is a local-first browser extension for finding and switching to open tabs, managing duplicate copies, and parking pages for later. The principal workflow runs from the popup or dashboard through shared inventory and duplicate detection, then user actions perform cleanup or parking and persist the resulting state locally. The dashboard also exposes parked-tab management and settings; a background service worker supports browser-level behavior. Relationships below are limited to sampled source references and README statements, so unsampled implementations are represented only where the tree or documentation supports them.

Main entry points: [`src/ui/actions.ts`](https://github.com/aakashkardam/twintabtracker/blob/main/src/ui/actions.ts) (User actions), [`src/shared/browser/adapter.ts`](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/browser/adapter.ts) (Browser adapter), [`src/shared/inventory/service.ts`](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/inventory/service.ts) (Tab inventory), [`src/popup/PopupApp.tsx`](https://github.com/aakashkardam/twintabtracker/blob/main/src/popup/PopupApp.tsx) (Toolbar popup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["Extension surfaces"]
  node_popup["Toolbar popup<br/>[PopupApp.tsx]"]
  node_dashboard["Dashboard<br/>[DashboardApp.tsx]"]
  node_parkedview["Parked tabs view<br/>[ParkedView.tsx]"]
  node_settingsview["Settings view<br/>[SettingsView.tsx]"]
  node_searchbox["Tab search<br/>[SearchBox.tsx]"]
end

subgraph group_domain["Tab workflows"]
  node_actions["User actions<br/>[actions.ts]"]
  node_inventoryhook["Inventory hook<br/>[useInventory.ts]"]
  node_inventory["Tab inventory<br/>[service.ts]"]
  node_tabmapping["Tab mapping<br/>[map.ts]"]
  node_duplicates["Duplicate detection<br/>[detect.ts]"]
  node_cleanupplan["Cleanup planning<br/>[plan.ts]"]
  node_cleanup["Cleanup execution<br/>[execute.ts]"]
  node_undo["Cleanup undo<br/>[undo.ts]"]
  node_parking["Parking operations<br/>[operations.ts]"]
  node_parkexport["Parked data export<br/>[export.ts]"]
end

subgraph group_platform["Browser and state"]
  node_browser["Browser adapter<br/>[adapter.ts]"]
  node_storageclient["Storage client<br/>[client.ts]"]
  node_localstate[("Extension local state")]
  node_settingshook["Settings hook<br/>[useSettings.ts]"]
end

subgraph group_background["Background behavior"]
  node_serviceworker["Background service worker<br/>[service-worker.ts]"]
  node_prevention["Duplicate prevention<br/>[prevention.ts]"]
  node_badge["Duplicate badge<br/>[badge.ts]"]
end

node_user(("Browser user"))

node_user -->|"opens"| node_popup
node_user -->|"opens"| node_dashboard
node_popup -->|"invokes"| node_actions
node_dashboard -->|"invokes"| node_actions
node_dashboard -->|"loads"| node_inventoryhook
node_dashboard -->|"renders"| node_searchbox
node_popup -->|"loads"| node_inventoryhook
node_popup -->|"renders"| node_searchbox
node_searchbox -->|"offers results"| node_user
node_inventoryhook -->|"loads and subscribes"| node_inventory
node_inventoryhook -->|"detects groups"| node_duplicates
node_inventory -->|"queries and listens"| node_browser
node_inventory -->|"maps tabs"| node_tabmapping
node_tabmapping -->|"maps browser data"| node_browser
node_actions -->|"plans cleanup"| node_cleanupplan
node_actions -->|"executes cleanup"| node_cleanup
node_actions -->|"undoes cleanup"| node_undo
node_actions -->|"parks tabs"| node_parking
node_actions -->|"activates and closes"| node_browser
node_actions -->|"persists actions"| node_storageclient
node_cleanupplan -->|"previews targets"| node_user
node_user -->|"manages parked tabs"| node_parkedview
node_parkedview -->|"manages entries"| node_parking
node_parkedview -->|"exports entries"| node_parkexport
node_settingsview -->|"edits settings"| node_settingshook
node_settingshook -->|"reads and updates"| node_storageclient
node_storageclient -->|"uses storage API"| node_browser
node_browser -->|"reads and writes"| node_localstate
node_serviceworker -->|"uses adapter"| node_browser
node_serviceworker -->|"registers behavior"| node_prevention
node_serviceworker -->|"updates badge"| node_badge
node_prevention -->|"checks inventory"| node_inventory
node_prevention -->|"checks duplicates"| node_duplicates
node_badge -->|"loads tabs"| node_inventory
node_badge -->|"counts duplicates"| node_duplicates

click node_popup "https://github.com/aakashkardam/twintabtracker/blob/main/src/popup/PopupApp.tsx"
click node_dashboard "https://github.com/aakashkardam/twintabtracker/blob/main/src/dashboard/DashboardApp.tsx"
click node_parkedview "https://github.com/aakashkardam/twintabtracker/blob/main/src/dashboard/ParkedView.tsx"
click node_settingsview "https://github.com/aakashkardam/twintabtracker/blob/main/src/dashboard/SettingsView.tsx"
click node_searchbox "https://github.com/aakashkardam/twintabtracker/blob/main/src/ui/components/SearchBox.tsx"
click node_actions "https://github.com/aakashkardam/twintabtracker/blob/main/src/ui/actions.ts"
click node_inventoryhook "https://github.com/aakashkardam/twintabtracker/blob/main/src/ui/hooks/useInventory.ts"
click node_inventory "https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/inventory/service.ts"
click node_tabmapping "https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/tabs/map.ts"
click node_duplicates "https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/duplicates/detect.ts"
click node_cleanupplan "https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/duplicates/plan.ts"
click node_cleanup "https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/cleanup/execute.ts"
click node_undo "https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/cleanup/undo.ts"
click node_parking "https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/park/operations.ts"
click node_parkexport "https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/park/export.ts"
click node_browser "https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/browser/adapter.ts"
click node_storageclient "https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/storage/client.ts"
click node_settingshook "https://github.com/aakashkardam/twintabtracker/blob/main/src/ui/hooks/useSettings.ts"
click node_serviceworker "https://github.com/aakashkardam/twintabtracker/blob/main/src/background/service-worker.ts"
click node_prevention "https://github.com/aakashkardam/twintabtracker/blob/main/src/background/prevention.ts"
click node_badge "https://github.com/aakashkardam/twintabtracker/blob/main/src/background/badge.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_popup,node_dashboard,node_parkedview,node_settingsview,node_searchbox,node_user toneBlue
class node_actions,node_inventoryhook,node_inventory,node_tabmapping,node_duplicates,node_cleanupplan,node_cleanup,node_undo,node_parking,node_parkexport toneAmber
class node_browser,node_storageclient,node_localstate,node_settingshook toneMint
class node_serviceworker,node_prevention,node_badge toneRose
```

## Components

### Extension surfaces

- [Toolbar popup](https://github.com/aakashkardam/twintabtracker/blob/main/src/popup/PopupApp.tsx): `src/popup/PopupApp.tsx`
- [Dashboard](https://github.com/aakashkardam/twintabtracker/blob/main/src/dashboard/DashboardApp.tsx): `src/dashboard/DashboardApp.tsx`
- [Parked tabs view](https://github.com/aakashkardam/twintabtracker/blob/main/src/dashboard/ParkedView.tsx): `src/dashboard/ParkedView.tsx`
- [Settings view](https://github.com/aakashkardam/twintabtracker/blob/main/src/dashboard/SettingsView.tsx): `src/dashboard/SettingsView.tsx`
- [Tab search](https://github.com/aakashkardam/twintabtracker/blob/main/src/ui/components/SearchBox.tsx): `src/ui/components/SearchBox.tsx`

### Tab workflows

- [User actions](https://github.com/aakashkardam/twintabtracker/blob/main/src/ui/actions.ts): `src/ui/actions.ts`
- [Inventory hook](https://github.com/aakashkardam/twintabtracker/blob/main/src/ui/hooks/useInventory.ts): `src/ui/hooks/useInventory.ts`
- [Tab inventory](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/inventory/service.ts): `src/shared/inventory/service.ts`
- [Tab mapping](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/tabs/map.ts): `src/shared/tabs/map.ts`
- [Duplicate detection](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/duplicates/detect.ts): `src/shared/duplicates/detect.ts`
- [Cleanup planning](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/duplicates/plan.ts): `src/shared/duplicates/plan.ts`
- [Cleanup execution](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/cleanup/execute.ts): `src/shared/cleanup/execute.ts`
- [Cleanup undo](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/cleanup/undo.ts): `src/shared/cleanup/undo.ts`
- [Parking operations](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/park/operations.ts): `src/shared/park/operations.ts`
- [Parked data export](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/park/export.ts): `src/shared/park/export.ts`

### Browser and state

- [Browser adapter](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/browser/adapter.ts): `src/shared/browser/adapter.ts`
- [Storage client](https://github.com/aakashkardam/twintabtracker/blob/main/src/shared/storage/client.ts): `src/shared/storage/client.ts`
- **Extension local state**
- [Settings hook](https://github.com/aakashkardam/twintabtracker/blob/main/src/ui/hooks/useSettings.ts): `src/ui/hooks/useSettings.ts`

### Background behavior

- [Background service worker](https://github.com/aakashkardam/twintabtracker/blob/main/src/background/service-worker.ts): `src/background/service-worker.ts`
- [Duplicate prevention](https://github.com/aakashkardam/twintabtracker/blob/main/src/background/prevention.ts): `src/background/prevention.ts`
- [Duplicate badge](https://github.com/aakashkardam/twintabtracker/blob/main/src/background/badge.ts): `src/background/badge.ts`

### Other components

- **Browser user**

## Connections

- Browser user → Toolbar popup: opens
- Browser user → Dashboard: opens
- Toolbar popup → User actions: invokes (evidence: `src/popup/PopupApp.tsx`)
- Dashboard → User actions: invokes (evidence: `src/dashboard/DashboardApp.tsx`)
- Dashboard → Inventory hook: loads (evidence: `src/dashboard/DashboardApp.tsx`)
- Dashboard → Tab search: renders (evidence: `src/dashboard/DashboardApp.tsx`)
- Toolbar popup → Inventory hook: loads (evidence: `src/popup/PopupApp.tsx`)
- Toolbar popup → Tab search: renders (evidence: `src/popup/PopupApp.tsx`)
- Tab search → Browser user: offers results (evidence: `src/ui/components/SearchBox.tsx`)
- Inventory hook → Tab inventory: loads and subscribes (evidence: `src/ui/hooks/useInventory.ts`)
- Inventory hook → Duplicate detection: detects groups (evidence: `src/ui/hooks/useInventory.ts`)
- Tab inventory → Browser adapter: queries and listens (evidence: `src/shared/inventory/service.ts`)
- Tab inventory → Tab mapping: maps tabs (evidence: `src/shared/inventory/service.ts`)
- Tab mapping → Browser adapter: maps browser data (evidence: `src/shared/tabs/map.ts`)
- User actions → Cleanup planning: plans cleanup (evidence: `src/ui/actions.ts`)
- User actions → Cleanup execution: executes cleanup (evidence: `src/ui/actions.ts`)
- User actions → Cleanup undo: undoes cleanup (evidence: `src/ui/actions.ts`)
- User actions → Parking operations: parks tabs (evidence: `src/ui/actions.ts`)
- User actions → Browser adapter: activates and closes (evidence: `src/ui/actions.ts`)
- User actions → Storage client: persists actions (evidence: `src/ui/actions.ts`)
- Cleanup planning → Browser user: previews targets
- Browser user → Parked tabs view: manages parked tabs
- Parked tabs view → Parking operations: manages entries (evidence: `src/dashboard/ParkedView.tsx`)
- Parked tabs view → Parked data export: exports entries (evidence: `src/dashboard/ParkedView.tsx`)
- Settings view → Settings hook: edits settings
- Settings hook → Storage client: reads and updates (evidence: `src/ui/hooks/useSettings.ts`)
- Storage client → Browser adapter: uses storage API (evidence: `src/shared/storage/client.ts`)
- Browser adapter → Extension local state: reads and writes (evidence: `src/shared/browser/adapter.ts`)
- Background service worker → Browser adapter: uses adapter (evidence: `src/background/service-worker.ts`)
- Background service worker → Duplicate prevention: registers behavior (evidence: `src/background/service-worker.ts`)
- Background service worker → Duplicate badge: updates badge (evidence: `src/background/service-worker.ts`)
- Duplicate prevention → Tab inventory: checks inventory (evidence: `src/background/prevention.ts`)
- Duplicate prevention → Duplicate detection: checks duplicates (evidence: `src/background/prevention.ts`)
- Duplicate badge → Tab inventory: loads tabs (evidence: `src/background/badge.ts`)
- Duplicate badge → Duplicate detection: counts duplicates (evidence: `src/background/badge.ts`)