# m1dugh/rosettastonks architecture

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

- Interactive diagram: https://gitdiagram.com/m1dugh/rosettastonks
- Repository: https://github.com/m1dugh/rosettastonks

## Overview

##### Project Type and Purpose
- Rosetta Stonks is a **browser extension** (Chrome & Firefox) that hooks into the Rosetta Stone web app to automate “add time” and “validate lesson” actions.
- Key indicators: `chrome/manifest.json`, `mozilla/manifest.json`, `src/frontend` (React UI), `src/worker` (background service worker), build & packaging instructions in README.

##### File-Structure Analysis
- Top-level:
- `chrome/`, `mozilla/`: per-browser manifests
- `src/frontend`: React/TypeScript popup UI & service module
- `src/worker`: background worker logic for network interception & tab messaging
- `src/lib`: shared utility code (env, request wrappers, product definitions)
- `static`: HTML/CSS assets for the popup page
- `scripts/package.ts`: packaging helper
- Build configs: `deno.json`, `Makefile`, Nix flake files
- Architectural choice: extension splits into **UI layer** (popup), **background layer** (service worker), and **shared library** code.

##### Insights from README
- Two separate build flows: `deno task build:worker` → `/dist/worker.esm.js`, and `deno task build:frontend` → `/dist/frontend.esm.js`.
- Packaging targets: `make chrome` yields Chrome CRX folder, `make firefox` yields XPI.
- User flows: the popup UI calls into the worker via the Service Worker Messaging API; the worker intercepts fetch requests to Rosetta Stone endpoints (`src/worker/request.ts`).

