# sebstefenel/glanceai architecture

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

- Interactive diagram: https://gitdiagram.com/sebstefenel/glanceai
- Repository: https://github.com/sebstefenel/glanceai

## Overview

1. **Project type and deployment boundary**
   - This is a **Chrome Extension (Manifest V3)**, not a standalone web app.
   - The main runtime boundaries are:
     - the **Google Search results page** where the extension injects behavior,
     - the **extension context** (background/service worker and options page),
     - and **external websites + Together.ai API**.

2. **Primary user flow**
   - A user performs a Google search.
   - When they **hover over a result link**, the extension attempts to summarize that page in the context of the original search query.
   - The output is meant to be an **instant relevance preview** without opening the link.

3. **Content script layer: `content.js`**
   - `content.js` is the page-facing component.
   - Its job is likely to:
     - detect Google Search result links,
     - listen for hover/mouse interactions,
     - capture the relevant query and URL,
     - trigger the summarization request,
     - and render the summary into the page UI.
   - This is the boundary where the extension interacts with the DOM of the host page.

4. **Extension background layer: `background.js`**
   - `background.js` is the extension-side orchestration layer.
   - In a Manifest V3 extension, this is typically the **service worker** responsible for privileged work:
     - fetching article content from the target URL,
     - calling the Together.ai API,
     - handling API key access,
     - and returning the summary to the content script.
   - This layer is the main bridge between the browser page and external services.

5. **External AI dependency: Together.ai**
   - The extension depends on **Together.ai** as its LLM provider.
   - The README specifically references `deepseek-ai/DeepSeek-V3`.
   - Architecturally, the model call is a distinct external boundary; the extension must send:
     - the original search query,
     - the article text or extracted content,
     - and receive a generated summary in response.

6. **Configuration and secrets: `options.html` + `options.js`**
   - The options page is the user-facing configuration boundary.
   - It is used to **store the user’s Together.ai API key**.
   - `options.js` likely reads/writes extension storage and validates/saves the key.
   - This is important architecturally because the extension is designed to be **user-authenticated per install**, not bundled with a shared server-side key.

7. **Static presentation: `style.css`**
   - `style.css` likely controls both the injected summary UI and/or the options page styling.
   - This is a presentation-only layer; it does not change the data flow, but it affects how the summary appears inline on search results pages.

8. **Data flow between layers**
   - The typical request path is:
     1. user hovers a search result in the page,
     2. `content.js` captures the URL and search context,
     3. `content.js` sends a message to `background.js`,
     4. `background.js` fetches the article and submits the text to Together.ai,
     5. the AI response returns to the background script,
     6. the summary is passed back to the content script,
     7. the content script displays it near the hovered result.
   - This is the core architecture diagram flow to show.

9. **Storage and persistence boundary**
   - The API key is configured once in the options page and then reused across sessions.
   - The extension likely relies on **Chrome extension storage** rather than local files or a backend.
   - That means the state boundary is local to the browser profile, not shared across users.

10. **Permissions and cross-origin considerations**
   - Because the extension summarizes pages on arbitrary domains, it needs to operate across:
     - the Google results page,
     - destination article domains,
     - and the Together.ai endpoint.
   - In architecture terms, this implies the manifest must grant permissions for host access and extension messaging, and the background layer is the likely place where cross-origin requests are centralized.

11. **Role of `manifest.json`**
   - `manifest.json` defines the extension’s lifecycle and wiring:
     - content script injection points,
     - background/service worker registration,
     - options page entry,
     - permissions and host access.
   - For an architecture diagram, this file is the “bootstrapping contract” that connects all other pieces.

12. **`test.py`**
   - `test.py` appears to be a utility artifact rather than a core runtime component.
   - It is likely used for local experimentation, API testing, or scraping/summarization verification.
   - It should not be treated as part of the browser execution path unless you verify otherwise.

13. **What to emphasize in a diagram**
   - The most important architectural separation is:
     - **page script/UI interaction** in `content.js`,
     - **privileged orchestration and API access** in `background.js`,
     - **user configuration** in `options.html`/`options.js`,
     - and the **external AI service** as the main dependency.
   - The article site is an input source, not part of the extension itself.

14. **Overall system shape**
   - This is a **client-side browser extension** with no custom backend.
   - All intelligence and state live either:
     - in the browser extension runtime,
     - in the user’s extension storage,
     - or in Together.ai’s API.
   - The architecture is lightweight and event-driven: hover event → extract content → summarize → render result.

