# nrednav/youtube-playlist-duration-calculator architecture

> Architecture diagram of the GitHub repository nrednav/youtube-playlist-duration-calculator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nrednav/youtube-playlist-duration-calculator
- Repository: https://github.com/nrednav/youtube-playlist-duration-calculator

## Overview

##### Project Type & Purpose
- This is a browser extension (targeting Chrome and Firefox) intended to calculate and display the total duration of a YouTube playlist. It also provides sorting functionality for playlists (by duration, channel name, index, views, and upload date) and supports multiple locales.
- The extension interacts with YouTube pages by integrating its functionality into the page (for example, adding duration information to the playlist overview).

##### File Structure
- Top-Level Files:
- Configuration files (.env.*, .eslintrc, jsconfig.json, package.json, pnpm-lock.yaml, and vite.config.js) indicate that the project is built with a modern JavaScript toolchain and uses Vite as its bundler.
- The presence of directories like “public” (with localization files) and “src” (with code logic) clearly separates static assets from application logic.
- Source Code:
- The “src” directory contains the main application code.
- The “src/manifest.json” file signals that this is a browser extension by defining the extension properties for browsers.
- The “src/modules/sorting” directory includes several subdirectories for different sorting strategies (by channel name, duration, index, upload date, and views). Each sorting module has its own index and parser files reflecting a modular (possibly Strategy Pattern) design.
- A “src/shared” directory with utility files (like logger.js, timestamp.js, and element-selectors.js) delivers common functionality.
- Documentation & Testing:
- The “docs” directory contains additional information about testing and translations.
- Screenshots provide UI design hints and are referenced from the README.

##### Key Components
a. Extension Frontend/UI:
- User interface elements as they are injected or interact with YouTube’s page (this is managed through the code in “src/main.js” and “src/main.css”).
- Integration with YouTube playlist overview pages.
b. Sorting Modules:
▪ Sort by Channel Name
▪ Sort by Duration
▪ Sort by Index
▪ Sort by Upload Date (with associated parser files per locale)
▪ Sort by Views (where supported)
- That these modules share a common interface or strategy design pattern to enable different sorting rules.
c. Shared Utilities:
d. Localization:
- “Public/Locales” directory as a component that handles internationalization. Show how locale messages (in multiple languages – en, es, pt, zh, etc.) feed into the UI.
e. Build & Development Pipeline:
- A component for the build process. Indicate that Vite (configured via vite.config.js) and scripts mediated by pnpm are used to build and package the extension.
- Mention the environment variable (VITE_TARGET_BROWSER) to clarify the dual builds for Chrome and Firefox.
f. External Interactions:
- Relationship with the YouTube website as an external system from which data (e.g., playlist information) is processed.
- Optionally, note browser-specific APIs the extension relies on (from manifest.json).

##### Relationships & Interactions
- From the YouTube page (external system) into the extension’s content scripts.
- From the main UI component to the Sorting Modules, illustrating that when a user uses the sorting function the corresponding module handles the algorithm.
- From the Sorting Modules back to the UI to display sorted results.
- Shared Utilities (e.g., logging and timestamp) are invoked by both the main UI and the sorting strategies.

