How m1dugh/rosettastonks works
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