Main entry points: [`background.js`](https://github.com/sebstefenel/glanceai/blob/main/background.js) (Background worker), [`content.js`](https://github.com/sebstefenel/glanceai/blob/main/content.js) (Content script), [`manifest.json`](https://github.com/sebstefenel/glanceai/blob/main/manifest.json) (Manifest), [`options.js`](https://github.com/sebstefenel/glanceai/blob/main/options.js) (Options logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Extension runtime"]
  node_manifest["Manifest<br/>extension config<br/>[manifest.json]"]
  node_content["Content script<br/>page injector<br/>[content.js]"]
  node_background["Background worker<br/>service worker<br/>[background.js]"]
end

subgraph group_ui["User settings"]
  node_options_page["Options page<br/>settings UI<br/>[options.html]"]
  node_options_js["Options logic<br/>settings controller<br/>[options.js]"]
  node_style["Styles<br/>presentation<br/>[style.css]"]
  node_storage[("Extension storage<br/>local state")]
end

subgraph group_external["External surfaces"]
  node_google(("Google Search<br/>host page"))
  node_article(("Target pages<br/>web content"))
  node_together{{"Together.ai<br/>llm api"}}
end

node_manifest -->|"injects"| node_content
node_manifest -->|"registers"| node_background
node_manifest -->|"opens"| node_options_page
node_manifest -->|"loads"| node_style
node_options_page -->|"drives"| node_options_js
node_options_js -->|"writes"| node_storage
node_options_js -->|"reads"| node_storage
node_google -->|"hosts"| node_content
node_content -->|"messages"| node_background
node_background -->|"fetches"| node_article
node_background -->|"calls"| node_together
node_background -->|"reads"| node_storage
node_background -->|"returns"| node_content
node_content -->|"renders with"| node_style

click node_manifest "https://github.com/sebstefenel/glanceai/blob/main/manifest.json"
click node_content "https://github.com/sebstefenel/glanceai/blob/main/content.js"
click node_background "https://github.com/sebstefenel/glanceai/blob/main/background.js"
click node_options_page "https://github.com/sebstefenel/glanceai/blob/main/options.html"
click node_options_js "https://github.com/sebstefenel/glanceai/blob/main/options.js"
click node_style "https://github.com/sebstefenel/glanceai/blob/main/style.css"

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_manifest,node_content,node_background toneBlue
class node_options_page,node_options_js,node_style,node_storage toneAmber
class node_google,node_article,node_together toneMint
```

## Components

### Extension runtime

Manifest V3 components that run inside the browser extension

- [Manifest](https://github.com/sebstefenel/glanceai/blob/main/manifest.json): extension config · Declares entrypoints, permissions, and wiring for the MV3 extension · `manifest.json`
- [Content script](https://github.com/sebstefenel/glanceai/blob/main/content.js): page injector · Reads Google results, captures hover events, and renders inline summaries · `content.js`
- [Background worker](https://github.com/sebstefenel/glanceai/blob/main/background.js): service worker · Orchestrates cross-origin fetches, AI calls, and response routing · `background.js`

### User settings

Options page and local configuration storage

- [Options page](https://github.com/sebstefenel/glanceai/blob/main/options.html): settings UI · User-facing page for configuring the extension · `options.html`
- [Options logic](https://github.com/sebstefenel/glanceai/blob/main/options.js): settings controller · Persists and validates the Together.ai API key in extension storage · `options.js`
- [Styles](https://github.com/sebstefenel/glanceai/blob/main/style.css): presentation · Shared styling for injected UI and settings surfaces · `style.css`
- **Extension storage**: local state · Persists the user API key and other install-scoped settings

### External surfaces

Host pages and remote services the extension interacts with

- **Google Search**: host page · Primary page where result hover triggers the summarization flow
- **Target pages**: web content · Destination pages whose text is fetched and summarized
- **Together.ai**: llm api · External model endpoint used to generate relevance summaries

## Connections

- Manifest → Content script: injects · Registers the content script on search result pages
- Manifest → Background worker: registers · Declares the MV3 service worker
- Manifest → Options page: opens · Connects the extension settings page
- Manifest → Styles: loads · Makes shared presentation assets available
- Options page → Options logic: drives · The page is controlled by its settings script
- Options logic → Extension storage: writes · Saves the API key and related preferences
- Options logic → Extension storage: reads · Loads persisted configuration on open
- Google Search → Content script: hosts · Content script runs in the Google results DOM
- Content script → Background worker: messages · Sends hover-triggered summarization requests
- Background worker → Target pages: fetches · Retrieves source page content for summarization
- Background worker → Together.ai: calls · Submits article text and query context to the model API
- Background worker → Extension storage: reads · Uses the stored API key for authentication
- Background worker → Content script: returns · Sends the generated summary back to the page script
- Content script → Styles: renders with · Uses shared CSS for the injected preview UI