# floaredor/ventrilo-interview architecture

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

- Interactive diagram: https://gitdiagram.com/floaredor/ventrilo-interview
- Repository: https://github.com/floaredor/ventrilo-interview

## Overview

##### Project type + purpose (what you’re diagramming)
This repo is a **Chrome Extension (Manifest V3)** whose purpose is to **extract visible text from the currently active web page** and **display it in the extension popup**, with a **copy-to-clipboard** action.

That implies a system made of **browser-controlled runtime components** (popup UI, extension runtime, injected script running in the page) rather than a traditional client/server split.

##### Read the file tree as architecture signals
From the tree + README, the “real” runtime components are:

- **Extension UI**
- `popup.html` (view)
- `popup.ts` (controller/logic; compiled to `dist/popup.js`)
- **Injected / content execution**
- `content_script_main.ts` (entry point; compiled into `dist/content_script.js`)
- `text_extraction.ts` (pure-ish library module for DOM text extraction; bundled into content script)
- **Extension definition + permissions**
- `manifest.json` (MV3; defines popup, permissions like `activeTab`, `scripting`, `clipboardWrite`)
- **Build/tooling**
- `package.json`, `package-lock.json` (scripts + dependencies: `esbuild`, `typescript`, `@types/chrome`)
- `tsconfig.json`
- `dist/` is generated (not in tree, but referenced in README)
- **Assets**

The architecture is best described as **event-driven**:
- User opens popup → popup triggers injection → injected script extracts → sends message back → popup renders + enables copy.

##### Extension Popup Context
- Runs in its own isolated document (`popup.html` + `dist/popup.js`)
- Has access to Chrome extension APIs (subject to permissions)
##### Chrome Extension Platform / APIs
- `chrome.scripting.executeScript`
- `chrome.runtime.sendMessage` / `onMessage`
- (Potentially) `activeTab` permission boundary
##### Target Web Page Context (tab)
- Where the injected script executes (isolated world, but reading page DOM)
- Contains the DOM you’re extracting from

##### `popup.html` loads `dist/popup.js`
3. `dist/popup.js` → **Chrome Scripting API**: `chrome.scripting.executeScript({ target: activeTab, files: ['dist/content_script.js'] })`
##### Copy click → clipboard write (`navigator.clipboard.writeText` or fallback)

- `popup.ts` → esbuild → `dist/popup.js`
- `content_script_main.ts` + `text_extraction.ts` → esbuild → `dist/content_script.js`

This is important because in extensions, runtime files referenced by manifest / scripting injection must be the **compiled artifacts**.

##### Architectural patterns / principles used

- **Multi-context architecture** (Popup context vs Page context)
- **Command + response via messaging**
- Popup issues command (inject script)
- Content script returns result (message)
- **Separation of concerns**
- `text_extraction.ts` is a reusable “domain/library” module
- `content_script_main.ts` is orchestration glue
- `popup.ts` is UI/controller + platform API usage
- **Permission-gated capabilities**
- `activeTab` and `scripting` enable injection
- clipboard permission / API usage for copy

##### Relevant technologies/frameworks/libraries

- **Chrome Extension Manifest V3** (`manifest.json`)
- **Chrome Extension APIs**: `chrome.scripting`, `chrome.runtime`
- **TypeScript** source → **esbuild** bundle → JS artifacts in `dist/`
- Clipboard: `navigator.clipboard` (+ `document.execCommand` fallback)

- Shows popup open → injection → extraction → message → display → copy

- Shows how TS sources become `dist/*.js` and which artifact is injected/loaded

- `manifest.json` → “Extension Definition (MV3): popup entry + permissions”
- `popup.html` → “Popup View”
- `popup.ts` → “Popup Logic”
- `content_script_main.ts` → “Injected Script Entry”
- `text_extraction.ts` → “Text Extraction Library”
- `package.json` / `tsconfig.json` → “Tooling/Build Config”

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% RUNTIME (TOP-DOWN)
%% =========================

U["User"]:::external

subgraph "Extension Package (Chrome Extension MV3)"
  M["Manifest (MV3)\nExtension definition + permissions\n(activeTab, scripting, clipboardWrite)"]:::manifest
  I["Assets / Icons"]:::asset
  D1["Built Artifact\n(dist/popup.js)"]:::artifact
  D2["Built Artifact\n(dist/content_script.js)"]:::artifact
end

subgraph "Execution Context: Extension Popup"
  PHTML["Popup View\n(popup.html)\nTextarea + 'Copy Text' button"]:::popup
  PJS["Popup Controller\n(popup.ts → dist/popup.js)\n- inject content script\n- receive messages\n- render + copy"]:::popup
  CLIP["Clipboard API\nnavigator.clipboard.writeText()\n+ document.execCommand fallback"]:::api
end

subgraph "Execution Context: Chrome Extension Platform / APIs"
  SAPI["chrome.scripting\nexecuteScript()"]:::platform
  MSG["chrome.runtime messaging\nsendMessage / onMessage"]:::platform
  PERM["Permission-gated capabilities\nactiveTab + scripting + clipboardWrite"]:::platform
end

