# delambo/core-web-vitals-annotations architecture

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

- Interactive diagram: https://gitdiagram.com/delambo/core-web-vitals-annotations
- Repository: https://github.com/delambo/core-web-vitals-annotations

## Overview

1. **Project type and runtime**
   - This is a **Chrome Extension** focused on analyzing and annotating **Core Web Vitals** on the currently open web page.
   - It runs in two main browser-extension contexts: a **content script** injected into pages and a **popup UI** shown when the user clicks the extension icon.

2. **Top-level architecture**
   - The repo is split into three functional areas:
     - `src/public`: page-injected assets and logic
     - `src/popup`: the extension popup UI
     - `src/background`: the extension background script
   - `src/manifest.json` ties these pieces together as a browser extension.

3. **Page instrumentation layer**
   - `src/public/contentScript.js` is the main page-facing subsystem.
   - Its job is to observe page behavior related to **CLS** and **LCP**, then overlay visual annotations directly on the webpage.
   - `src/public/contentScript.css` provides the styling for those overlays so they appear on top of page content.

4. **What the content script reports**
   - The extension highlights:
     - **CLS contributors**: elements that shifted and contributed to layout instability
     - **LCP element**: the largest contentful paint target, marked with a dashed purple outline
   - The README indicates the script also tracks metric values and groups elements that shifted together, which implies the content script is both an observer and a renderer of diagnostic overlays.

5. **Extension popup**
   - `src/popup/index.js` is the entry point for the popup panel.
   - `src/popup/popup.ejs` defines the popup’s structure, and `src/popup/styled.js` contains the styling layer for the popup UI.
   - The popup presents a grid of **FID, LCP, and CLS** values and includes a control to remove annotations from the page.

6. **Data flow between popup and page**
   - The popup is not the source of the metrics; it is a **viewer/controller** over data collected elsewhere.
   - The metrics and overlay state are likely shared through **extension messaging** and/or background-mediated state, because the popup must reflect page state and trigger actions like clearing annotations.
   - The content script is the component closest to the page and therefore the component that actually owns the overlays.

7. **Background script role**
   - `src/background/index.js` is the likely coordination point for extension-level events and communication.
   - In a Chrome extension like this, the background layer commonly handles message routing, lifecycle persistence, and coordination between the popup and the content script.
   - Architecturally, it is the boundary between transient UI interactions and page instrumentation state.

8. **Manifest and extension wiring**
   - `src/manifest.json` defines the extension permissions, entry points, and which scripts run in which contexts.
   - This manifest is the key boundary document: it determines what is injected into pages, what runs in the extension UI, and what background capabilities are available.

9. **Performance-measurement focus**
   - The repo is explicitly centered on **Core Web Vitals** and related browser performance events:
     - **FID** is user-initiated and may only appear after interaction
     - **CLS** accumulates over time as layout shifts occur
     - **LCP** is detected as the largest contentful paint element
   - This means the architecture is event-driven rather than request/response based.

10. **Rendering and visual semantics**
   - The overlay system uses color and shape to encode severity and metric type:
     - CLS annotations are color-coded from lower to higher impact
     - LCP uses a purple dashed outline
   - Those are not just UI details; they are part of the architecture because they define the page-layer diagnostic model.

11. **Build and tooling**
   - The project is built with a webpack-based setup, likely using **Kyt** (`kyt.config.js`).
   - Babel (`.babelrc`) and ESLint (`.eslintrc.js`) indicate transpilation and linting support for the extension codebase.
   - `webpack.aliases.config.js` suggests module aliasing to simplify imports across the popup, background, and public scripts.

12. **Source organization boundary**
   - `src/public/lodash.debounce-throttle.js` and the presence of page instrumentation code indicate the repo includes utility code bundled with the content script, likely to reduce redundant event handling for scroll/layout activity.
   - The separation between `public`, `popup`, and `background` is the most important architectural boundary in the repo.

