# nrs13/bodhi architecture

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

- Interactive diagram: https://gitdiagram.com/nrs13/bodhi
- Repository: https://github.com/nrs13/bodhi

## Overview

Bodhi is a Chrome extension that finds vocabulary in YouTube captions or a user-entered search and displays definitions without interrupting playback. The caption path gathers a recent caption window, ranks candidate words, looks up a definition, and presents it in a floating card; users can try another candidate or search directly. The card and popup also expose per-video lookup history and settings. Edges reflect documented calls and data access; cross-context message dispatch is shown as unverified because the excerpts do not show the full wiring.

Main entry points: [`extension/content/content.js`](https://github.com/nrs13/bodhi/blob/main/extension/content/content.js) (Page controller), [`extension/popup/popup.js`](https://github.com/nrs13/bodhi/blob/main/extension/popup/popup.js) (Popup and settings), [`extension/background/serviceWorker.js`](https://github.com/nrs13/bodhi/blob/main/extension/background/serviceWorker.js) (Message worker), [`extension/content/wordPredictor.js`](https://github.com/nrs13/bodhi/blob/main/extension/content/wordPredictor.js) (Ranking client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_caption["Caption analysis"]
  node_transcript["Transcript manager"]
  node_rank_client["Ranking client<br/>[wordPredictor.js]"]
  node_ranker["Word ranker<br/>[wordPredictor.js]"]
  node_frequency[("Frequency list<br/>[frequencyList.js]")]
end

subgraph group_lookup["Definition lookup"]
  node_worker["Message worker<br/>[serviceWorker.js]"]
  node_definition_client["Definition client"]
  node_message_client["Runtime message client<br/>[swClient.js]"]
  node_definitions["Definition fetcher"]
end

subgraph group_experience["Extension experience"]
  node_content["Page controller<br/>[content.js]"]
  node_card["Floating card<br/>[content.js]"]
  node_spellcheck["Search suggestions<br/>[content.js]"]
  node_popup["Popup and settings<br/>[popup.js]"]
  node_text_helper["Text formatting<br/>[text.js]"]
end

subgraph group_state["History and settings"]
  node_history["Lookup history<br/>[content.js]"]
  node_storage[("Chrome local storage")]
  node_history_helper["History pruning<br/>[history.js]"]
end

node_viewer(("YouTube viewer"))
node_youtube["YouTube captions"]
node_dictionary_services["Dictionary services"]
node_popup_actor(("Extension user"))

node_viewer -->|"watches"| node_youtube
node_youtube -->|"provides captions"| node_transcript
node_viewer -->|"invokes lookup"| node_content
node_content -->|"reads caption window"| node_transcript
node_content -->|"requests ranking"| node_rank_client
node_rank_client -.->|"sends rank request"| node_worker
node_worker -->|"dispatches ranking"| node_ranker
node_ranker -->|"reads word ranks"| node_frequency
node_content -->|"requests definition"| node_definition_client
node_definition_client -->|"sends lookup request"| node_message_client
node_message_client -.->|"dispatches lookup"| node_worker
node_worker -->|"dispatches lookup"| node_definitions
node_definitions -->|"queries providers"| node_dictionary_services
node_content -->|"renders result"| node_card
node_content -->|"offers search suggestions"| node_spellcheck
node_content -->|"reads and saves lookups"| node_history
node_history -->|"reads and writes"| node_storage
node_popup_actor -->|"opens popup"| node_popup
node_popup -->|"reads history and settings"| node_storage
node_popup -->|"prunes entries"| node_history_helper
node_content -->|"prunes entries"| node_history_helper
node_content -->|"cleans display text"| node_text_helper
node_popup -->|"formats displayed text"| node_text_helper

click node_content "https://github.com/nrs13/bodhi/blob/main/extension/content/content.js"
click node_transcript "https://github.com/nrs13/bodhi/blob/main/extension/content/transcriptManager.js"
click node_rank_client "https://github.com/nrs13/bodhi/blob/main/extension/content/wordPredictor.js"
click node_worker "https://github.com/nrs13/bodhi/blob/main/extension/background/serviceWorker.js"
click node_ranker "https://github.com/nrs13/bodhi/blob/main/extension/background/wordPredictor.js"
click node_frequency "https://github.com/nrs13/bodhi/blob/main/extension/data/frequencyList.js"
click node_definition_client "https://github.com/nrs13/bodhi/blob/main/extension/content/definitionFetcher.js"
click node_message_client "https://github.com/nrs13/bodhi/blob/main/extension/content/swClient.js"
click node_definitions "https://github.com/nrs13/bodhi/blob/main/extension/background/definitionFetcher.js"
click node_card "https://github.com/nrs13/bodhi/blob/main/extension/content/content.js"
click node_spellcheck "https://github.com/nrs13/bodhi/blob/main/extension/content/content.js"
click node_history "https://github.com/nrs13/bodhi/blob/main/extension/content/content.js"
click node_popup "https://github.com/nrs13/bodhi/blob/main/extension/popup/popup.js"
click node_history_helper "https://github.com/nrs13/bodhi/blob/main/extension/shared/history.js"
click node_text_helper "https://github.com/nrs13/bodhi/blob/main/extension/shared/text.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_transcript,node_rank_client,node_ranker,node_frequency,node_viewer,node_popup_actor toneBlue
class node_worker,node_definition_client,node_message_client,node_definitions toneAmber
class node_content,node_card,node_spellcheck,node_popup,node_text_helper toneMint
class node_history,node_storage,node_history_helper toneRose
class node_youtube,node_dictionary_services toneIndigo
```

## Components

### Caption analysis

- [Transcript manager](https://github.com/nrs13/bodhi/blob/main/extension/content/transcriptManager.js): `extension/content/transcriptManager.js`
- [Ranking client](https://github.com/nrs13/bodhi/blob/main/extension/content/wordPredictor.js): `extension/content/wordPredictor.js`
- [Word ranker](https://github.com/nrs13/bodhi/blob/main/extension/background/wordPredictor.js): `extension/background/wordPredictor.js`
- [Frequency list](https://github.com/nrs13/bodhi/blob/main/extension/data/frequencyList.js): `extension/data/frequencyList.js`

### Definition lookup

- [Message worker](https://github.com/nrs13/bodhi/blob/main/extension/background/serviceWorker.js): `extension/background/serviceWorker.js`
- [Definition client](https://github.com/nrs13/bodhi/blob/main/extension/content/definitionFetcher.js): `extension/content/definitionFetcher.js`
- [Runtime message client](https://github.com/nrs13/bodhi/blob/main/extension/content/swClient.js): `extension/content/swClient.js`
- [Definition fetcher](https://github.com/nrs13/bodhi/blob/main/extension/background/definitionFetcher.js): `extension/background/definitionFetcher.js`

### Extension experience

- [Page controller](https://github.com/nrs13/bodhi/blob/main/extension/content/content.js): `extension/content/content.js`
- [Floating card](https://github.com/nrs13/bodhi/blob/main/extension/content/content.js): `extension/content/content.js`
- [Search suggestions](https://github.com/nrs13/bodhi/blob/main/extension/content/content.js): `extension/content/content.js`
- [Popup and settings](https://github.com/nrs13/bodhi/blob/main/extension/popup/popup.js): `extension/popup/popup.js`
- [Text formatting](https://github.com/nrs13/bodhi/blob/main/extension/shared/text.js): `extension/shared/text.js`

### History and settings

- [Lookup history](https://github.com/nrs13/bodhi/blob/main/extension/content/content.js): `extension/content/content.js`
- **Chrome local storage**
- [History pruning](https://github.com/nrs13/bodhi/blob/main/extension/shared/history.js): `extension/shared/history.js`

### Other components

- **YouTube viewer**
- **YouTube captions**
- **Dictionary services**
- **Extension user**

## Connections

- YouTube viewer → YouTube captions: watches (evidence: `README.md`)
- YouTube captions → Transcript manager: provides captions (evidence: `README.md`)
- YouTube viewer → Page controller: invokes lookup (evidence: `README.md`)
- Page controller → Transcript manager: reads caption window (evidence: `extension/content/content.js`)
- Page controller → Ranking client: requests ranking (evidence: `extension/content/content.js`)
- Ranking client → Message worker: sends rank request
- Message worker → Word ranker: dispatches ranking (evidence: `extension/background/serviceWorker.js`)
- Word ranker → Frequency list: reads word ranks (evidence: `extension/background/wordPredictor.js`)
- Page controller → Definition client: requests definition (evidence: `extension/content/content.js`)
- Definition client → Runtime message client: sends lookup request (evidence: `extension/content/definitionFetcher.js`)
- Runtime message client → Message worker: dispatches lookup
- Message worker → Definition fetcher: dispatches lookup (evidence: `extension/background/serviceWorker.js`)
- Definition fetcher → Dictionary services: queries providers (evidence: `extension/background/definitionFetcher.js`)
- Page controller → Floating card: renders result (evidence: `extension/content/content.js`)
- Page controller → Search suggestions: offers search suggestions (evidence: `README.md`)
- Page controller → Lookup history: reads and saves lookups (evidence: `extension/content/content.js`)
- Lookup history → Chrome local storage: reads and writes (evidence: `extension/content/content.js`)
- Extension user → Popup and settings: opens popup (evidence: `README.md`)
- Popup and settings → Chrome local storage: reads history and settings (evidence: `extension/popup/popup.js`)
- Popup and settings → History pruning: prunes entries (evidence: `extension/popup/popup.js`)
- Page controller → History pruning: prunes entries (evidence: `extension/content/content.js`)
- Page controller → Text formatting: cleans display text (evidence: `extension/content/content.js`)
- Popup and settings → Text formatting: formats displayed text (evidence: `extension/popup/popup.js`)
