# davrous/dareangel architecture

> Architecture diagram of the GitHub repository davrous/dareangel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/davrous/dareangel
- Repository: https://github.com/davrous/dareangel

## Overview

##### Project Type and Purpose
- This is a cross-browser **proof-of-concept extension** (“Dare Angel”) that extracts images from the active tab, displays thumbnails in a popup/dashboard, calls a Computer Vision API to describe the image, then speaks the description via Bing TTS or the Web Speech API.

##### Main Components
a. **Manifest (manifest.json)**
– Declares extension metadata, permissions (tabs, activeTab, speech), and entry points (content scripts, browser action).
b. **Content Script (start.ts → start.js)**
– Injects into every page (per manifest) or upon user action. Scans the DOM to collect `<img>` elements and sends their URLs back to the dashboard.
c. **Dashboard UI (dashboard.html, dashboard.css, dareangel.dashboard.ts → .js)**
– Renders the list of thumbnails and handles user clicks to select an image.
d. **Client Logic (dareangel.client.ts → .js)**
– Orchestrates calls to Microsoft’s Computer Vision API to retrieve image descriptions.
e. **TTS Client (BingTTSClient.ts → .js)**
– Wraps calls to the Bing Speech API; falls back to the Web Speech API when no key is provided.
f. **TypeScript Declarations (dts/… .d.ts)**
– Provides ambient typing for browser and Web APIs.
g. **Build Configuration (tsconfig.json)**
– Controls the TS→JS compilation target, module resolution, source maps, etc.

##### External Services and Browser APIs
- **Microsoft Computer Vision API** (HTTP REST call)
- **Bing Speech (Text-to-Speech) API** (HTTP REST call)
- **Web Speech API** (built-in browser)
- **Browser Messaging** (chrome.runtime.sendMessage / browser.tabs.sendMessage)
- **DOM APIs** (document.querySelectorAll, createElement)

##### High-Level Workflow and Interactions
2. `dashboard.js` sends a message to `start.js` (content script) to scan images in the active tab.
3. `start.js` returns an array of image URLs to the dashboard.
4. Dashboard UI displays thumbnails; user clicks one.
5. `dareangel.client.js` takes the selected URL → issues Computer Vision API request → receives a textual description.
6. `BingTTSClient.js` or Web Speech API is invoked to vocalize the description.
7. UI may display the description text alongside playing the audio stream.

##### Architectural Patterns and Principles
- **Event-driven / message-passing** between UI and content script.
- **Separation of concerns**: UI, page-scanning logic, API orchestration, TTS logic all in distinct modules.
- **Fallback strategy** for TTS (use Web Speech if Bing key missing).
- **Type safety and modularity** via TypeScript + declaration files.

##### Guidance
- External Services (Computer Vision API, Bing TTS API).
- Browser APIs (Web Speech, Messaging, DOM).
- UI → Content Script (“scan images” message)
- Content Script → UI (“image URLs” message)
- UI/Client → Computer Vision API (HTTP POST with image URL)
- UI/Client → Bing TTS API (HTTP request)
- UI/Client → Web Speech API (fallback)
- Content scripts / logic modules in another (e.g., green)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Extension Boundary
    subgraph "Browser Extension"
        style BrowserExt fill:#ffffff,stroke:#000000,stroke-width:1px
        BrowserExt[[ ]]
        subgraph ExtensionComponents
            Manifest["manifest.json"]:::config
            subgraph "Content Script"
                startTS["start.ts"]:::logic
                startJS["start.js"]:::logic
            end
            subgraph "Dashboard UI"
                HTML["dashboard.html"]:::ui
                CSS["dashboard.css"]:::ui
                DashboardTS["dareangel.dashboard.js"]:::ui
            end
            subgraph "Client Logic"
                ClientTS["dareangel.client.ts"]:::logic
                ClientJS["dareangel.client.js"]:::logic
            end
            subgraph "TTS Client"
                TTS_TS["BingTTSClient.ts"]:::logic
                TTS_JS["BingTTSClient.js"]:::logic
            end
            TSDecl["dts/"]:::declaration
            TSConfig["tsconfig.json"]:::config
        end
    end

    %% Browser APIs
    subgraph "Browser APIs"
        WebSpeech["Web Speech API"]:::browserapi
        Messaging["Browser Messaging"]:::browserapi
        DOMAPI["DOM API"]:::browserapi
    end

    %% External Services
    subgraph "External Services"
        VisionAPI["Computer Vision API"]:::external
        BingAPI["Bing TTS API"]:::external
    end

    %% Workflow Arrows
    HTML -->|"1: send scan images message"| Messaging
    Messaging -->|"deliver to content script"| startJS
    startJS -->|"2: scan DOM"| DOMAPI
    startJS -->|"2: send image URLs"| Messaging
    Messaging -->|"deliver to UI"| HTML
    HTML -->|"3: user selects image"| DashboardTS
    DashboardTS -->|"4: request description"| ClientJS
    ClientJS -->|"5: HTTP POST with image URL"| VisionAPI
    VisionAPI -->|"6: returns description"| ClientJS
    ClientJS -->|"7: send to TTS Client"| TTS_JS
    TTS_JS -->|"8a: HTTP to Bing TTS"| BingAPI
    TTS_JS -->|"8b: fallback Web Speech"| WebSpeech
    TTS_JS -->|"9: playback control"| HTML

    %% Click Events
    click Manifest "https://github.com/davrous/dareangel/blob/master/manifest.json"
    click startTS "https://github.com/davrous/dareangel/blob/master/start.ts"
    click startJS "https://github.com/davrous/dareangel/blob/master/start.js"
    click HTML "https://github.com/davrous/dareangel/blob/master/dashboard.html"
    click CSS "https://github.com/davrous/dareangel/blob/master/dashboard.css"
    click DashboardTS "https://github.com/davrous/dareangel/blob/master/dareangel.dashboard.ts"
    click ClientTS "https://github.com/davrous/dareangel/blob/master/dareangel.client.ts"
    click ClientJS "https://github.com/davrous/dareangel/blob/master/dareangel.client.js"
    click TTS_TS "https://github.com/davrous/dareangel/blob/master/BingTTSClient.ts"
    click TTS_JS "https://github.com/davrous/dareangel/blob/master/BingTTSClient.js"
    click TSDecl "https://github.com/davrous/dareangel/tree/master/dts/"
    click TSConfig "https://github.com/davrous/dareangel/blob/master/tsconfig.json"

    %% Styles
    classDef ui fill:#D0E7FF,stroke:#0366d6,stroke-width:1px
    classDef logic fill:#DFFFD0,stroke:#228B22,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#d2691e,stroke-width:1px
    classDef browserapi fill:#E0E0E0,stroke:#666666,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#999999,stroke-width:1px
    classDef declaration fill:#F9E79F,stroke:#B7950B,stroke-width:1px
```