a. Main Components
- Browser Host
- Extension Popup (frontend)
- Background Service Worker
- Shared Library Module
- Rosetta Stone Website (external web app/API)
- Build/CI Pipeline (Deno, Make, GitHub Actions)
b. Relationships & Data Flows
2. UI calls `service.ts` → uses `chrome.runtime.sendMessage` / `browser.runtime.sendMessage` → **Service Worker** (`src/worker/index.ts`).
3. Service Worker monitors network via `fetch` event handlers (`worker/request.ts`), logs Rosetta Stone API calls, and persists state if needed.
4. Worker communicates with active tab scripts (`worker/tab.ts`) to coordinate page actions (click “ignore”, “resolve”, etc.).
5. Both UI and Worker import common code from `src/lib` for environment config (`env.ts`), request helpers (`request.ts`), and product definitions (`product.ts`).
6. Packaging pipeline: Deno bundles → outputs ESM in `/dist` → Makefile assembles extension bundle → GitHub Actions releases artifacts.
c. Architectural Patterns & Principles
- **Separation of Concerns**: UI vs. background logic vs. shared code
- **Messaging Pattern**: popup ↔ service worker ↔ content/tab script
- **Interceptor Pattern**: service worker intercepts network requests
- **Modular Build**: Deno tasks + Make + CI workflows
d. Key Technologies & Frameworks
- Deno & TypeScript
- React (TSX) for popup UI
- Web Extension APIs (`chrome.*` / `browser.*`)
- Nix flakes for reproducible builds
- GitHub Actions for release automation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::user -->|click extension icon| UI

    %% Browser Extension Components
    subgraph "Browser" 
        direction TB
        UI["Popup UI"]:::ui
        SW["Background Service Worker"]:::sw
    end

    %% Shared Library
    Lib["Shared Library"]:::lib

    %% External System
    API["Rosetta Stone API"]:::external

    %% Build & CI Pipeline
    subgraph "Build & Packaging Pipeline"
        direction TB
        Deno["Deno Tasks"]:::build
        Dist["/dist"]:::build
        Make["Makefile"]:::build
        CI["GitHub Actions"]:::build
    end

    %% Documentation & Metadata
    subgraph "Documentation & Metadata"
        direction TB
        Doc1["README.md"]:::doc
        Doc2["CHANGELOG.md"]:::doc
        Doc3["CONTRIBUTING.md"]:::doc
        Doc4["INSTALL_GUI.md"]:::doc
        Doc5["SECURITY.md"]:::doc
        Doc6["LICENSE"]:::doc
        Doc7[".gitignore"]:::doc
        Doc8[".github/ISSUE_TEMPLATE"]:::doc
        Doc9[".github/ISSUE_TEMPLATE/bug_report.md"]:::doc
    end

    %% Browser Manifests
    subgraph "Browser Extension Manifests"
        direction TB
        Man1["chrome/manifest.json"]:::manifest
        Man2["mozilla/manifest.json"]:::manifest
    end

    %% Relationships
    UI -->|runtime.sendMessage| SW
    SW -->|"fetch intercept"| API
    UI -->|"imports"| Lib
    SW -->|"imports"| Lib
    Deno --> Dist --> Make --> CI
    Man1 --> UI
    Man1 --> SW
    Man2 --> UI
    Man2 --> SW

    %% Files under Popup UI
    subgraph "Popup UI Files" 
        direction TB
        F1["static/index.html"]:::ui
        F2["static/style.css"]:::ui
        F3["src/frontend/index.tsx"]:::ui
        F4["src/frontend/components/ErrorBanner.tsx"]:::ui
        F5["src/frontend/components/MissingFeatureBanner.tsx"]:::ui
        F6["src/frontend/components/TimeForm.tsx"]:::ui
        F7["src/frontend/components/ValidateForm.tsx"]:::ui
        F8["src/frontend/service.ts"]:::ui
    end
    UI --> F1
    UI --> F2
    UI --> F3
    UI --> F4
    UI --> F5
    UI --> F6
    UI --> F7
    UI --> F8

    %% Files under Service Worker
    subgraph "Service Worker Files"
        direction TB
        W1["src/worker/index.ts"]:::sw
        W2["src/worker/request.ts"]:::sw
        W3["src/worker/tab.ts"]:::sw
    end
    SW --> W1
    SW --> W2
    SW --> W3

    %% Files under Shared Library
    subgraph "Shared Library Files"
        direction TB
        L1["src/lib/env.ts"]:::lib
        L2["src/lib/product.ts"]:::lib
        L3["src/lib/request.ts"]:::lib
    end
    Lib --> L1
    Lib --> L2
    Lib --> L3

    %% Files under Build & Packaging
    subgraph "Build Files"
        direction TB
        B1["deno.json"]:::build
        B2["deno.lock"]:::build
        B3["Makefile"]:::build
        B4["flake.nix"]:::build
        B5["flake.lock"]:::build
        B6["scripts/package.ts"]:::build
        B7[".github/workflows/release.yml"]:::build
    end
    Deno --> B1
    Deno --> B2
    Make --> B3
    Make --> B4
    Make --> B5
    Make --> B6
    CI --> B7

    %% Click Events for Popup UI
    click F1 "https://github.com/m1dugh/rosettastonks/blob/master/static/index.html"
    click F2 "https://github.com/m1dugh/rosettastonks/blob/master/static/style.css"
    click F3 "https://github.com/m1dugh/rosettastonks/blob/master/src/frontend/index.tsx"
    click F4 "https://github.com/m1dugh/rosettastonks/blob/master/src/frontend/components/ErrorBanner.tsx"
    click F5 "https://github.com/m1dugh/rosettastonks/blob/master/src/frontend/components/MissingFeatureBanner.tsx"
    click F6 "https://github.com/m1dugh/rosettastonks/blob/master/src/frontend/components/TimeForm.tsx"
    click F7 "https://github.com/m1dugh/rosettastonks/blob/master/src/frontend/components/ValidateForm.tsx"
    click F8 "https://github.com/m1dugh/rosettastonks/blob/master/src/frontend/service.ts"

    %% Click Events for Service Worker
    click W1 "https://github.com/m1dugh/rosettastonks/blob/master/src/worker/index.ts"
    click W2 "https://github.com/m1dugh/rosettastonks/blob/master/src/worker/request.ts"
    click W3 "https://github.com/m1dugh/rosettastonks/blob/master/src/worker/tab.ts"

    %% Click Events for Shared Library
    click L1 "https://github.com/m1dugh/rosettastonks/blob/master/src/lib/env.ts"
    click L2 "https://github.com/m1dugh/rosettastonks/blob/master/src/lib/product.ts"
    click L3 "https://github.com/m1dugh/rosettastonks/blob/master/src/lib/request.ts"

    %% Click Events for Manifests
    click Man1 "https://github.com/m1dugh/rosettastonks/blob/master/chrome/manifest.json"
    click Man2 "https://github.com/m1dugh/rosettastonks/blob/master/mozilla/manifest.json"

    %% Click Events for Build & Packaging
    click B1 "https://github.com/m1dugh/rosettastonks/blob/master/deno.json"
    click B2 "https://github.com/m1dugh/rosettastonks/blob/master/deno.lock"
    click B3 "https://github.com/m1dugh/rosettastonks/tree/master/Makefile"
    click B4 "https://github.com/m1dugh/rosettastonks/blob/master/flake.nix"
    click B5 "https://github.com/m1dugh/rosettastonks/blob/master/flake.lock"
    click B6 "https://github.com/m1dugh/rosettastonks/blob/master/scripts/package.ts"
    click B7 "https://github.com/m1dugh/rosettastonks/blob/master/.github/workflows/release.yml"

    %% Click Events for Documentation
    click Doc1 "https://github.com/m1dugh/rosettastonks/blob/master/README.md"
    click Doc2 "https://github.com/m1dugh/rosettastonks/blob/master/CHANGELOG.md"
    click Doc3 "https://github.com/m1dugh/rosettastonks/blob/master/CONTRIBUTING.md"
    click Doc4 "https://github.com/m1dugh/rosettastonks/blob/master/INSTALL_GUI.md"
    click Doc5 "https://github.com/m1dugh/rosettastonks/blob/master/SECURITY.md"
    click Doc6 "https://github.com/m1dugh/rosettastonks/tree/master/LICENSE"
    click Doc7 "https://github.com/m1dugh/rosettastonks/blob/master/.gitignore"
    click Doc8 "https://github.com/m1dugh/rosettastonks/tree/master/.github/ISSUE_TEMPLATE"
    click Doc9 "https://github.com/m1dugh/rosettastonks/blob/master/.github/ISSUE_TEMPLATE/bug_report.md"

    %% Styles
    classDef ui fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef sw fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef lib fill:#f0f4c3,stroke:#827717,color:#827717;
    classDef external fill:#eeeeee,stroke:#616161,color:#616161;
    classDef build fill:#fff9c4,stroke:#f57f17,color:#f57f17;
    classDef manifest fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef doc fill:#d7ccc8,stroke:#4e342e,color:#4e342e;
    classDef user fill:#ffe082,stroke:#ff6f00,color:#ff6f00;
```
