# rajeshpatel07/scythe architecture

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

- Interactive diagram: https://gitdiagram.com/rajeshpatel07/scythe
- Repository: https://github.com/rajeshpatel07/scythe

## Overview

Scythe is a keyboard-first Chromium extension for history search, tab switching, and link previews. The main workflow begins with a keyboard or link interaction in a page, opens an overlay, then searches/navigates, selects a tab, or previews a URL. The graph also preserves the background message handlers, settings, and Glance header rules. Some background and tab-switcher implementation details were not excerpted; edges there are limited to indexed references or README statements.

Main entry points: [`src/features/spotlight/services/spotlight.controller.ts`](https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/spotlight.controller.ts) (Spotlight controller), [`src/features/spotlight/services/search-runner.service.ts`](https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/search-runner.service.ts) (History search), [`src/app/keyboard/global-keys.ts`](https://github.com/rajeshpatel07/scythe/blob/main/src/app/keyboard/global-keys.ts) (Global keys), [`src/background/router.ts`](https://github.com/rajeshpatel07/scythe/blob/main/src/background/router.ts) (Background router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Page Interaction"]
  node_content["Content entry<br/>[index.ts]"]
  node_globalkeys["Global keys<br/>[global-keys.ts]"]
  node_glance["Glance preview"]
  node_switcher["Tab switcher"]
  node_selection["Tab selection"]
  node_selectionstate["Selection state<br/>[selection.store.ts]"]
end

subgraph group_spotlight["Spotlight Search"]
  node_spotcontroller["Spotlight controller"]
  node_searchrunner["History search"]
  node_autocomplete["Autocomplete"]
  node_autocompleteengine["Completion engine"]
  node_historyindex["History index"]
  node_historylist["Recent history"]
  node_results["Search results UI"]
end

subgraph group_background["Background Services"]
  node_backgroundrouter["Background router<br/>[router.ts]"]
  node_historyhandler["History handler<br/>[history.handler.ts]"]
  node_tabhandler["Tab handlers<br/>[tabs.handler.ts]"]
  node_glancehandler["Glance handler<br/>[glance.handler.ts]"]
  node_faviconhandler["Favicon handler<br/>[favicon.handler.ts]"]
  node_rules["Glance header rules<br/>[rules.service.ts]"]
end

subgraph group_shared["Shared UI and State"]
  node_navigation["URL navigation"]
  node_config["Extension settings<br/>[config.ts]"]
  node_storage[("Browser storage<br/>[storage.utils.ts]")]
  node_broker["Message broker<br/>[message.broker.ts]"]
  node_favicon["Favicon service<br/>[favicon.service.ts]"]
  node_newtab["New tab page"]
  node_popup["Settings popup<br/>[popup.ts]"]
end

node_user(("Keyboard user"))

node_user -->|"presses shortcuts"| node_globalkeys
node_globalkeys -->|"opens or closes"| node_switcher
node_globalkeys -->|"updates selection"| node_selection
node_selection -->|"updates display"| node_switcher
node_selection -->|"reads state"| node_selectionstate
node_globalkeys -->|"opens search"| node_spotcontroller
node_globalkeys -->|"closes preview"| node_glance
node_content -->|"registers keys"| node_globalkeys
node_content -->|"initializes search"| node_spotcontroller
node_spotcontroller -->|"populates history"| node_historylist
node_spotcontroller -->|"ensures index"| node_historyindex
node_spotcontroller -->|"updates completion"| node_autocomplete
node_spotcontroller -->|"debounces search"| node_searchrunner
node_searchrunner -->|"requests history"| node_broker
node_searchrunner -->|"parses candidates"| node_autocompleteengine
node_searchrunner -->|"applies completion"| node_autocomplete
node_searchrunner -->|"renders results"| node_results
node_searchrunner -->|"opens submitted URL"| node_navigation
node_autocomplete -->|"scores candidates"| node_autocompleteengine
node_autocomplete -->|"uses local index"| node_historyindex
node_historyindex -->|"requests history"| node_broker
node_historyindex -.->|"shares history data"| node_historylist
node_spotcontroller -->|"checks settings"| node_config
node_config -->|"loads preferences"| node_storage
node_glance -->|"sends preview requests"| node_broker
node_glance -->|"opens preview URL"| node_navigation
node_glance -.->|"needs compatible framing"| node_rules
node_broker -.->|"dispatches messages"| node_backgroundrouter
node_backgroundrouter -->|"routes history"| node_historyhandler
node_backgroundrouter -->|"routes tab actions"| node_tabhandler
node_backgroundrouter -->|"routes preview actions"| node_glancehandler
node_backgroundrouter -->|"routes favicon requests"| node_faviconhandler
node_content -.->|"supports new tab page"| node_newtab
node_popup -->|"configures preferences"| node_config
node_results -->|"loads favicons"| node_favicon

click node_content "https://github.com/rajeshpatel07/scythe/blob/main/src/content/index.ts"
click node_globalkeys "https://github.com/rajeshpatel07/scythe/blob/main/src/app/keyboard/global-keys.ts"
click node_glance "https://github.com/rajeshpatel07/scythe/blob/main/src/features/glance/components/glance.component.ts"
click node_switcher "https://github.com/rajeshpatel07/scythe/blob/main/src/features/tab-switcher/components/switcher.component.ts"
click node_selection "https://github.com/rajeshpatel07/scythe/blob/main/src/features/tab-switcher/actions/selection.actions.ts"
click node_selectionstate "https://github.com/rajeshpatel07/scythe/blob/main/src/features/tab-switcher/state/selection.store.ts"
click node_spotcontroller "https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/spotlight.controller.ts"
click node_searchrunner "https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/search-runner.service.ts"
click node_autocomplete "https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/autocompletion.service.ts"
click node_autocompleteengine "https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/autocompletion.engine.ts"
click node_historyindex "https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/history-index.store.ts"
click node_historylist "https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/history-list.service.ts"
click node_results "https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/components/result-item.component.ts"
click node_navigation "https://github.com/rajeshpatel07/scythe/blob/main/src/core/services/navigation.service.ts"
click node_config "https://github.com/rajeshpatel07/scythe/blob/main/src/core/config/config.ts"
click node_storage "https://github.com/rajeshpatel07/scythe/blob/main/src/core/storage/storage.utils.ts"
click node_broker "https://github.com/rajeshpatel07/scythe/blob/main/src/core/messaging/message.broker.ts"
click node_backgroundrouter "https://github.com/rajeshpatel07/scythe/blob/main/src/background/router.ts"
click node_historyhandler "https://github.com/rajeshpatel07/scythe/blob/main/src/background/handlers/history.handler.ts"
click node_tabhandler "https://github.com/rajeshpatel07/scythe/blob/main/src/background/handlers/tabs.handler.ts"
click node_glancehandler "https://github.com/rajeshpatel07/scythe/blob/main/src/background/handlers/glance.handler.ts"
click node_faviconhandler "https://github.com/rajeshpatel07/scythe/blob/main/src/background/handlers/favicon.handler.ts"
click node_rules "https://github.com/rajeshpatel07/scythe/blob/main/src/background/services/rules.service.ts"
click node_favicon "https://github.com/rajeshpatel07/scythe/blob/main/src/core/services/favicon.service.ts"
click node_newtab "https://github.com/rajeshpatel07/scythe/blob/main/src/features/new-tab/components/newtab.component.ts"
click node_popup "https://github.com/rajeshpatel07/scythe/blob/main/src/popup/popup.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_content,node_globalkeys,node_glance,node_switcher,node_selection,node_selectionstate,node_user toneBlue
class node_spotcontroller,node_searchrunner,node_autocomplete,node_autocompleteengine,node_historyindex,node_historylist,node_results toneAmber
class node_backgroundrouter,node_historyhandler,node_tabhandler,node_glancehandler,node_faviconhandler,node_rules toneMint
class node_navigation,node_config,node_storage,node_broker,node_favicon,node_newtab,node_popup toneRose
```

## Components

### Page Interaction

- [Content entry](https://github.com/rajeshpatel07/scythe/blob/main/src/content/index.ts): `src/content/index.ts`
- [Global keys](https://github.com/rajeshpatel07/scythe/blob/main/src/app/keyboard/global-keys.ts): `src/app/keyboard/global-keys.ts`
- [Glance preview](https://github.com/rajeshpatel07/scythe/blob/main/src/features/glance/components/glance.component.ts): `src/features/glance/components/glance.component.ts`
- [Tab switcher](https://github.com/rajeshpatel07/scythe/blob/main/src/features/tab-switcher/components/switcher.component.ts): `src/features/tab-switcher/components/switcher.component.ts`
- [Tab selection](https://github.com/rajeshpatel07/scythe/blob/main/src/features/tab-switcher/actions/selection.actions.ts): `src/features/tab-switcher/actions/selection.actions.ts`
- [Selection state](https://github.com/rajeshpatel07/scythe/blob/main/src/features/tab-switcher/state/selection.store.ts): `src/features/tab-switcher/state/selection.store.ts`

### Spotlight Search

- [Spotlight controller](https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/spotlight.controller.ts): `src/features/spotlight/services/spotlight.controller.ts`
- [History search](https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/search-runner.service.ts): `src/features/spotlight/services/search-runner.service.ts`
- [Autocomplete](https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/autocompletion.service.ts): `src/features/spotlight/services/autocompletion.service.ts`
- [Completion engine](https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/autocompletion.engine.ts): `src/features/spotlight/services/autocompletion.engine.ts`
- [History index](https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/history-index.store.ts): `src/features/spotlight/services/history-index.store.ts`
- [Recent history](https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/services/history-list.service.ts): `src/features/spotlight/services/history-list.service.ts`
- [Search results UI](https://github.com/rajeshpatel07/scythe/blob/main/src/features/spotlight/components/result-item.component.ts): `src/features/spotlight/components/result-item.component.ts`

### Background Services

- [Background router](https://github.com/rajeshpatel07/scythe/blob/main/src/background/router.ts): `src/background/router.ts`
- [History handler](https://github.com/rajeshpatel07/scythe/blob/main/src/background/handlers/history.handler.ts): `src/background/handlers/history.handler.ts`
- [Tab handlers](https://github.com/rajeshpatel07/scythe/blob/main/src/background/handlers/tabs.handler.ts): `src/background/handlers/tabs.handler.ts`
- [Glance handler](https://github.com/rajeshpatel07/scythe/blob/main/src/background/handlers/glance.handler.ts): `src/background/handlers/glance.handler.ts`
- [Favicon handler](https://github.com/rajeshpatel07/scythe/blob/main/src/background/handlers/favicon.handler.ts): `src/background/handlers/favicon.handler.ts`
- [Glance header rules](https://github.com/rajeshpatel07/scythe/blob/main/src/background/services/rules.service.ts): `src/background/services/rules.service.ts`

### Shared UI and State

- [URL navigation](https://github.com/rajeshpatel07/scythe/blob/main/src/core/services/navigation.service.ts): `src/core/services/navigation.service.ts`
- [Extension settings](https://github.com/rajeshpatel07/scythe/blob/main/src/core/config/config.ts): `src/core/config/config.ts`
- [Browser storage](https://github.com/rajeshpatel07/scythe/blob/main/src/core/storage/storage.utils.ts): `src/core/storage/storage.utils.ts`
- [Message broker](https://github.com/rajeshpatel07/scythe/blob/main/src/core/messaging/message.broker.ts): `src/core/messaging/message.broker.ts`
- [Favicon service](https://github.com/rajeshpatel07/scythe/blob/main/src/core/services/favicon.service.ts): `src/core/services/favicon.service.ts`
- [New tab page](https://github.com/rajeshpatel07/scythe/blob/main/src/features/new-tab/components/newtab.component.ts): `src/features/new-tab/components/newtab.component.ts`
- [Settings popup](https://github.com/rajeshpatel07/scythe/blob/main/src/popup/popup.ts): `src/popup/popup.ts`

### Other components

- **Keyboard user**

## Connections

- Keyboard user → Global keys: presses shortcuts (evidence: `README.md`)
- Global keys → Tab switcher: opens or closes (evidence: `src/app/keyboard/global-keys.ts`)
- Global keys → Tab selection: updates selection (evidence: `src/app/keyboard/global-keys.ts`)
- Tab selection → Tab switcher: updates display (evidence: `src/features/tab-switcher/actions/selection.actions.ts`)
- Tab selection → Selection state: reads state (evidence: `src/features/tab-switcher/actions/selection.actions.ts`)
- Global keys → Spotlight controller: opens search (evidence: `src/content/index.ts`)
- Global keys → Glance preview: closes preview (evidence: `src/app/keyboard/global-keys.ts`)
- Content entry → Global keys: registers keys (evidence: `src/content/index.ts`)
- Content entry → Spotlight controller: initializes search (evidence: `src/content/index.ts`)
- Spotlight controller → Recent history: populates history (evidence: `src/features/spotlight/services/spotlight.controller.ts`)
- Spotlight controller → History index: ensures index (evidence: `src/features/spotlight/services/spotlight.controller.ts`)
- Spotlight controller → Autocomplete: updates completion (evidence: `src/features/spotlight/services/spotlight.controller.ts`)
- Spotlight controller → History search: debounces search (evidence: `src/features/spotlight/services/spotlight.controller.ts`)
- History search → Message broker: requests history (evidence: `src/features/spotlight/services/search-runner.service.ts`)
- History search → Completion engine: parses candidates (evidence: `src/features/spotlight/services/search-runner.service.ts`)
- History search → Autocomplete: applies completion (evidence: `src/features/spotlight/services/search-runner.service.ts`)
- History search → Search results UI: renders results (evidence: `src/features/spotlight/services/search-runner.service.ts`)
- History search → URL navigation: opens submitted URL (evidence: `src/features/spotlight/services/search-runner.service.ts`)
- Autocomplete → Completion engine: scores candidates (evidence: `src/features/spotlight/services/autocompletion.service.ts`)
- Autocomplete → History index: uses local index (evidence: `src/features/spotlight/services/autocompletion.service.ts`)
- History index → Message broker: requests history (evidence: `src/features/spotlight/services/history-index.store.ts`)
- History index → Recent history: shares history data
- Spotlight controller → Extension settings: checks settings (evidence: `src/features/spotlight/services/spotlight.controller.ts`)
- Extension settings → Browser storage: loads preferences (evidence: `src/core/config/config.ts`)
- Glance preview → Message broker: sends preview requests (evidence: `src/features/glance/components/glance.component.ts`)
- Glance preview → URL navigation: opens preview URL (evidence: `src/features/glance/components/glance.component.ts`)
- Glance preview → Glance header rules: needs compatible framing (evidence: `README.md`)
- Message broker → Background router: dispatches messages
- Background router → History handler: routes history (evidence: `src/background/router.ts`)
- Background router → Tab handlers: routes tab actions (evidence: `src/background/router.ts`)
- Background router → Glance handler: routes preview actions (evidence: `src/background/router.ts`)
- Background router → Favicon handler: routes favicon requests (evidence: `src/background/router.ts`)
- Content entry → New tab page: supports new tab page (evidence: `README.md`)
- Settings popup → Extension settings: configures preferences (evidence: `src/popup/popup.ts`)
- Search results UI → Favicon service: loads favicons (evidence: `src/features/spotlight/components/result-item.component.ts`)