13. **Operational behavior**
   - The extension is designed to be opened on an active page, where the content script has already been monitoring or can begin monitoring page activity.
   - The popup is effectively a dashboard for the currently active tab, while the content script is the measurement engine.

14. **What an architecture diagram should show**
   - A browser page with injected **content script + overlay CSS**
   - A separate **popup UI** opened from the extension icon
   - A **background script** mediating extension communication/state
   - The **manifest** as the configuration layer connecting all three
   - The data path from page events → metrics collection → overlay rendering and popup display

Main entry points: [`src/public/contentScript.js`](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/public/contentScript.js) (Content script), [`src/popup/index.js`](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/popup/index.js) (Popup app), [`src/background/index.js`](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/background/index.js) (Background), [`src/manifest.json`](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/manifest.json) (Manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Extension runtime"]
  node_manifest["Manifest<br/>extension config<br/>[manifest.json]"]
  node_content_script["Content script<br/>page observer<br/>[contentScript.js]"]
  node_overlay_css["Overlay CSS<br/>page styles<br/>[contentScript.css]"]
  node_debounce_util["Debounce util<br/>event helper"]
  node_background["Background<br/>message broker<br/>[index.js]"]
  node_popup_entry["Popup app<br/>popup UI<br/>[index.js]"]
  node_popup_view["Popup view<br/>markup<br/>[popup.ejs]"]
  node_popup_styles["Popup styles<br/>ui styles<br/>[styled.js]"]
  node_page(("Web page<br/>browser page"))
  node_metrics{{"Core Web Vitals<br/>signals"}}
  node_cls_overlays["CLS markers<br/>annotation layer"]
  node_lcp_outline["LCP marker<br/>annotation layer"]
  node_popup_dashboard["Popup dashboard<br/>status panel"]
end

subgraph group_build["Build tooling"]
  node_build{{"Tooling<br/>build setup"}}
  node_kyt_config["Kyt config<br/>bundler config<br/>[kyt.config.js]"]
  node_aliases["Aliases<br/>module map"]
end

node_manifest -->|"injects"| node_content_script
node_manifest -->|"starts"| node_background
node_manifest -->|"opens"| node_popup_entry
node_content_script -->|"observes"| node_page
node_content_script -->|"reports"| node_metrics
node_content_script -->|"renders"| node_cls_overlays
node_content_script -->|"renders"| node_lcp_outline
node_content_script -->|"uses"| node_overlay_css
node_content_script -->|"uses"| node_debounce_util
node_background -->|"routes"| node_content_script
node_background -->|"routes"| node_popup_entry
node_popup_entry -->|"renders"| node_popup_view
node_popup_entry -->|"styles"| node_popup_styles
node_popup_entry -->|"shows"| node_popup_dashboard
node_popup_dashboard -->|"commands"| node_background
node_popup_dashboard -->|"displays"| node_metrics
node_build -->|"includes"| node_kyt_config
node_build -->|"configures"| node_aliases

click node_manifest "https://github.com/delambo/core-web-vitals-annotations/blob/main/src/manifest.json"
click node_content_script "https://github.com/delambo/core-web-vitals-annotations/blob/main/src/public/contentScript.js"
click node_overlay_css "https://github.com/delambo/core-web-vitals-annotations/blob/main/src/public/contentScript.css"
click node_debounce_util "https://github.com/delambo/core-web-vitals-annotations/blob/main/src/public/lodash.debounce-throttle.js"
click node_background "https://github.com/delambo/core-web-vitals-annotations/blob/main/src/background/index.js"
click node_popup_entry "https://github.com/delambo/core-web-vitals-annotations/blob/main/src/popup/index.js"
click node_popup_view "https://github.com/delambo/core-web-vitals-annotations/blob/main/src/popup/popup.ejs"
click node_popup_styles "https://github.com/delambo/core-web-vitals-annotations/blob/main/src/popup/styled.js"
click node_kyt_config "https://github.com/delambo/core-web-vitals-annotations/blob/main/kyt.config.js"
click node_aliases "https://github.com/delambo/core-web-vitals-annotations/blob/main/webpack.aliases.config.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_manifest,node_content_script,node_overlay_css,node_debounce_util,node_background,node_popup_entry,node_popup_view,node_popup_styles,node_page,node_metrics,node_cls_overlays,node_lcp_outline,node_popup_dashboard toneBlue
class node_build,node_kyt_config,node_aliases toneAmber
```

## Components

### Extension runtime

Page instrumentation, background coordination, and popup UI

- [Manifest](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/manifest.json): extension config · Wires page injection, popup, and background roles · `src/manifest.json`
- [Content script](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/public/contentScript.js): page observer · Monitors CLS and LCP on the active page and drives annotations · `src/public/contentScript.js`
- [Overlay CSS](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/public/contentScript.css): page styles · Styles in-page highlights, outlines, and diagnostic overlays · `src/public/contentScript.css`
- [Debounce util](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/public/lodash.debounce-throttle.js): event helper · Shared throttling/debouncing support for page event handling · `src/public/lodash.debounce-throttle.js`
- [Background](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/background/index.js): message broker · Coordinates extension events and shared state between page and popup · `src/background/index.js`
- [Popup app](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/popup/index.js): popup UI · Entry point for the extension dashboard and page controls · `src/popup/index.js`
- [Popup view](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/popup/popup.ejs): markup · Defines the popup layout for metric values and actions · `src/popup/popup.ejs`
- [Popup styles](https://github.com/delambo/core-web-vitals-annotations/blob/main/src/popup/styled.js): ui styles · Styles the popup panel and its metric grid · `src/popup/styled.js`
- **Web page**: browser page · The currently open tab where measurement and annotations occur
- **Core Web Vitals**: signals · FID, CLS, and LCP values surfaced by the extension
- **CLS markers**: annotation layer · Highlights shifted elements and groups instability contributors
- **LCP marker**: annotation layer · Marks the largest contentful paint target with a dashed outline
- **Popup dashboard**: status panel · Shows metric values and a control to clear page annotations

### Build tooling

Transpilation, bundling, and module resolution

- **Tooling**: build setup · Webpack, Babel, ESLint, and alias configuration
- [Kyt config](https://github.com/delambo/core-web-vitals-annotations/blob/main/kyt.config.js): bundler config · Project bundling and environment setup · `kyt.config.js`
- [Aliases](https://github.com/delambo/core-web-vitals-annotations/blob/main/webpack.aliases.config.js): module map · Import path aliases shared across extension bundles · `webpack.aliases.config.js`

## Connections

- Manifest → Content script: injects · Declares the page script that runs in the active tab
- Manifest → Background: starts · Registers the background coordination script
- Manifest → Popup app: opens · Declares the extension popup entrypoint
- Content script → Web page: observes · Listens to page activity and paint/layout events
- Content script → Core Web Vitals: reports · Produces CLS, LCP, and interaction-related signals
- Content script → CLS markers: renders · Draws shifted-element annotations on the page
- Content script → LCP marker: renders · Marks the LCP element with a dashed outline
- Content script → Overlay CSS: uses · Relies on overlay styling for in-page visualization
- Content script → Debounce util: uses · Throttles high-frequency page events
- Background → Content script: routes · Forwards state and commands between extension contexts
- Background → Popup app: routes · Serves popup requests and page state updates
- Popup app → Popup view: renders · Builds the popup structure
- Popup app → Popup styles: styles · Applies popup-specific presentation
- Popup app → Popup dashboard: shows · Displays current metric values and clear-annotations control
- Popup dashboard → Background: commands · Requests current state and clear actions through extension messaging
- Popup dashboard → Core Web Vitals: displays · Surfaces collected performance values for the active tab
- Tooling → Kyt config: includes · Webpack-based project setup
- Tooling → Aliases: configures · Defines shared module resolution