##### Architectural Patterns & Design Principles
- Modular design of sorting functionalities – this is akin to the Strategy Pattern where different sorting algorithms are interchangeable.
- Separation of concerns:
- Business logic (sorting, duration calculation) is isolated in “src/modules/sorting”.
- Common utilities are separated in the “src/shared” directory.
- Localization is completely separate in the “public/_locales” folder.
- How development and deployment (through pnpm, Vite, and build scripts) integrate with the overall architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("YouTube (External)"):::external

    %% Extension Frontend/UI
    subgraph "Extension Frontend/UI"
        B("UI/Content Script"):::ui
    end

    %% Sorting Modules
    subgraph "Sorting Modules"
        C1("Sort by Channel Name"):::sorting
        C2("Sort by Duration"):::sorting
        C3("Sort by Index"):::sorting
        C4("Sort by Upload Date"):::sorting
        C41("Upload Date Parsers"):::sorting
        C5("Sort by Views"):::sorting
        C51("Views Parsers"):::sorting
    end

    %% Shared Utilities
    subgraph "Shared Utilities"
        D1("Logger"):::utilities
        D2("Timestamp"):::utilities
        D3("Element Selectors"):::utilities
    end

    E("Localization"):::localization

    %% Build & Deployment Pipeline
    subgraph "Build & Deployment"
        F1("Vite Config"):::build
        F2("Env Config"):::build
        F3("Package Manager"):::build
    end

    %% Relationships & Data Flow
    A -->|"playlist_data"| B

    B -->|"invoke_sorting"| C1
    B -->|"invoke_sorting"| C2
    B -->|"invoke_sorting"| C3
    B -->|"invoke_sorting"| C4
    B -->|"invoke_sorting"| C5

    C4 -->|"parsers"| C41
    C5 -->|"parsers"| C51

    C1 -->|"return_sorted"| B
    C2 -->|"return_sorted"| B
    C3 -->|"return_sorted"| B
    C4 -->|"return_sorted"| B
    C5 -->|"return_sorted"| B

    %% Shared Utilities used by UI and Sorting Modules
    B -->|"utilizes"| D1
    B -->|"utilizes"| D2
    B -->|"utilizes"| D3
    C1 -->|"utilizes"| D1
    C1 -->|"utilizes"| D2
    C1 -->|"utilizes"| D3
    C2 -->|"utilizes"| D1
    C2 -->|"utilizes"| D2
    C2 -->|"utilizes"| D3
    C3 -->|"utilizes"| D1
    C3 -->|"utilizes"| D2
    C3 -->|"utilizes"| D3
    C4 -->|"utilizes"| D1
    C4 -->|"utilizes"| D2
    C4 -->|"utilizes"| D3
    C5 -->|"utilizes"| D1
    C5 -->|"utilizes"| D2
    C5 -->|"utilizes"| D3

    %% Localization provides messages to UI
    E -->|"provides"| B

    %% Build & Deployment builds major components
    F1 -->|"builds"| B
    F2 -->|"builds"| B
    F3 -->|"builds"| B
    F1 -->|"builds"| C1
    F2 -->|"builds"| C1
    F1 -->|"builds"| D1
    F2 -->|"builds"| D1
    F1 -->|"builds"| E
    F2 -->|"builds"| E

    %% Click Events for Extension Frontend/UI
    click B "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/src/main.js"

    %% Click Events for Sorting Modules
    click C1 "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/src/modules/sorting/sort-by-channel-name/index.js"
    click C2 "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/src/modules/sorting/sort-by-duration/index.js"
    click C3 "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/src/modules/sorting/sort-by-index/index.js"
    click C4 "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/src/modules/sorting/sort-by-upload-date/index.js"
    click C41 "https://github.com/nrednav/youtube-playlist-duration-calculator/tree/main/src/modules/sorting/sort-by-upload-date/parsers/"
    click C5 "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/src/modules/sorting/sort-by-views/index.js"
    click C51 "https://github.com/nrednav/youtube-playlist-duration-calculator/tree/main/src/modules/sorting/sort-by-views/parsers/"

    %% Click Events for Shared Utilities
    click D1 "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/src/shared/modules/logger.js"
    click D2 "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/src/shared/modules/timestamp.js"
    click D3 "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/src/shared/data/element-selectors.js"

    %% Click Event for Localization
    click E "https://github.com/nrednav/youtube-playlist-duration-calculator/tree/main/public/_locales/"

    %% Click Events for Build & Deployment
    click F1 "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/vite.config.js"
    click F2 "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/.env.chrome"
    click F3 "https://github.com/nrednav/youtube-playlist-duration-calculator/blob/main/package.json"

    %% Styles
    classDef external fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef ui fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef sorting fill:#f94144,stroke:#333,stroke-width:2px;
    classDef utilities fill:#577590,stroke:#fff,stroke-width:2px;
    classDef localization fill:#277da1,stroke:#fff,stroke-width:2px;
    classDef build fill:#f3722c,stroke:#333,stroke-width:2px;
```
