# jraversbcn21/hoverlingo architecture

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

- Interactive diagram: https://gitdiagram.com/jraversbcn21/hoverlingo
- Repository: https://github.com/jraversbcn21/hoverlingo

## Overview

HoverLingo is a browser extension that translates words or selected phrases in page-context tooltips. The main flow is hover detection, text extraction, cache lookup, background translation through Groq, and tooltip display; the popup configures settings and exposes controls and usage statistics. The graph also preserves sentence translation, highlighting, and persistent caching. Some wiring is only partially sampled, so unverified links are dashed and evidence is limited to the shown excerpts or README.

Main entry points: [`src/content/index.ts`](https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/index.ts) (Content Orchestrator), [`src/background/service-worker.ts`](https://github.com/jraversbcn21/hoverlingo/blob/main/src/background/service-worker.ts) (Background Worker), [`src/popup/popup.ts`](https://github.com/jraversbcn21/hoverlingo/blob/main/src/popup/popup.ts) (Settings Popup), [`src/content/tooltip-renderer.ts`](https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/tooltip-renderer.ts) (Tooltip Renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_page["Page Translation"]
  node_hover["Hover Detection<br/>[hover-detector.ts]"]
  node_extract["Text Extraction<br/>[text-extractor.ts]"]
  node_content["Content Orchestrator<br/>[index.ts]"]
  node_highlight["Word Highlight<br/>[word-highlight.ts]"]
  node_tooltip["Tooltip Renderer"]
end

subgraph group_translation["Translation Runtime"]
  node_cache1[("Memory Cache<br/>[cache-l1.ts]")]
  node_worker["Background Worker<br/>[service-worker.ts]"]
  node_cache2[("Persistent Cache<br/>[cache-l2.ts]")]
end

subgraph group_settings["Settings and Usage"]
  node_popup["Settings Popup<br/>[popup.ts]"]
  node_locales["Popup Locales"]
end

subgraph group_shared["Shared Logic"]
  node_prompts["Prompt Builder<br/>[prompts.ts]"]
  node_cachekey["Cache Key<br/>[cache-key.ts]"]
  node_json["Response Parser<br/>[extract-json.ts]"]
  node_validation["Settings Validation"]
  node_types["Translation Types<br/>[types.ts]"]
  node_constants["Runtime Constants<br/>[constants.ts]"]
end

node_user(("User"))
node_webpage["Web Page"]
node_groq["Groq AI"]
node_storage[("Browser Storage")]

node_user -->|"hovers or selects"| node_webpage
node_webpage -.->|"provides pointer events"| node_hover
node_content -->|"configures"| node_hover
node_content -->|"extracts text"| node_extract
node_content -.->|"uses"| node_highlight
node_content -->|"renders results"| node_tooltip
node_content -->|"checks cache"| node_cache1
node_content -->|"builds keys"| node_cachekey
node_content -.->|"requests translations"| node_worker
node_tooltip -->|"reads pending results"| node_cache1
node_worker -->|"checks cache"| node_cache2
node_worker -->|"builds prompts"| node_prompts
node_worker -->|"builds keys"| node_cachekey
node_worker -->|"sends translation requests"| node_groq
node_worker -.->|"parses responses"| node_json
node_worker -->|"reads settings"| node_storage
node_popup -->|"loads and saves"| node_storage
node_popup -->|"validates imports"| node_validation
node_popup -->|"uses localized messages"| node_locales
node_content -->|"reads settings and records stats"| node_storage
node_user -->|"configures extension"| node_popup
node_content -->|"translates sentences on demand"| node_tooltip

click node_hover "https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/hover-detector.ts"
click node_extract "https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/text-extractor.ts"
click node_content "https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/index.ts"
click node_highlight "https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/word-highlight.ts"
click node_tooltip "https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/tooltip-renderer.ts"
click node_cache1 "https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/cache-l1.ts"
click node_worker "https://github.com/jraversbcn21/hoverlingo/blob/main/src/background/service-worker.ts"
click node_cache2 "https://github.com/jraversbcn21/hoverlingo/blob/main/src/background/cache-l2.ts"
click node_popup "https://github.com/jraversbcn21/hoverlingo/blob/main/src/popup/popup.ts"
click node_locales "https://github.com/jraversbcn21/hoverlingo/tree/main/public/_locales"
click node_prompts "https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/prompts.ts"
click node_cachekey "https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/cache-key.ts"
click node_json "https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/extract-json.ts"
click node_validation "https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/settings-validation.ts"
click node_types "https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/types.ts"
click node_constants "https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/constants.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_hover,node_extract,node_content,node_highlight,node_tooltip,node_user toneBlue
class node_cache1,node_worker,node_cache2,node_storage toneAmber
class node_popup,node_locales toneMint
class node_prompts,node_cachekey,node_json,node_validation,node_types,node_constants toneRose
class node_webpage,node_groq toneIndigo
```

## Components

### Page Translation

- [Hover Detection](https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/hover-detector.ts): `src/content/hover-detector.ts`
- [Text Extraction](https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/text-extractor.ts): `src/content/text-extractor.ts`
- [Content Orchestrator](https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/index.ts): `src/content/index.ts`
- [Word Highlight](https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/word-highlight.ts): `src/content/word-highlight.ts`
- [Tooltip Renderer](https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/tooltip-renderer.ts): `src/content/tooltip-renderer.ts`

### Translation Runtime

- [Memory Cache](https://github.com/jraversbcn21/hoverlingo/blob/main/src/content/cache-l1.ts): `src/content/cache-l1.ts`
- [Background Worker](https://github.com/jraversbcn21/hoverlingo/blob/main/src/background/service-worker.ts): `src/background/service-worker.ts`
- [Persistent Cache](https://github.com/jraversbcn21/hoverlingo/blob/main/src/background/cache-l2.ts): `src/background/cache-l2.ts`

### Settings and Usage

- [Settings Popup](https://github.com/jraversbcn21/hoverlingo/blob/main/src/popup/popup.ts): `src/popup/popup.ts`
- [Popup Locales](https://github.com/jraversbcn21/hoverlingo/tree/main/public/_locales): `public/_locales`

### Shared Logic

- [Prompt Builder](https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/prompts.ts): `src/shared/prompts.ts`
- [Cache Key](https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/cache-key.ts): `src/shared/cache-key.ts`
- [Response Parser](https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/extract-json.ts): `src/shared/extract-json.ts`
- [Settings Validation](https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/settings-validation.ts): `src/shared/settings-validation.ts`
- [Translation Types](https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/types.ts): `src/shared/types.ts`
- [Runtime Constants](https://github.com/jraversbcn21/hoverlingo/blob/main/src/shared/constants.ts): `src/shared/constants.ts`

### Other components

- **User**
- **Web Page**
- **Groq AI**
- **Browser Storage**

## Connections

- User → Web Page: hovers or selects (evidence: `README.md`)
- Web Page → Hover Detection: provides pointer events
- Content Orchestrator → Hover Detection: configures (evidence: `src/content/index.ts`)
- Content Orchestrator → Text Extraction: extracts text (evidence: `src/content/index.ts`)
- Content Orchestrator → Word Highlight: uses (evidence: `src/content/index.ts`)
- Content Orchestrator → Tooltip Renderer: renders results (evidence: `src/content/index.ts`)
- Content Orchestrator → Memory Cache: checks cache (evidence: `src/content/index.ts`)
- Content Orchestrator → Cache Key: builds keys (evidence: `src/content/index.ts`)
- Content Orchestrator → Background Worker: requests translations
- Tooltip Renderer → Memory Cache: reads pending results (evidence: `src/content/tooltip-renderer.ts`)
- Background Worker → Persistent Cache: checks cache (evidence: `src/background/service-worker.ts`)
- Background Worker → Prompt Builder: builds prompts (evidence: `src/background/service-worker.ts`)
- Background Worker → Cache Key: builds keys (evidence: `src/background/service-worker.ts`)
- Background Worker → Groq AI: sends translation requests (evidence: `src/background/service-worker.ts`)
- Background Worker → Response Parser: parses responses (evidence: `src/background/service-worker.ts`)
- Background Worker → Browser Storage: reads settings (evidence: `src/background/service-worker.ts`)
- Settings Popup → Browser Storage: loads and saves (evidence: `src/popup/popup.ts`)
- Settings Popup → Settings Validation: validates imports (evidence: `src/popup/popup.ts`)
- Settings Popup → Popup Locales: uses localized messages (evidence: `README.md`)
- Content Orchestrator → Browser Storage: reads settings and records stats (evidence: `src/content/index.ts`)
- User → Settings Popup: configures extension (evidence: `README.md`)
- Content Orchestrator → Tooltip Renderer: translates sentences on demand (evidence: `README.md`)