subgraph "Execution Context: Active Tab (Target Web Page)"
  PAGE["Target Web Page\nVisible DOM content"]:::page
  CS["Injected Content Bundle\n(content_script_main.ts + text_extraction.ts\n→ dist/content_script.js)"]:::content
  LIB["Text Extraction Library\n(text_extraction.ts)\n'simplifiedExtractTextFromPage()'"]:::content
end

%% Runtime numbered flow
U -->|"1.open_popup"| PHTML
PHTML -->|"2.load_script"| D1
D1 -->|"2.run_popup_logic"| PJS
PJS -->|"3.request_inject"| SAPI
PERM -->|"gate_injection"| SAPI
SAPI -->|"4.inject_and_run(dist/content_script.js)"| D2
D2 -->|"4.executes_in_tab"| CS
CS -->|"5.extract_call"| LIB
LIB -->|"5.read_visible_text"| PAGE
CS -->|"6.sendMessage({text})"| MSG
MSG -->|"7.onMessage(text)"| PJS
PJS -->|"8.render_text"| PHTML
PHTML -->|"9.copy_click"| PJS
PJS -->|"9.copy"| CLIP
PERM -->|"gate_clipboard"| CLIP

%% Architecture notes (kept vertical)
NOTE1["Pattern: Multi-context architecture\nPopup context ↔ Platform APIs ↔ Page context"]:::note
NOTE2["Pattern: Command + response via messaging\nInject → Extract → Message back"]:::note
NOTE3["Separation of concerns\npopup.ts (UI/controller)\ncontent_script_main.ts (glue)\ntext_extraction.ts (domain/lib)"]:::note
PJS -->|"note"| NOTE1
CS -->|"note"| NOTE2
LIB -->|"note"| NOTE3

%% =========================
%% BUILD / TOOLING (DEV-TIME)
%% =========================

subgraph "Build / Tooling (dev-time)"
  PKG["Build scripts + deps\n(package.json)\nTypeScript + esbuild"]:::build
  LOCK["Dependency lock\n(package-lock.json)"]:::build
  TSCFG["TypeScript config\n(tsconfig.json)"]:::build
  README["Project Documentation\n(README.md)"]:::doc
  NOTES["Internal Notes\n(agent-context/PROJECT_SUMMARY.md)"]:::doc
end

%% Build flows into artifacts used at runtime
PKG -->|"bundle_TS→JS"| D1
PKG -->|"bundle_TS→JS"| D2
TSCFG -->|"typecheck_config"| PKG
LOCK -->|"locks_deps"| PKG
README -->|"docs"| PKG
NOTES -->|"context_notes"| PKG

%% Manifest references runtime entrypoints conceptually
M -->|"declares_popup"| PHTML
M -->|"permissions"| PERM
M -->|"package_assets"| I

%% =========================
%% Click Events (from mapping)
%% =========================
click M "https://github.com/floaredor/ventrilo-interview/blob/main/manifest.json"
click PHTML "https://github.com/floaredor/ventrilo-interview/blob/main/popup.html"
click PJS "https://github.com/floaredor/ventrilo-interview/blob/main/popup.ts"
click CS "https://github.com/floaredor/ventrilo-interview/blob/main/content_script_main.ts"
click LIB "https://github.com/floaredor/ventrilo-interview/blob/main/text_extraction.ts"
click PKG "https://github.com/floaredor/ventrilo-interview/blob/main/package.json"
click LOCK "https://github.com/floaredor/ventrilo-interview/blob/main/package-lock.json"
click TSCFG "https://github.com/floaredor/ventrilo-interview/blob/main/tsconfig.json"
click I "https://github.com/floaredor/ventrilo-interview/tree/main/images/"
click README "https://github.com/floaredor/ventrilo-interview/blob/main/README.md"
click NOTES "https://github.com/floaredor/ventrilo-interview/blob/main/agent-context/PROJECT_SUMMARY.md"

%% =========================
%% Styles
%% =========================
classDef popup fill:#2E6FEE,stroke:#0B2E6F,color:#FFFFFF,stroke-width:1.5px
classDef platform fill:#F59E0B,stroke:#8A4B00,color:#111827,stroke-width:1.5px
classDef content fill:#16A34A,stroke:#0F5A2A,color:#FFFFFF,stroke-width:1.5px
classDef page fill:#9CA3AF,stroke:#4B5563,color:#111827,stroke-width:1.5px
classDef manifest fill:#60A5FA,stroke:#1D4ED8,color:#0B1020,stroke-width:1.5px
classDef build fill:#A855F7,stroke:#5B21B6,color:#FFFFFF,stroke-width:1.5px
classDef artifact fill:#E9D5FF,stroke:#7C3AED,color:#111827,stroke-width:1.5px
classDef api fill:#FB923C,stroke:#9A3412,color:#111827,stroke-width:1.5px
classDef external fill:#111827,stroke:#374151,color:#FFFFFF,stroke-width:1.5px
classDef asset fill:#93C5FD,stroke:#1D4ED8,color:#0B1020,stroke-width:1.5px
classDef doc fill:#C7D2FE,stroke:#4338CA,color:#111827,stroke-width:1.5px
classDef note fill:#FEF3C7,stroke:#B45309,color:#111827,stroke-width:1px,stroke-dasharray: 3 3
```
