# some1sm/tunetransporter architecture

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

- Interactive diagram: https://gitdiagram.com/some1sm/tunetransporter
- Repository: https://github.com/some1sm/tunetransporter

## Overview

##### Project Type & Purpose
- TuneTransporter is a Chrome extension focused on redirecting music links between Spotify and YouTube Music.
- Its main goal is to automatically send users from one streaming service’s URL (Spotify or YouTube Music) to equivalent search results on the other service, with toggles available in a popup for controlling redirection behavior.

##### File Structure
- Key Files & Directories:
- manifest.json: The configuration file that defines the extension’s permissions, background service worker, content scripts, and popup.
- service-worker.js: Acts as the background script for persistent tasks and possibly managing notifications or redirection conditions.
- Content Scripts: Files like spotify2ytm-content.js, ytm2spotify-content.js, yt-fallback-content.js are responsible for detecting page states in Spotify and YouTube Music, extracting necessary data, and executing redirections.

##### Components and Their Interactions
- Main Components:
- Popup Interface: UI defined by popup.html, popup.css, and popup.js. It provides toggles to enable or disable specific redirection directions and saves settings (using the Chrome storage API).
- Content Scripts: These are injected into matching pages on Spotify and YouTube Music. They have distinct roles:
⁃ spotify2ytm-content.js: Handles redirection from Spotify to YouTube Music.
⁃ ytm2spotify-content.js: Handles redirection from YouTube Music to Spotify.
⁃ yt-fallback-content.js: Provides backup extraction logic if the primary method fails.
- Background Service Worker: (service-worker.js) May manage persistent tasks like listening for events, background data handling, and coordinating communication between content scripts and the popup.
- Manifest & Configuration: (manifest.json) Serves as the foundation for permissions (activeTab, storage) and registers the above components.

- Relationships & Data Flow:
- The user interacts with the Popup Interface to set redirection preferences. These settings are stored using Chrome’s storage.
- When the user navigates to a supported page (Spotify or YouTube Music), the corresponding content script runs – extracting page data and performing redirection based on the saved settings.
- The content scripts may sometimes communicate with the background service worker (if applicable) for tasks like timing notifications or handling errors (e.g., when redirection fails).
→ User Interaction flowing into Popup Interface.
→ Popup saving preferences via the storage API.
→ Content Scripts initiating on page load, reading stored settings, and performing extraction and redirection.
→ Fallback logic (from secondary content scripts) operating when required.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The system cleanly separates UI (popup) from the content processing (content scripts) and background tasks (service worker).
- Modular Components: Each content script handles redirection in a specific context (Spotify vs. YouTube Music), making it easy to extend or update individual parts.
- Event-driven Communication: Interaction between the popup and content scripts likely involves event listeners and callbacks, indicating a decoupled design.

##### Essential Elements
- Communication from the Popup to the Storage (saving preferences).
- Flow of content script activation upon page load.
- Data flow between content scripts and the Service Worker (if notifications or background processes are involved).

##### Summary
- UI (Popup) where settings are managed.
- Content Scripts that perform extraction and redirection logic.
- Background Service Worker for handling notifications or intermediary tasks.
- The manifest tying these pieces together with Chrome-specific permissions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction Layer"
        U("User"):::ui
        Popup("Popup Interface"):::ui
        Storage("Chrome Storage API"):::storage
    end

    %% Content Processing Layer
    subgraph "Content Processing Layer"
        Spotify("spotify2ytm-content.js"):::script
        YTM("ytm2spotify-content.js"):::script
        Fallback("yt-fallback-content.js"):::script
    end

    %% Background Processing Layer
    subgraph "Background Processing Layer"
        Service("Service Worker"):::bg
    end

    %% Configuration Layer
    subgraph "Configuration"
        Manifest("Manifest & Configuration"):::config
    end

    %% Connections
    U -->|"setsPreferences"| Popup
    Popup -->|"savesPreferences"| Storage
    Storage -->|"providesSettings"| Spotify
    Storage -->|"providesSettings"| YTM
    Storage -->|"providesSettings"| Fallback
    Spotify -->|"sendsEvents"| Service
    YTM -->|"sendsEvents"| Service
    Fallback -->|"fallbackEvents"| Service
    Manifest -->|"definesPopup"| Popup
    Manifest -->|"definesService"| Service
    Manifest -->|"definesContentScript"| Spotify
    Manifest -->|"definesContentScript"| YTM
    Manifest -->|"definesContentScript"| Fallback

    %% Click Events
    click Popup "https://github.com/some1sm/tunetransporter/blob/master/popup.html"
    click Popup "https://github.com/some1sm/tunetransporter/blob/master/popup.css"
    click Popup "https://github.com/some1sm/tunetransporter/blob/master/popup.js"
    click Spotify "https://github.com/some1sm/tunetransporter/blob/master/spotify2ytm-content.js"
    click YTM "https://github.com/some1sm/tunetransporter/blob/master/ytm2spotify-content.js"
    click Fallback "https://github.com/some1sm/tunetransporter/blob/master/yt-fallback-content.js"
    click Service "https://github.com/some1sm/tunetransporter/blob/master/service-worker.js"
    click Manifest "https://github.com/some1sm/tunetransporter/blob/master/manifest.json"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1B4F72,stroke-width:2px
    classDef storage fill:#F9E79F,stroke:#B7950B,stroke-width:2px
    classDef script fill:#A9DFBF,stroke:#1E8449,stroke-width:2px
    classDef bg fill:#F5B7B1,stroke:#922B21,stroke-width:2px
    classDef config fill:#D2B4DE,stroke:#6C3483,stroke-width:2px
```
